Setup Python Gitignore

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Create or refresh the root .gitignore for a Python project — a universal base plus sections for whatever is actually detected (Django static/media/SQLite paths, a file-based FastAPI database, Sphinx or MkDocs output, notebooks, PDM files, Node tooling, an Antora docs build). It mirrors iru-setup-php-gitignore and iru-setup-typescript-gitignore for the Python ecosystem and never overwrites an existing .gitignore without showing a diff and getting approval.

Purpose

iru-setup-python-gitignore bootstraps a .gitignore that matches what a uv-managed Python project really produces: bytecode, build/ and dist/ output (coverage XML, JUnit results, API docs, uv build artifacts), *.egg-info/, virtual environments (.venv/), pytest/coverage/Hypothesis/tox/nox caches, mypy/Ruff/Pyre/Pytype caches, env files (keeping .env.example), .pypirc, logs, OS/editor noise and the repository-wide .integration-test.lock/ directory. It adds a section only when the thing it targets is present: Django’s STATIC_ROOT/MEDIA_ROOT/db.sqlite3 (read from the settings), a file-based SQLite database for FastAPI, Celery beat files, browser UI test output (.ui-screenshots/ and pytest-playwright’s test-results/ — for a Django project, or any project with pytest-playwright or a tests/ui/ directory; .ui-quality.yml stays tracked), Sphinx or MkDocs build directories, Jupyter checkpoints, PDM local files, root Node tooling, and Antora build output.

It never ignores uv.lock (or poetry.lock/pdm.lock/Pipfile.lock), .python-version or .secrets.baseline — CI installs with uv sync --locked, so those files must be committed — and proposes removing such a line from an existing file. When .gitignore already exists it announces an update, shows the merged draft as a diff, and asks Update (merge, keep hand-added entries) / Keep as is / Replace (template only).

Purpose group

Python Bootstrap

Plugin

Shipped by the iru-python plugin of the ai-catalog marketplace (install with /plugin install iru-python@ai-catalog; see Plugins).

Invocation

/iru-setup-python-gitignore

Optionally with an args block of key: value lines (see below) for scripted runs.

Inputs

Argument Required Description Default

on-existing

No

ask, keep, update or replace — how to treat an existing .gitignore in scripted runs. An orchestrator forwards it only if its own args received it. Other shared keys (such as mode or flavor) are ignored; the flavor is detected from the files themselves.

ask

Outputs

  • A root .gitignore — created from scratch, updated (merged, keeping hand-added lines), or replaced with the template — or left untouched when kept as is.

  • A report stating whether the run was from scratch or an update, the action taken (created / updated / replaced / kept as is, and whether it came from the user’s answer or on-existing), the detected flavor, which conditional sections were included or skipped and why, whether a uv.lock or .python-version ignore line was removed, the git check-ignore result, and which hand-added lines were preserved or dropped.

  • Explicit warnings: review the file before committing (detection is heuristic); run git rm -r --cached manually for anything already tracked under a newly ignored path (rotate credentials if .env or .pypirc was committed); commit uv.lock and .python-version; and which entries were verified versus inferred.

Execution flow

flowchart TD A["Start /iru-setup-python-gitignore"] --> B["Step 0: parse args\n(on-existing)"] B --> C{".gitignore exists?"} C -- no --> D["Step 1: announce creating from scratch"] C -- yes --> E["Step 1: announce updating existing,\nread current content"] E --> F{"on-existing is keep?"} F -- yes --> R["Step 6: report, file untouched"] F -- no --> G D --> G["Step 2: universal Python base template\n(never ignore uv.lock, .python-version)"] G --> H["Step 3: detect flavor and add sections\nDjango, FastAPI, Sphinx, MkDocs, Jupyter,\nPDM, Node, Antora"] H --> I["Step 4: compose merged draft\nand template-only draft"] I --> J{"Existing file?"} J -- no --> W["Step 6: write .gitignore"] J -- yes --> K["Step 5: show diff"] K --> L{"on-existing update or replace?"} L -- yes --> W L -- no --> M{"AskUserQuestion:\nUpdate, Keep as is, Replace"} M -- Update or Replace --> W M -- Keep as is --> R W --> V["Verify with git check-ignore"] V --> R R --> S["Report mode, action, flavor,\nsections, warnings"]

Dependencies

Invokes

None — iru-setup-python-gitignore is a leaf skill; it only reads manifests and config files and writes .gitignore. It relies on the flavor markers also used by Explore and Setup Python Repository, but does not call them.

Invoked by

Related agents

None.

Source

SKILL.md on GitHub — the file this page was generated from.