SuperAPI AI Directory

build-infrastructure-git

Coding & development

View repository

Updated 10-16 09:45

About this skill

Git — Version Control Workflow

Entry/Exit

  • Entry: Need to commit code or create a branch during build
  • Exit: Clean, separable commit history for review
  • Points to: Continue build or enter verify-workflow-review
  • Preload: CANON.md
  • Output path: Commit history → verify-workflow-review review

When not to use

  • Only reading history, checking status, or explaining Git concepts, without creating commits/branches
  • The current task explicitly requires not committing or not changing version history
  • When unowned changes need to be cleaned up but the source cannot be determined, ask the human partner first

Iron Law

Core principles

1. Trunk-Based Development (recommended)

main ────○────○────────○────○── (经常合并小改动)
           \          /
feature     ○──○──○──○  (短生命周期分支,< 2 天)

Rules:

  • Branch lifetime < 2 days
  • Rebase onto latest main before merging
  • Small PRs (100-300 lines) > large PRs
  • Commit directly to main only for documentation fixes, configuration adjustments, and other non-behavioral changes

2. Atomic commits — one change per commit

Good:
  1a2b3c feat: add Task.create() with validation
  4d5e6f test: add unit tests for Task.create()
  7f8g9h refactor: extract validateTask to shared module

Bad:
  abc123 feat: add task creation, tests, refactor validation, fix typo in README

Each commit is independently understandable, revertible, and bisectable.

3. Descriptive commit messages

<type>: <简短摘要(< 50 字符)>

<详细说明 —— 为什么改,不是什么(可选,如有必要)>

Type: feat / fix / refactor / test / docs / chore / perf / security

Commit messages should state why, not what.git diff already shows what.

Good:
  fix: prevent race condition when two users complete same task
  
  The task status check and update were not atomic, allowing two
  concurrent requests to both mark a task as completed.

Bad:
  fix: update task service

4. Separation of concerns

  • Formatting changes → separate formatting commit
  • Renaming/moving files → separate commit (do not mix with behavioral changes)
  • Behavioral changes → separate commit

Never mix formatting changes and behavioral changes in one commit.

5. Change size

Size Lines Review difficulty
Small < 100 lines Easy to review, fast to merge
Medium 100-300 lines Regular PR, can be completed in one review session
Large 300-1000 lines Needs splitting or more careful review
XL > 1000 lines Must be split

Goal: about 100 lines per commit. Over 300 lines → decide whether to split.

Save Point mode

Commit frequently, push often. A commit = a save point, not a final product.

实现 Task A      实现 Task B      格式化          Rebase 到 main
    │                │               │                  │
    ▼                ▼               ▼                  ▼
commit + push   commit + push   commit + push    git pull --rebase
                                                    │
                                               push + merge

Safety net: Commit after completing each logical unit (one function, one test, one refactoring step). If you mess up later, rollback is cheap.

Worktree isolation

Create isolated environments for unrelated work:

# 创建隔离工作区
git worktree add -b feature/x ../project-feature-x main

# 在隔离区工作
cd ../project-feature-x

# 完成 → 合并 → 清理
git worktree remove ../project-feature-x

When to use worktree:

  • Handle multiple unrelated tasks at the same time
  • Need to quickly switch back to main to verify some behavior without losing current progress
  • Run long scripts (tests, builds) without blocking

Pre-Commit Hygiene

Before committing, check:

git diff --staged            # 审查你实际要提交的变更
git diff --staged --check    # 检查空白字符错误
npm test                     # 运行测试(如果项目有预提交钩子则自动)

Never:

  • git add -A or git add . — manually select files to avoid accidentally committing secrets or binary files
  • git push --force to a shared branch — it rewrites someone else's baseline
  • --no-verify skip hooks — unless the hooks are broken and there is a sufficient reason
  • Commit .env、credentials.json、node_modules, build artifacts

Git Debugging Tools

git bisect start HEAD <known-good-commit>  # 二分查找引入 bug 的提交
git log -- path/to/file                    # 看文件变更历史
git blame -L 10,30 path/to/file            # 看特定行是谁改的
git grep "pattern" $(git rev-list --all)   # 在所有提交中搜索

Common Excuses

Excuse Reality Consequence
"Put all changes in one commit" A giant commit cannot be reviewed, cannot be reverted, and cannot be bisected. Split it up. When reverting a giant commit, you are forced to discard all changes rather than reverting a single point; when using bisect to locate a bug, you cannot narrow it down to a specific step, making debugging time 5-10x longer.
"Commit messages don't matter, the code speaks for itself" Commit messages are for your colleague 2 years from now. The code shows what, the commit message explains why. Commit history without why → future maintainers cannot understand the motivation behind decisions → repeated discussion of already-ruled-out approaches or accidental modification of critical logic.
"Wait until everything is done before committing" Frequent commits = safety net. When something goes wrong, the revert scope is small. When a single large commit goes wrong, the revert scope = all changes; when frequent commits go wrong, the revert scope = the last logical unit, a loss difference of 10-50x.
"force-push doesn't matter, I'm the only one on this branch" CI may be running on the branch, and force-push will interrupt CI. Even if you are the only one,--force-with-lease > --force。 force-push to a shared branch → rewrites others' baseline → team members' subsequent merges fail or work is lost, with a fix cost of > 1 hour/person.
"No need for worktree, just open two clones" Two clones do not share an object store, wasting disk space and requiring two copies of npm install。 Two clones → double disk usage + double install time (~5 minutes) vs worktree sharing an object store (< 1 minute to create).
"Just run the tests once with formatting changes and behavior changes mixed together" When reverting a behavior change, you are forced to also revert the formatting. Always separate them. Mixed commit reverting a behavior change → formatting is also lost → reformatting + re-review, an extra 30-60 minutes.

Red Flags — STOP

  • More than 10 staged files that do not belong to the same change
  • Commit message = "fix", "update", "WIP" (zero information)
  • git add -A staging unrelated files together
  • Branch alive for more than 3 days with a diff over 500 lines
  • Formatting changes and behavior changes appear in the same staged set
  • force-push to main/master(rewriting shared history)
  • staged includes .env or key files
  • When resolving merge conflicts, using --theirs to resolve whole blocks instead of checking one by one

Verification Checklist

  • Each commit is a single logical unit
  • Commit messages use the <type>: <summary> format, explaining why
  • Changes are separated by concern (formatting vs behavior vs renaming)
  • No accidentally committed keys, binary files, or generated files
  • Branch is based on the latest main/master
  • Tests pass before committing
  • No force-push to shared branches

Handling Verification Failures

Failure Scenario Handling Method
Too many staged files (>10 and not part of the same change) STOP. Split by concern: commit behavior changes, formatting, and renames separately. Do not force them into one package.
Commit message is vague (fix/update/WIP) Force a rewrite of the commit message. Use <type>: <summary> format, write why not what.
Secret key or .env file accidentally staged STOP。git reset HEAD <文件> to unstage. Never commit secrets. If already committed, use git filter-branch to purge from history.
Merge conflict resolved with --theirs as a whole block STOP. Check each conflict block one by one, understand both sides' intent, then choose or manually merge. Do not blindly accept either side.
Branch alive > 3 days and diff > 500 lines Split into multiple small PRs. Short branch + small diff = fast review + fast merge.
force-push to main/master STOP. This rewrites shared history. Fix with revert or a new commit, do not rewrite.

Good and bad examples

Good — atomic commit sequence

1a2b3c feat: add Task.create() with validation
4d5e6f test: add unit tests for Task.create()
7f8g9h refactor: extract validateTask to shared module

→ Each commit is a single logical unit, independently revertible, bisectable

Bad — giant mixed commit

abc123 feat: add task creation, tests, refactor validation, fix typo in README

→ Problem: 4 changes mixed together → reverting task creation forces reverting tests, refactoring, and typo fixes too → Problem: cannot narrow the scope when using bisect to locate the bug → debugging time 5-10x

Output template

The commit sequence should follow the format below (check each commit):

## Commit Checklist
- [ ] 提交类型: feat/fix/refactor/test/docs/chore/perf/security
- [ ] 提交摘要 < 50 字符,描述 why
- [ ] 变更行数 < 300(超过需拆分)
- [ ] 格式化/重命名/行为变更已分离
- [ ] 无密钥、二进制、生成文件误提交
- [ ] 测试在提交前已通过