gitignore

Gitignore

Generate well-structured .gitignore files that separate user-level from project-level concerns, cover all common blind spots, and follow community best practices.

Three-Tier System

~/.gitignore_global          # User: OS files, your editor, your AI tools
.gitignore                   # Project: build output, deps, secrets, caches
.git/info/exclude            # Local one-offs: not shared, not committed

Setup: git config --global core.excludesFile ~/.gitignore_global

Workflow

1. Detect project type from existing files (package.json, pyproject.toml, Cargo.toml, go.mod, etc.)
2. Start with the right github/gitignore template — fetch from https://github.com/github/gitignore/tree/main for the detected language/framework (e.g., Node.gitignore, Python.gitignore, Rust.gitignore, Go.gitignore)
3. Layer on universal patterns from the catalog below
4. Add framework-specific patterns (.next/, .nuxt/, .turbo/, etc.)
5. Apply partial-commit patterns for shared tool configs (.vscode, .claude)
6. Verify nothing critical is missing against the catalog reference
7. Check for already-tracked files that should now be ignored — warn about git rm --cached

Universal Patterns (Always Include)

These apply to virtually every project regardless of language:

# Secrets & environment
.env
.env.local
.env.*.local
!.env.example
*.pem
*.key

# OS artifacts (safety net for devs without global gitignore)
.DS_Store
Thumbs.db

# Logs
*.log

# AI coding tools — local/personal overrides
CLAUDE.local.md

Partial-Commit Patterns

Some directories contain a mix of team-shared and personal files. Use the ignore-then-unignore pattern:

VS Code

# ref: github/gitignore/blob/main/Global/VisualStudioCode.gitignore
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
!.vscode/*.code-snippets

Claude Code

# ref: code.claude.com/docs/en/settings
.claude/*
!.claude/settings.json
!.claude/CLAUDE.md
!.claude/agents/
!.claude/rules/
CLAUDE.local.md

Cursor

# ref: cursor.com/docs/context/ignore-files
.cursor/*
!.cursor/rules/

Key Principles

• Project .gitignore = project concerns only. Build output, deps, secrets, caches, local overrides.
• Editor/IDE configs belong in global gitignore, not the project. Exception: partial-commit patterns above when the team agrees.
• OS artifacts (.DS_Store, Thumbs.db): Belong in global gitignore. Including them in project .gitignore is a courtesy safety net — acceptable but not required.
• Team convention files MUST be committed: .editorconfig, .prettierrc, .eslintrc*, tsconfig.json, lock files, .nvmrc, mise.toml, .husky/, .devcontainer/.
• Lock files MUST be committed: pnpm-lock.yaml, package-lock.json, yarn.lock, Cargo.lock, poetry.lock.
• *.local convention: Many tools use .local suffix for personal overrides (.env.local, CLAUDE.local.md, mise.local.toml, docker-compose.override.yml). Always ignore these.
• Comment with refs: Add # ref: comments linking to the relevant github/gitignore template or official docs for non-obvious patterns.
• Group by category: Organize sections with clear headers (secrets, build output, testing, etc.).

Common Pitfalls

• Forgetting .env.*.local variants (.env.development.local, .env.test.local)
• Committing docker-compose.override.yml — this is Docker's local override mechanism
• Not committing lock files — causes inconsistent dependency resolution
• Gitignoring .editorconfig or .prettierrc — these are team standards, not personal preference
• Adding a file to .gitignore after it's already tracked — must run git rm --cached <file> first
• Using overly broad patterns like * that accidentally hide important files

Full Catalog Reference

For the complete categorized list of 80+ common paths with recommendations (editors, AI tools, OS, secrets, version managers, build tools, testing, containers, Python, git hooks, infra, logs), see references/gitignore-catalog.md.

Canonical Source

https://github.com/github/gitignore/tree/main — official templates for languages, frameworks, and global patterns. Always cross-reference when setting up a new project type.