team-guide is now positioned as the external rulebook agents read at project start: project AGENTS.md files reference team-guide rather than duplicating its content. - Delete templates/ (5 files). The only useful one — AGENTS.md skeleton — is now an inline code block in AGENTS.md §2. Handoff checklist also inlined into AGENTS.md §7. - Remove the unaudited "Product projects" section (was AGENTS.md §5). Project repos document their own release scheme in their own AGENTS.md. - Add library/ as a catalog for narrower specs. - Seed library/git-upload/SPEC.md: what to commit / what not to, .gitignore baseline, sensitive-info scan, leaked-secret recovery. - AGENTS.md gets a "How AI agents use this repo" intro and a §5 Team library section indexing library/. - README.md updated to match: explicit "for AI" framing, library section, drop product-spec mentions. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
8.6 KiB
git-upload — what to commit, what not to
When to read this
- Pushing to a remote for the first time on a project.
- Adding a new file type the project hasn't committed before (data dumps, generated artifacts, model weights, .env files, screenshots).
- About to run
git add .orgit add -A. - Cleaning up a
.gitignore. - Suspect or confirmed a secret was committed.
This is a focused spec, not the full Git workflow. Branch / commit /
PR / tagging rules live in ../../AGENTS.md §3.
The first rule
git status and git diff --cached before every push. Read every
file name in the staging list. Most accidents happen because the
author didn't notice an extra file got staged.
What goes in
Source and infrastructure for the project. Things that:
- Are written by humans (or AI under a human's review).
- Are reasonably small (text or small binaries — a few MB at most).
- Are the canonical version, not a derivative or cache.
Concretely:
- Source code, scripts, tests
- Configuration templates (e.g.
.env.example) — never real values - Schemas, fixtures, small reference datasets that are part of the project
- Documentation (Markdown, small images for docs)
- Lockfiles (
package-lock.json,poetry.lock,Cargo.lock, etc.) — always commit these - Build / CI configuration
- License, README, CHANGELOG
What stays out
Secrets and credentials
Never commit any of these, even once, even temporarily.
- API keys, tokens, passwords (any provider)
.env,.env.local,.env.production,*.pem,*.key,id_rsa,*.pfx,*.p12- OAuth client secrets, webhook signing keys
- Database connection strings with embedded passwords
- Cloud credentials (
~/.aws/credentials, service account JSON) - Personal access tokens in URLs (
https://user:TOKEN@host/repo.git) - Cookies, session tokens, signed JWTs from real users
A "delete the secret" commit later is not enough — the secret stays in history. See Recovering from a leaked secret.
Generated and runtime files
These are derivatives — regenerable from sources, not source themselves.
# Build outputs
dist/ build/ out/ target/ .next/ .nuxt/
# Dependency caches
node_modules/ .venv/ venv/ __pycache__/ .pytest_cache/ .mypy_cache/
.tox/ .gradle/ vendor/ Pods/
# Editor / IDE state
.vscode/ .idea/ *.swp .DS_Store Thumbs.db desktop.ini
# Local runtime / logs
logs/ *.log tmp/ .cache/ runtime-temp/ feedback-records/
generated_*/ reports/
The exception: vendored dependencies that you deliberately want under version control (offline / air-gapped builds). That's a project decision documented in the project's AGENTS.md, not the default.
Large binaries
5 MB → stop. Talk about Git LFS or out-of-band storage first.
Common offenders to scan for before pushing:
- Model weights (
.bin,.safetensors,.gguf,.ckpt,.pt,.onnx) - Datasets (
.parquet,.arrow,.zip,.tar.gz,.7zover a few MB) - Videos, raw images, audio
- Database dumps, full backups
- Vendor SDK installers
Once a large binary is in history, the repo is bloated forever (unless you rewrite history). Catch it before push, not after.
Personal / machine-specific files
- Personal editor settings — those go in
~/.<editor>not the repo - Agent personal config —
.claude/settings.local.json,~/.codex/config.toml(the personal one) - Per-machine paths, hostnames, debug toggles
- Temporary scratch files, half-written notes
User and customer data
- Real PII (names, emails, phone numbers from real people)
- Real internal records, customer logs, support tickets
- Anything covered by NDA or compliance scope
If sample data is needed for tests, generate it synthetically or use public fixtures.
.gitignore patterns
A baseline for most projects (adapt to the language):
# OS
.DS_Store
Thumbs.db
desktop.ini
# Editors
.vscode/
.idea/
*.swp
*~
# Secrets
.env
.env.*
!.env.example
*.pem
*.key
id_rsa*
*.pfx
*.p12
# Agent local state
.claude/settings.local.json
.claude/projects/
.claude/sessions/
# Python
__pycache__/
*.py[cod]
.venv/
venv/
.pytest_cache/
.mypy_cache/
# Node
node_modules/
npm-debug.log*
yarn-error.log
# Build outputs (uncomment what applies)
# dist/
# build/
# out/
# Logs / temp
*.log
tmp/
.cache/
Two rules for .gitignore:
- Be deliberate about negations (
!.env.exampleetc.) — they override broader rules and are the source of "why isn't this file ignored" confusion. .gitignoreonly ignores untracked files. A file already in the index keeps being tracked even if you add it to.gitignore. To actually stop tracking it:git rm --cached <file>then commit.
Staging discipline
git add . and git add -A are dangerous when there are unrecognized
untracked files. The safe pattern:
git status --short # see what's changed
git add <specific files> # stage by name
git diff --cached # read what's actually being committed
git commit -m "..."
If you have many related files and want to use a glob, prefer git add src/foo/ (a directory) over git add . (the world).
Sensitive-info scan
Before push, especially when you've added new files:
git diff --cached
For periodic / pre-release scans across the working tree:
git grep -nE "sk-|hf_|Bearer |apiKey|ANTHROPIC_API_KEY|OPENAI_API_KEY|password|secret" \
-- ':!*.lock' ':!vendor/**' ':!**/__pycache__/**'
Hits need human judgment — demo keys in comments and real keys both match the same regex. Don't blind-commit and don't blind-delete.
For a stronger sweep, use a dedicated tool (gitleaks, trufflehog,
or your platform's secret scanning). They have richer rule sets than
the regex above. Run them at least before any first-time push to a new
remote.
Recovering from a leaked secret
When a real secret has been committed (and possibly pushed):
- Invalidate the secret immediately. Rotate the key/token at the provider before doing anything else. This is the only step that actually makes the leak safe — everything below is cleanup.
- Replace the secret locally. Move it to
.env(which is gitignored) or your secrets manager. - Notify collaborators. They need to know not to base work on the compromised commit until history is rewritten.
- Decide whether to rewrite history. For a public repo or one with a
short history, use
git filter-repo(preferred over the deprecatedfilter-branch) or your platform's secret-removal tooling. After rewrite, force-push with team agreement and ask everyone to re-clone. - Document the incident briefly — what leaked, when, how, what was done. Future-you will want this when a similar mistake happens.
A "delete the key" commit on top is not safe. The secret is still in history and accessible to anyone who clones.
URLs with embedded credentials
A common slip: pushing with a token-embedded URL writes the token into
.git/config:
remote "origin"
url = https://user:TOKEN@host/owner/repo.git
Fix: after pushing, reset the URL to the credential-free form and let the credential helper handle auth:
git remote set-url origin https://host/owner/repo.git
Verify with git remote -v. The token also lives in shell history and
in any .bash_history / PowerShell history file — clear it if the
token is sensitive enough to warrant rotation.
First push to a new remote
A short checklist when initializing a project:
.gitignorecovers secrets, build outputs, editor state, agent local state- No
.env(or any.env.*other than.env.example) in the tree - No files >5 MB in the tree (check with
find . -size +5M -not -path "./.git/*"or equivalent) git statusshows only files you mean to commitgit diff --cachedreads cleanly — no surprise content- Repo URL on the remote matches the one you intend; no token in the URL
- Credential helper is configured (so you don't have to embed tokens in URLs)
After first push: git remote -v should show a clean URL.
Don'ts (summary)
- Don't
git add .with unrecognized untracked files in the tree. - Don't commit
.env, secrets, tokens, or real credentials — ever, not even temporarily. - Don't commit large binaries (>5 MB) without a Git LFS conversation.
- Don't commit generated / cache directories.
- Don't commit real user data or PII.
- Don't try to "clean up" a leaked secret with a delete commit. Rotate first, rewrite history if needed.
- Don't leave tokens in
.git/configafter a token-in-URL push. - Don't
--no-verifyto skip pre-commit secret scans.