19

I'm using a very new Python package manager called Poetry.

It creates several files/directories upon creating a new project (environment), but I'm not sure which one I should add to .gitignore for the best practice.

Say I create a new poetry project by doing this: 

$ poetry new foo_project
$ cd foo_project
$ poetry add numpy
$ ls

There are:

tests (directory)
foo_project (also a directory)
pyproject.toml (a file that specifies installed packages)
poetry.lock (a lock file of installed packages)
README.rst (I don't know why README is created but it just shows up.)

I usually add tests/, foo_project/, poetry.lock and README.rst because they seem to be dependent on the machine the project was created. Also, I seem to be able to reproduce the environment only with pyproject.toml so that's another reason I ignored all other files/directories.

However, it's just my hunch and unfortunately, I can't find any official guide what I really should add to .gitignore on the official documentation.

It just bugs me that I don't know for sure what I'm doing. Which ones should I add to my .gitignore?

user8491363
  • 2,924
  • 5
  • 19
  • 28

1 Answers1

17

Also moved to poetry quite recently.

I would say you should not add any of: tests/, foo_project/, poetry.lock or README.rst to your .gitignore. In other words, those files and folders should be in version control. My reasons are as follows:

tests/ - your tests should not be machine dependent (unless this is a know limitation of your package) and providing the tests for others is how they test a) the installation has worked and b) any changes they make don't break past features, so a pull request becomes more robust.

foo_project/ - this is where your python module goes! All you .py files should be inside this folder if you want poetry to be able to build and publish your package.

poetry.lock - see https://python-poetry.org/docs/basic-usage/ where it says:

When Poetry has finished installing, it writes all of the packages and the exact versions of them that it downloaded to the poetry.lock file, locking the project to those specific versions. You should commit the poetry.lock file to your project repo so that all people working on the project are locked to the same versions of dependencies (more below).

README.rst - although this one is perhaps more a personal thing, this is the file that becomes your package readme if you use poetry for publishing your package, e.g. to PyPi. Without it you're package will have an empty readme. I have two readmes one .md (for GitHub) and one .rst (for PyPi). I use the GitHub readme for developers/users and the PyPi for pure users.

Mike Williamson
  • 4,915
  • 14
  • 67
  • 104
Chas Nelson
  • 196
  • 1
  • 5
  • Is there a typo? You say "I would say you should not add any of", and then proceed to list things, along with reasons that you _should_ add them. Thanks for the reasoning, btw. – Justin W May 15 '21 at 00:43
  • 3
    That's "should not add any of ... to your .gitignore"? You should add them to your repo, sort of thing. – Chas Nelson May 23 '21 at 19:30
  • Do you likewise have any books on reading comprehension you could recommend me? I seem to be needing it ;) (I read the title of the question and your answer, didn't bother with @user8491363's specifics) – Justin W May 24 '21 at 22:33