Python Git and Python Projects

Commit source: code, tests, configuration (pyproject.toml, lock files), documentation and small sample data. Don't commit anything that can be regenerated or that is specific to one machine or person. A typical Python .gitignore:

# virtual environments
.venv/
# bytecode and caches
__pycache__/
*.pyc
.pytest_cache/
.mypy_cache/
.ruff_cache/
# build output
dist/
build/
*.egg-info/
# local settings and secrets
.env
.vscode/
.idea/

GitHub's github/gitignore repository has a maintained Python.gitignore you can start from.

An ignore rule only affects untracked files. If .env or __pycache__ was committed before you added the rule, Git keeps tracking it. Remove it from the index while keeping the local file with git rm --cached .env, then commit. If a secret was committed, also rotate it, because it remains in the history.

Separate the parts of the project so each has an obvious home:

• src/nature_log/: the importable package. The src layout prevents tests from accidentally importing the local folder instead of the installed package, which catches packaging mistakes early.
• tests/: test files named test_*.py, mirroring the package modules.
• pyproject.toml: metadata, dependencies and tool settings.
• README.md: what the project does and how to set it up and run it.

With the src layout, install the project in your virtual environment in editable mode, python -m pip install -e ., so import nature_log works in tests and scripts. A simpler "flat" layout, with the package folder at the root, is also common for small projects and scripts.

Import behaviour depends on the layout and on how you start Python: python src/nature_log/cli.py and python -m nature_log.cli set up sys.path differently. Running modules with -m from an installed package avoids most ModuleNotFoundError surprises.

A good commit contains one coherent change and explains why it was made:

git add src/nature_log/observations.py tests/test_observations.py
git commit -m "Reject observations with negative bird counts

Counts below zero came from a spreadsheet import bug and broke the
weekly totals. Validation now raises ValueError with the record id."

Commit the fix together with the test that proves it, so they can't drift apart. Keep unrelated changes, such as a reformat or a dependency update, in their own commits; a reviewer can then read each one in isolation, and a problem can be reverted without losing other work.

Use git add -p to stage parts of a file when you've made several changes at once, and git diff --staged to check exactly what you're about to commit. The first line of the message should be a short summary in the imperative ("Reject...", "Add..."), around 50 characters.

Teams usually work on branches: create one for a change, commit there, push it, and open a pull request for review.

git switch -c fix/negative-counts
# edit, test, commit
python -m pytest
ruff check .
git push -u origin fix/negative-counts

Run the project's checks before pushing: tests, linter, formatter and type checker. Continuous integration runs them again on the pull request, across Python versions if configured, so reviewers know the change works before reading it.

A merge without conflicts only means Git could combine the text; it doesn't prove the combined program works. Two branches can each pass their tests and still break when merged, which is why CI runs on the merged result and why tests matter more than a clean merge. Tools such as pre-commit run formatting and lint checks automatically on every commit, catching problems before they reach the shared repository.

Task: create a documented Python project layout with ignore rules, a focused commit and a tested feature branch.

mkdir -p nature-log/src/nature_log nature-log/tests && cd nature-log
git init
printf ".venv/\n__pycache__/\n*.pyc\n.env\n" > .gitignore
printf 'def total(counts):\n    return sum(counts)\n' > src/nature_log/observations.py
touch src/nature_log/__init__.py
printf 'from nature_log.observations import total\n\ndef test_total():\n    assert total([2, 3]) == 5\n' > tests/test_observations.py
git add . && git commit -m "Create project with observation totals and a test"
git switch -c feature/validation

With a minimal pyproject.toml and python -m pip install -e . in a virtual environment, python -m pytest runs the test before you push the branch. For the worked check: should a project normally commit its .venv directory? No. Commit the dependency files and recreate the environment instead.

The Git documentation, GitHub's Python .gitignore template and the packaging guide's src layout discussion are useful references. Continue with interview questions and the Git course. Practise with the Python exercises and Python quiz.