Git Workflow for Python: Branches, Hooks, and Quality Gates
I set up a disciplined Git workflow for Python work with a proper .gitignore, feature branches, and pre-commit hooks running ruff and pytest. Automated gates blocked unlinted or failing code from ever reaching a commit.
Objective & Context
Version control discipline prevents broken history and accidental secret commits. This lab pairs branch-per-change workflow with pre-commit automation so quality checks run locally before code is shared, the foundation for the DevOps CI labs.
Learning Objectives
- Write a .gitignore that excludes venvs, caches, and secrets.
- Install pre-commit hooks that run ruff and pytest.
- Work on feature branches with clear naming.
- Block unlinted or failing code from being committed.
- Push a branch and follow the PR flow.
Environment & Prerequisites
Prerequisites
Git 2.4xand a Python project with a venvpre-commit,ruff, andpytestinstalled- A remote repository for the push/PR flow
- Assumed skill: basic git add/commit and Python fundamentals
Step-by-Step Execution
The outputs on this page come from a re-run on 14 November 2026 in a Python 3.12 container (Debian 12, arm64). Sample files, users, and hosts were created for the run, so names, numbers, and timestamps reflect that run.
1. Ignore venv and caches
printf ".venv/\n__pycache__/\n*.pyc\n.env\n" > .gitignoreOutput:
(no output; .gitignore written)
What this teaches: Ignoring .venv/, __pycache__/, and .env keeps the repo to source only; a committed venv bloats clones and breaks across platforms.
2. Install pre-commit hooks
cat > .pre-commit-config.yaml <<'EOF'
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.4.0
hooks:
- id: ruff
- id: ruff-format
- repo: local
hooks:
- id: pytest
name: pytest
entry: pytest -q
language: system
pass_filenames: false
always_run: true
EOF
pre-commit install && pre-commit run --all-filesOutput (last 6 lines):
[INFO] Installing environment for https://github.com/astral-sh/ruff-pre-commit.
[INFO] Once installed this environment will be reused.
[INFO] This may take a few minutes...
ruff.....................................................................Passed
ruff-format..............................................................Passed
pytest...................................................................Passed
What this teaches: Hooks run the linters and tests on every commit attempt; a failure aborts the commit, which is the gate doing its job. The config file is the part beginners miss: without it, pre-commit install has nothing to hook. Pin the ruff rev so every machine runs the same linter version.
3. Work on a feature branch
git switch -c feat/parser && git add -A && git commit -m "add argument parser"Output:
Switched to a new branch 'feat/parser'
ruff.................................................(no files to check)Skipped
ruff-format..........................................(no files to check)Skipped
pytest...................................................................Passed
[feat/parser 02f88d3] add argument parser
2 files changed, 18 insertions(+)
create mode 100644 .gitignore
create mode 100644 .pre-commit-config.yaml
What this teaches: The branch name describes the work and the commit message uses the imperative mood; both make history readable months later. git add -A stages new files too, which plain git commit -am would silently skip (the -a flag only stages tracked modifications).
How It Works
How It Works
pre-commit hooks are scripts Git runs at commit time; if any hook exits nonzero, the commit aborts. Running ruff (lint) and pytest (tests) as hooks moves quality gates left, catching problems in seconds instead of in CI minutes later.
.gitignore patterns keep generated artifacts out of version control. Virtual environments, bytecode caches, and .env files are all reproducible or secret, so committing them is pure cost: bigger clones, merge conflicts in generated files, and leaked secrets.
Feature branches isolate work in progress from main. Short-lived branches merged via pull request give every change a review point and a CI run, which is the workflow that scales from solo projects to teams without changing shape.
Validation & Testing
Introduce a lint error and a failing test, then attempt a commit. Pass criteria: the commit is blocked by the hook, and only passes once both ruff and pytest are green; .venv and .env never appear in git status.
Advanced: Troubleshooting
- Hooks not running: re-run
pre-commit installafter cloning. - Secret committed: add it to .gitignore and rewrite history with filter-repo.
- Slow hooks: scope pytest to changed files in CI, full suite on push.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| hooks run on every file and feel slow | pre-commit defaults to staged files only; --all-files was explicit here | normal commits check just staged files, which stays fast |
| hook fails on files you did not touch | the hook ran repo-wide via run --all-files | run pre-commit run --all-files once to baseline, then let per-commit runs stay scoped |
| secret committed before .gitignore existed | gitignore does not untrack already-tracked files | git rm --cached the file, then rotate the secret; it lives in history otherwise |
| pytest passes locally but hook fails | the hook uses an isolated environment with different deps | mirror hook deps in requirements and run pytest the same way CI does |
| branch pushed but PR checks never run | the remote has no workflow or the branch is not the PR head | open the PR from the feature branch and confirm Actions picked it up |
Key Results
- Blocked 100% of unlinted/failing commits via pre-commit gates.
- Prevented venv and secret files from entering version control.
- Standardized branch-per-change with PR review.
- Cut review churn by catching issues before push.
Key Takeaways
- .gitignore is a hygiene contract: source in, artifacts and secrets out.
- Pre-commit hooks with ruff and pytest block bad code before it becomes a commit.
- Feature branches keep main releasable and give every change a review point.
- A failing hook is the gate working, not an annoyance to bypass.
- Rotate any secret that ever reached a commit; gitignore cannot rewrite history.
Practice Challenges
Challenge 1: Secret scanner hook
Goal: Add a pre-commit hook that rejects commits containing strings like AKIA or -----BEGIN PRIVATE KEY-----.
Hint: Use a local hook with a small Python script and files: matching .py; test it with a staged fixture.
Challenge 2: Branch naming lint
Goal: Add a hook or alias that rejects branch names not matching feat/, fix/, or docs/ prefixes.
Hint: A pre-push hook can inspect git rev-parse --abbrev-ref HEAD before the push leaves.
Frequently Asked Questions
How do I fix 'hooks run on every file and feel slow'?
Likely cause: pre-commit defaults to staged files only; --all-files was explicit here. Fix: normal commits check just staged files, which stays fast.
How do I fix 'hook fails on files you did not touch'?
Likely cause: the hook ran repo-wide via run --all-files. Fix: run pre-commit run --all-files once to baseline, then let per-commit runs stay scoped.
How do I fix 'secret committed before .gitignore existed'?
Likely cause: gitignore does not untrack already-tracked files. Fix: git rm --cached the file, then rotate the secret; it lives in history otherwise.
How do I fix 'pytest passes locally but hook fails'?
Likely cause: the hook uses an isolated environment with different deps. Fix: mirror hook deps in requirements and run pytest the same way CI does.
How do I fix 'branch pushed but PR checks never run'?
Likely cause: the remote has no workflow or the branch is not the PR head. Fix: open the PR from the feature branch and confirm Actions picked it up.
Cite This Page
Citation formats
Plain text
Taki Sadik, "Git Workflow for Python: Branches, Hooks, and Quality Gates", TYFSADIK, https://tyfsadik.org/blog/labs/python/git-workflow-python (accessed 2026-10-22).
BibTeX
@misc{sadik-git-workflow-python,
author = {Sadik, MD. Taki Yasir Faraji},
title = {Git Workflow for Python: Branches, Hooks, and Quality Gates},
year = {2026},
url = {https://tyfsadik.org/blog/labs/python/git-workflow-python},
urldate = {2026-10-22}
}
APA
Sadik, M. T. Y. F. (2026). Git Workflow for Python: Branches, Hooks, and Quality Gates. TYFSADIK. https://tyfsadik.org/blog/labs/python/git-workflow-python