Should we gitignore the .python-version file?

by

While being too specific, you can still version that file (meaning: not include it in the default .gitignore), as :

  • it will be used only by pyenv
    (and, as noted by diavol in the comments, setup-python GitHub Action uses this file to set the python version of the build environment)
  • it is a good addition to the README, in order to illustrate what version of python is recommended for the specific project,
  • it can be overridden easily (if you are using pyenv), or simply ignored (if you don’t have pyenv).

As the article “How to manage multiple Python versions and virtual environments” states:

When setting up a new project that is to use Python 3.6.4 then pyenv local 3.6.4 would be ran in its root directory.
This would both set the version, and create a .python-version file, so that other contributors’ machines would pick it up.

But:

pyenv looks in four places to decide which version of Python to use, in priority order:

  1. The PYENV_VERSION environment variable (if specified).
    You can use the pyenv shell command to set this environment variable in your current shell session.
  2. The application-specific .python-version file in the current directory (if present).
    You can modify the current directory’s .python-version file with the pyenv local command.
  3. The first .python-version file found (if any) by searching each parent directory, until reaching the root of your filesystem.
  4. The global version file. You can modify this file using the pyenv global command.
    If the global version file is not present, pyenv assumes you want to use the “system” Python. (In other words, whatever version would run if pyenv weren’t in your PATH.)

None of these listed reasons indicate why .python-version should not be stored in source control.
You can still have a section in the README saying that the version to be used is specified in the .python-version file.

  • If someone is using pyenv it works automatically for them.
  • If not, then they’re in no worse of a position than they were if .python-version was not under source control.

True: Keeping the .python-version file under source control does ensure that pyenv users have an automatic reference point for the Python version to be used, which could streamline the setup process for them. Moreover, it serves as a documented specification of the Python version for those who do not use pyenv, assuming they are informed via the README or other documentation that they should refer to this file for the Python version information.

However, one potential issue with storing the .python-version file in source control could be the risk of unwanted modifications. Developers might accidentally commit changes to the .python-version file as they switch between different Python versions in their local development environment, potentially leading to conflicts or confusion among the team.

To mitigate this risk, a possible strategy would be to include clear guidelines in the README on how to handle the .python-version file. That might include instructions to avoid committing changes to the file unless a deliberate decision has been made to update the Python version used by the project.

But if you have to rely on README, I would instead put in that file instructions to activate a content filter driver, using a .gitattributes declaration.

smudge

(image from “Customizing Git – Git Attributes“, from “Pro Git book“)

  • .gitignore

    .python-version

  • .gitattributes

    .python-version filter=smudgeScript

  • instructions to activate the content filter driver:

    git config filter.smudgeScript.smudge /path/to/your/smudgeScript
git config filter.smudgeScript.clean "cat python-version.tpl"

And now, any checkout/clone would restore the right .python-version while avoiding any unwanted modification in it.

Leave a Comment