What files/directories should I add to .gitignore when using Poetry, the Python package manager?

Question

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?

Answer 1

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.