Files
praxis/library/git-upload/SPEC.md
T
阿白叔andClaude Opus 4.7 c5e6ebb534 docs: replace templates/ with library/, drop unaudited Product section
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>
2026-05-20 23:38:46 +08:00

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 . or git 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, .7z over 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:

  1. Be deliberate about negations (!.env.example etc.) — they override broader rules and are the source of "why isn't this file ignored" confusion.
  2. .gitignore only 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):

  1. 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.
  2. Replace the secret locally. Move it to .env (which is gitignored) or your secrets manager.
  3. Notify collaborators. They need to know not to base work on the compromised commit until history is rewritten.
  4. Decide whether to rewrite history. For a public repo or one with a short history, use git filter-repo (preferred over the deprecated filter-branch) or your platform's secret-removal tooling. After rewrite, force-push with team agreement and ask everyone to re-clone.
  5. 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:

  • .gitignore covers 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 status shows only files you mean to commit
  • git diff --cached reads 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/config after a token-in-URL push.
  • Don't --no-verify to skip pre-commit secret scans.