Git

Git — Rules and Conventions

1. Philosophy

1. Atomic commits — One commit = one logical change. Small, descriptive, reviewable. Stage selectively, never git add . blindly.
2. Clean history — main stays linear and deployable: every PR lands as one squash commit. No merge bubbles, no WIP commits, no empty messages.
3. Ephemeral branches — Feature branches are short-lived, derived from main, deleted after merge. main is the only permanent branch.
4. Trunk-based development — main is always stable and deployable. Every change reaches main through a PR with code review. Never push directly to main.
5. Conventional Commits — Mandatory standard for messages. Enables changelog generation, semantic versioning, automated releases.

2. Minimum Versions

3. Branching Strategy (Trunk-Based)

One permanent branch: main. Everything else is ephemeral and merges into main via PR.

No develop, release/*, or hotfix/* branches. A hotfix is a fix/<name> branch from main with priority. A release is a tag + GitHub Release from main, not a branch.

Naming Convention

feature/<issue-id>-<short-description>
fix/<issue-id>-<short-description>
chore/<issue-id>-<short-description>
docs/<issue-id>-<short-description>
epic/<short-description>

Examples

feature/42-add-user-auth
fix/53-fix-login-redirect
chore/58-bump-dependencies
docs/12-update-readme
epic/billing-refactor

4. Commits

Format (Conventional Commits)

<type>(<optional scope>): <description>

<optional body>

<optional footer>

Types

Full spec is default. build and ci can map to chore if team prefers, but commit-msg hook must match.

Breaking Changes

feat(api)!: change user endpoint response format

BREAKING CHANGE: The /api/users endpoint now returns { data: [...] }
instead of the previous flat array format.

Rules

• Language: English by default (matches orchestrator contract: generated technical artifacts are English). Spanish/other only when explicitly requested.
• Description: imperative present tense, no final period
• Body: explain what and why, not how
• Footer: reference issues (Closes #42, Fixes #53)
• Atomic: one logical change per commit; stage specific files (git add <files> or git add -p), never git add .
• No AI attribution: never add Co-Authored-By or AI-generated trailers

# ❌ Bad
fix stuff
update
WIP
asdf

# ✅ Good
feat(auth): add login form validation
Closes #42

Commit Signing (GPG or SSH)

# GPG
gpg --full-generate-key
git config --global user.signingkey <KEY_ID>
git config --global commit.gpgsign true
git commit -S -m "feat: add secure endpoint"

# SSH (simpler, reuses SSH key)
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true
git commit -S -m "feat: add secure endpoint"

5. Pull Requests

Title

Same format as commits:

feat(auth): add login form validation

Checklist before opening PR

• Branch rebased on main (not merged)
• Code follows project conventions
• Tests pass locally (pnpm test) — see package-manager skill
• Linter passes (pnpm lint) — see linting skill
• git diff --check reports no whitespace errors
• No console.log / debugger
• No commented-out code
• Documentation updated if applicable
• No merge conflicts with target branch

Draft PRs

Open a draft PR (gh pr create --draft) for early feedback or WIP slices. Cannot be merged until marked ready.

6. Merge Policy

One clear policy — no ambiguity:

Synchronizing before PR (standard)

git switch feature/42-add-user-auth
git fetch origin
git rebase origin/main
# Resolve conflicts if any, then re-test before pushing

Exception: merge commit (rare, documented)

git switch main
git merge --no-ff feature/42-add-user-auth

7. Workflow

Feature

git switch main
git pull origin main
git switch -c feature/42-add-user-auth
# ... work in small, atomic commits ...
git add src/auth/login.ts src/auth/validation.ts
git commit -m "feat(auth): add login form validation"
git push
gh pr create --title "feat(auth): add login form validation" --body "Closes #42"

Bug fix / hotfix (same flow, higher priority)

git switch main
git pull origin main
git switch -c fix/58-patch-security-vuln
git commit -m "fix: patch XSS vulnerability in search input"
git push
gh pr create --title "fix: patch XSS vulnerability in search input"
# After merge, tag a patch release if it must ship immediately (§10)

Release (tag from main, no release branch)

git switch main
git pull origin main
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin v1.2.0
gh release create v1.2.0 --generate-notes

Keep long-lived branch in sync

git fetch origin
git rebase origin/main
# If rewrites already-pushed commits:
git push --force-with-lease

8. Stacked / Chained PRs

Large changes must be split into reviewable slices. Pick one strategy per delivery plan and state it explicitly.

stacked-to-main

Each PR targets main; branches derive from each other. Merge bottom-up.

# Slice 1
git switch -c feature/42-auth-base main
# ... commits ...
git push
gh pr create --base main --head feature/42-auth-base

# Slice 2 (derived from slice 1)
git switch -c feature/42-auth-validation feature/42-auth-base
# ... commits ...
git push
gh pr create --base main --head feature/42-auth-validation

When base PR merges, rebase child on updated main:

git fetch origin
git switch feature/42-auth-validation
git rebase origin/main
git push --force-with-lease

feature-branch-chain (tracker branch)

Tracker (epic/<name>) accumulates integration; PRs target previous branch. Only tracker merges to main.

# Tracker
git switch -c epic/billing-refactor main
git push
gh pr create --base main --head epic/billing-refactor --draft

# PR #1 targets tracker
git switch -c feature/10-billing-model epic/billing-refactor
git push
gh pr create --base epic/billing-refactor --head feature/10-billing-model

# PR #2 targets previous PR branch
git switch -c feature/11-billing-api feature/10-billing-model
git push
gh pr create --base feature/10-billing-model --head feature/11-billing-api

Rules for chained PRs

1. Merge bottom-up, always in dependency order.
2. After any parent merge/edit, rebase descendants and verify with git range-diff (§12).
3. Only --force-with-lease, never plain --force.
4. Review incremental diff (gh pr diff against PR base), not whole chain.
5. Delete branches after merge; for tracker chain, delete all children when tracker merges.

9. .gitignore

Essential patterns (modern frontend)

# Dependencies
node_modules/

# Build output
dist/
build/
.next/
out/
.astro/
.vite/

# Caches
.cache/
.eslintcache
.parcel-cache/
.turbo/
.nx/

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# OS
.DS_Store
Thumbs.db

# Env (commit .env.example as template)
.env
.env.local
.env.*.local

# Logs
*.log
pnpm-debug.log*

# Testing (coverage only — snapshots ARE committed for PR review)
coverage/
.vitest/

# Platform folders
.vercel/
.netlify/

# Temp
*.tmp
*.temp
*.tsbuildinfo

⚠️ Do NOT ignore snapshots (__snapshots__/, *.snap). Jest/Vitest commit snapshots by default for PR review. Secrets: .env* patterns above are minimum. Add secret scanning — see security skill.

10. Tags and Semantic Versioning

SemVer

MAJOR.MINOR.PATCH
MAJOR: incompatible changes (breaking)
MINOR: new features (backward compatible)
PATCH: bug fixes (backward compatible)

Create tags

# Annotated (recommended — includes metadata)
git tag -a v1.2.0 -m "Release v1.2.0"

# Signed
git tag -s v1.2.0 -m "Release v1.2.0"

Publish tags

git push origin v1.2.0
git push origin --tags

11. Git Hooks

Production path for frontend repos is husky + lint-staged (see linting skill). commitlint is the maintainable alternative to hand-rolled commit-msg hook.

Husky + lint-staged (reference)

Husky manages git hooks without touching .git/hooks directly. lint-staged runs linters only on staged files. See linting skill for full setup.

commitlint (recommended)

pnpm add -D @commitlint/cli @commitlint/config-conventional
echo "export default { extends: ['@commitlint/config-conventional'] }" > commitlint.config.js
# Wire into husky: echo "pnpm commitlint --edit \$1" > .husky/commit-msg

12. Daily Commands + Recovery

Modern day-to-day

git switch main                    # instead of: git checkout main
git switch -c feature/x            # instead of: git checkout -b feature/x
git restore --staged file.ts       # unstage
git restore file.ts                # discard working-tree changes of one file
git diff --check                   # whitespace errors before committing

Stash

git stash push -u -m "WIP: login form"  # -u includes untracked
git stash list
git stash pop
git stash apply stash@{2}
git stash drop stash@{2}
git stash branch feature/new-branch     # create branch from stash

Cherry-pick

git cherry-pick abc1234               # apply specific commit
git cherry-pick abc1234 def5678       # multiple
git cherry-pick -n abc1234            # without committing

Reflog (disaster recovery)

git reflog                            # HEAD movement history
git reflog show feature/42            # specific branch
git cherry-pick <hash>                # recover "lost" commit after reset

Bisect (binary debugging)

git bisect start
git bisect bad                        # current is bad
git bisect good v1.0.0                # tag where it worked
# Test each step: git bisect bad / good
git bisect reset                      # exit

# Automated
git bisect start HEAD v1.0.0
git bisect run pnpm test
git bisect reset

Incorporate review feedback

git commit --fixup <hash>
git rebase -i --autosquash <base>

range-diff (verify rebases and force-pushes)

git range-diff origin/main...HEAD
git range-diff <sha-before>...<sha-after>  # after force-push

Pickaxe (find when string introduced)

git log -S "functionName" --oneline -- src/
git blame src/auth/login.ts

Worktrees (parallel branches)

git worktree add ../project-feature feature/42
git worktree list
git worktree remove ../project-feature

Submodules (rare — prefer pnpm workspaces)

git submodule add https://github.com/user/lib.git libs/shared
git clone --recurse-submodules <url>
git submodule update --init --recursive

Git LFS (rare)

git lfs install
git lfs track "*.psd" "*.zip" "*.mp4"
git lfs ls-files

13. GitHub CLI

Essential commands

gh auth login
gh pr create --title "feat(auth): add login" --body "Closes #42"
gh pr create --draft --title "feat(auth): add login" --body "WIP"
gh pr create --base epic/xxx --head feature/yyy  # stacked PRs
gh pr list
gh pr checkout 42
gh pr view 42
gh pr diff 42
gh pr checks 42 --watch
gh pr merge 42 --squash

⚠️ gh pr merge, gh pr close, gh pr review --approve require explicit user authorization. Never run without confirmation.

14. Permission Matrix and User Authorization

Command categories (agent / orchestrator contract)

Workflow (step by step)

1. Explain the plan
   → "I will commit changes to skills/git/SKILL.md and skills/package-manager/SKILL.md"
   → "Message: feat: modernize git and package-manager skills to v2.0"

2. Show evidence
   → "Files changed: skills/git/SKILL.md, skills/package-manager/SKILL.md"
   → Show exact command to execute

3. Ask for confirmation
   → "Should I run: git add skills/git/SKILL.md skills/package-manager/SKILL.md && git commit -m 'feat: modernize git and package-manager skills to v2.0'?"

4. Only then execute
   → If user confirms, execute
   → If not, stop and wait

Rules Git

1. Never run git add, git commit, git push without user permission.
2. Never merge, close, or approve a PR without explicit user permission.
3. Always show exact command before asking.
4. Always wait for explicit yes/no.
5. Never assume consent from silence.
6. Never chain commands without permission.
7. Agent/subagent approval ≠ authorization — only human user authorizes.

15. Prohibitions

• ❌ NEVER commit or push directly to main
• ❌ NEVER use git push --force on shared branches (use --force-with-lease)
• ❌ No giant commits (+200 lines without justification)
• ❌ No empty/meaningless commit messages
• ❌ NEVER merge a PR without explicit user authorization
• ❌ NEVER close a PR without explicit user authorization
• ❌ NEVER self-approve a PR without explicit user authorization
• ❌ No WIP or fix in final commits
• ❌ Do not ignore .gitignore (no node_modules, .env, dist/)
• ❌ Do not use git commit --no-verify except justified emergency
• ❌ Do not push .env or secrets
• ❌ Do not rebase/force-push branches shared with other developers
• ❌ Do not delete tags without team consensus

16. Methodology

Before using ANY Git command/config/pattern not documented in this skill:

1. MCP Context7 (priority): context7_resolve-library-id + context7_query-docs for the specific tool.
2. Official docs: git-scm.com — verify current behavior + options.
3. Project config: .git/config, .github/workflows/ — verify against actual setup.
4. HARD RULE: If not in this skill AND cannot be verified against 2 authoritative sources → DO NOT USE IT. Document as assumption or risk in report to orchestrator.

17. References

Note: For husky + lint-staged and commitlint wiring, see Linting Note: For CI/CD workflow templates, see Deploy Note: For package manager conventions, see Package Manager Note: For secret scanning, see Security

Last updated: 2026-08