|$ curl https://forge-ai.dev/api/markdown?path=docs/git/gitignore
$cat docs/gitignore.md
updated Today·20-28 min read·published
Gitignore
Introduction
.gitignore tells Git which untracked paths to pretend do not exist. It does not untrack files already in the index — those need git rm --cached.
ℹ
info
Pair with Best Practices secrets guidance.
Pattern Language
| Pattern | Matches |
|---|---|
| *.log | any .log file in any directory |
| /build | build only at repo root |
| build/ | any directory named build |
| **/temp | temp file/dir at any depth |
| doc/**/*.pdf | pdfs under doc/ |
| !important.log | negate a prior ignore |
| # comment | comment line |
| \\#file | literal #file |
.gitignore
GITIGNORE
| 1 | # dependencies |
| 2 | node_modules/ |
| 3 | .venv/ |
| 4 | |
| 5 | # builds |
| 6 | dist/ |
| 7 | build/ |
| 8 | .next/ |
| 9 | coverage/ |
| 10 | |
| 11 | # secrets |
| 12 | .env |
| 13 | .env.* |
| 14 | !.env.example |
| 15 | *.pem |
| 16 | |
| 17 | # logs & OS |
| 18 | *.log |
| 19 | .DS_Store |
| 20 | Thumbs.db |
| 21 | |
| 22 | # IDE (keep shared vscode settings) |
| 23 | .idea/ |
| 24 | .vscode/* |
| 25 | !.vscode/extensions.json |
| 26 | !.vscode/settings.json |
Negation Rules
Negation re-includes a path ignored by an earlier pattern. Parent directories must not be ignored, or Git cannot descend to re-include children.
negation.gitignore
GITIGNORE
| 1 | # Wrong: ignores directory so ! never reached |
| 2 | dist/ |
| 3 | !dist/keep.txt |
| 4 | |
| 5 | # Right: ignore contents, not the directory itself |
| 6 | dist/* |
| 7 | !dist/keep.txt |
| 8 | !dist/assets/ |
| 9 | dist/assets/* |
| 10 | !dist/assets/logo.svg |
⚠
warning
Order matters. Later patterns override earlier ones for the same path.
Global Gitignore
Keep personal IDE/OS junk out of every repo without polluting project .gitignore files.
global.sh
Bash
| 1 | git config --global core.excludesFile ~/.config/git/ignore |
| 2 | mkdir -p ~/.config/git |
| 3 | cat >> ~/.config/git/ignore <<'EOF' |
| 4 | .DS_Store |
| 5 | Thumbs.db |
| 6 | *.swp |
| 7 | .idea/ |
| 8 | .vscode/ |
| 9 | EOF |
| 10 | git config --get core.excludesFile |
git check-ignore
Debug why a path is ignored (or not).
check-ignore.sh
Bash
| 1 | git check-ignore -v .env |
| 2 | git check-ignore -v node_modules/lodash/index.js |
| 3 | git check-ignore -v --non-matching .env.example |
| 4 | # -v shows source file and pattern line |
Already Tracked Files
untrack.sh
Bash
| 1 | # Stop tracking but keep on disk |
| 2 | git rm -r --cached node_modules |
| 3 | echo "node_modules/" >> .gitignore |
| 4 | git add .gitignore |
| 5 | git commit -m "chore: stop tracking node_modules" |
✕
danger
Removing from the index in a commit will delete the path for others on next pull. Coordinate for large mistakes.
Templates
Start from github/gitignore templates and trim to your stack.
fetch-template.sh
Bash
| 1 | curl -sL https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore >> .gitignore |
| 2 | curl -sL https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore >> .gitignore |
| 3 | curl -sL https://raw.githubusercontent.com/github/gitignore/main/Global/macOS.gitignore >> ~/.config/git/ignore |
Python essentials
python.gitignore
GITIGNORE
| 1 | __pycache__/ |
| 2 | *.py[cod] |
| 3 | .venv/ |
| 4 | venv/ |
| 5 | .pytest_cache/ |
| 6 | .mypy_cache/ |
| 7 | .ruff_cache/ |
| 8 | dist/ |
| 9 | *.egg-info/ |
| 10 | .env |
Node essentials
node.gitignore
GITIGNORE
| 1 | node_modules/ |
| 2 | npm-debug.log* |
| 3 | yarn-error.log* |
| 4 | .pnpm-store/ |
| 5 | .next/ |
| 6 | out/ |
| 7 | dist/ |
| 8 | .env |
| 9 | .env.local |
| 10 | coverage/ |
info/exclude
.git/info/exclude is a local-only ignore file — never committed. Use for machine-specific noise.
exclude.sh
Bash
| 1 | echo "scratch/" >> .git/info/exclude |
| 2 | echo "notes.md" >> .git/info/exclude |
FAQ
Common questions and short answers.
Why is my ignored file still showing?
It was tracked before. Use git rm --cached and commit.
Can I ignore a file only for myself?
Yes — core.excludesFile or .git/info/exclude.
Do gitignore patterns affect clean?
git clean -fd respects excludes unless -x is used.
Ignore Review Checklist
- Secrets and .env patterns present
- Build outputs ignored
- Dependencies ignored
- .env.example force-included if needed
- Global excludes configured for OS junk
checklist.sh
Bash
| 1 | echo "[ ] Secrets and .env patterns present" |
| 2 | echo "[ ] Build outputs ignored" |
| 3 | echo "[ ] Dependencies ignored" |
| 4 | echo "[ ] .env.example force-included if needed" |
| 5 | echo "[ ] Global excludes configured for OS junk" |
Notes for AI Agents
- Never stage .env
- Run check-ignore -v when confused
- Prefer editing .gitignore over force-adding ignored files
- Do not commit .git/info/exclude
🔥
pro tip
See How to Master Git for curriculum order.
Worked Examples
These end-to-end examples reinforce the gitignore concepts above. Run them in a disposable lab under /tmp so mistakes are cheap.
Example A — happy path
example-a.sh
Bash
| 1 | # Lab for gitignore |
| 2 | rm -rf /tmp/git-lab-gitignore && mkdir -p /tmp/git-lab-gitignore |
| 3 | cd /tmp/git-lab-gitignore |
| 4 | git init -b main |
| 5 | git config user.email "lab@example.com" |
| 6 | git config user.name "Lab User" |
| 7 | echo "# lab" > README.md |
| 8 | git add README.md |
| 9 | git commit -m "chore: init lab for gitignore" |
| 10 | git status -sb |
| 11 | git log --oneline --decorate |
Example B — recover from a mistake
example-b.sh
Bash
| 1 | # Make a bad commit, then recover safely |
| 2 | echo bad > oops.txt |
| 3 | git add oops.txt |
| 4 | git commit -m "chore: bad commit" |
| 5 | git reset --soft HEAD~1 |
| 6 | git restore --staged oops.txt |
| 7 | rm oops.txt |
| 8 | git status -sb |
| 9 | # If you had hard-reset already: |
| 10 | # git reflog | head |
| 11 | # git reset --hard HEAD@{1} |
🔥
pro tip
Keep a note of the SHA before risky operations: reflog can save you, but only locally.
Troubleshooting
Symptoms you will hit in real repos, and the first commands to run.
Unexpected dirty tree
trouble-dirty.sh
Bash
| 1 | git status -sb |
| 2 | git diff |
| 3 | git diff --staged |
| 4 | git stash list |
| 5 | # Discard one file: |
| 6 | git restore path/to/file |
| 7 | # Unstage one file: |
| 8 | git restore --staged path/to/file |
Diverged from remote
trouble-diverge.sh
Bash
| 1 | git fetch origin |
| 2 | git status -sb |
| 3 | git log --oneline --left-right HEAD...origin/main |
| 4 | # Prefer rebase for feature branches: |
| 5 | git rebase origin/main |
| 6 | # Prefer merge if shared long-lived branch: |
| 7 | # git merge origin/main |
Conflict markers left behind
trouble-markers.sh
Bash
| 1 | git diff --check |
| 2 | rg -n '^(<<<<<<<|=======|>>>>>>>)' || true |
| 3 | # Fix files, then: |
| 4 | git add -A |
| 5 | git status |
✕
danger
Never force-push to main to "fix" divergence. Use revert or a forward fix.
Command Cheatsheet
Keep this short list nearby while practicing gitignore.
cheatsheet.sh
Bash
| 1 | git status -sb |
| 2 | git log --oneline --graph --decorate -15 |
| 3 | git diff |
| 4 | git diff --staged |
| 5 | git add -p |
| 6 | git commit -m "type(scope): summary" |
| 7 | git switch -c feature/x |
| 8 | git fetch origin --prune |
| 9 | git rebase origin/main |
| 10 | git push -u origin HEAD |
| 11 | git restore --staged PATH |
| 12 | git restore PATH |
| 13 | git stash push -u -m "wip" |
| 14 | git reflog | head |
| 15 | git rev-parse HEAD |
| 16 | git remote -v |
- Read the full curriculum order in How to Master Git
- Look up flags in Commands Reference
- Follow the staged path in Git Roadmap
Team Policy Notes
Document these decisions so humans and agents behave consistently across the org.
- Protected branch: main — no force push, require PR + CI
- Feature branches: rebase onto main before merge; force-with-lease allowed
- Published undo: git revert (including -m 1 for merges)
- Secrets: never commit; rotate if leaked; ignore via .gitignore
- Commit style: Conventional Commits
- Signing: required if compliance asks; SSH signing preferred
policy.md
Markdown
| 1 | # Git policy (excerpt) |
| 2 | - defaultBranch: main |
| 3 | - updateStrategy: rebase |
| 4 | - mergeStrategy: squash (via host) |
| 5 | - allowForcePush: feature/* only with --force-with-lease |
| 6 | - requireSignedCommits: true |
| 7 | - maxPRLines: 400 (soft) |
✓
best practice
Automate policy with hooks + CI — see Hooks and Best Practices.
Agent Verification Prompts
If you are an AI agent claiming competence on this topic, generate answers to these prompts and self-score. Fail closed on any critical miss.
- Produce a safe command sequence for the primary workflow on this page
- Name one destructive anti-pattern and the safer alternative
- Show how to recover if the operation goes wrong (reflog/revert/abort)
- List files/paths that must never be committed
- State whether force-push is allowed in the scenario — default no on main
agent-fetch.sh
Bash
| 1 | curl -s "https://forgelearn.dev/api/markdown?path=git/mastery" | head |
| 2 | curl -s "https://forgelearn.dev/api/agent?skill=forgelearn-git" | head |
| 3 | curl -s https://forgelearn.dev/skills/forgelearn-git/SKILL.md | head |
✕
danger
Do not claim mastery from titles alone — ingest full markdown for each linked topic.
Community
Get help on Slack, Discord or VIP
Stuck on a guide? Join the community and ask.