git-workflows

Git 和 GitHub 工作流

直接使用原生 git 和 gh 命令。gw 仅处理由 issue 驱动的工作树（gw git worktree create/finish）。

何时启用

• 创建 git 提交、推送、拉取、创建分支
• 创建或审查拉取请求
• 处理 GitHub issue
• 查看 git 历史记录、差异或 blame
• 解决合并冲突
• 管理 issue 工作所需的工作树

Conventional Commits 格式

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

<optional body>

<optional footer>

类型

Type	用途	示例
feat	新功能	feat(auth): add OAuth refresh
fix	Bug 修复	fix(landing): correct hero sizing
docs	文档	docs: update API reference
refactor	代码重构	refactor(engine): extract validation
test	测试	test(billing): add webhook tests
chore	维护	chore: update dependencies
perf	性能	perf(queries): add index for lookups

范围

使用包名：engine、landing、plant、aspen、heartwood、prism、foliage、lumen、billing

日常工作流

# Check state
git status
git diff --stat

# Stage and commit
git add .
git commit -m "feat(engine): add GlassCard hover animation"

# Push
git push

# Create PR
gh pr create --title "feat(engine): add GlassCard hover animation" --body "..."

读取操作

git status                       # Working tree status
git diff                         # Unstaged changes
git diff --staged                # Staged changes
git diff main...HEAD             # Changes on this branch vs main
git log --oneline -20            # Recent commits
git log --stat -5                # Commits with file stats
git blame src/lib/file.ts        # Line-by-line authorship
git show abc123                  # Show commit details

写入操作

git add .                                    # Stage all
git add src/lib/specific-file.ts             # Stage specific file
git commit -m "feat: add new feature"        # Commit
git push                                     # Push to remote
git push -u origin feature/new-thing         # Push new branch
git pull --rebase                            # Pull with rebase
git branch feature/new-thing                 # Create branch
git switch feature/new-thing                 # Switch branches
git stash                                    # Stash changes
git stash pop                                # Pop stash
git restore --staged file.ts                 # Unstage files

工作树（通过 gw）

由 issue 驱动的工作树是 gw 相较于原生 git 唯一额外提供的功能：

# Create worktree for an issue (fetches title, generates branch name)
gw git worktree create 1234 --write

# Finish: commit, push, merge into main, remove worktree
gw git worktree finish --write

# Finish with custom message
gw git worktree finish --write -m "feat: implement dark mode"

# Finish without merging (just commit + push + remove)
gw git worktree finish --write --no-merge

# List worktrees (raw git)
git worktree list

GitHub 操作

# Issues (via gw for browse TUI, or raw gh)
gw gh issue list                             # TUI browse with skills
gh issue create --title "..." --body "..."   # Create issue
gh issue close 123                           # Close issue

# Pull Requests
gh pr create --title "feat: ..." --body "..."
gh pr list
gh pr view 123
gh pr merge 123

# CI/Workflow runs
gh run list
gh run view 12345

分支管理

# Feature branch workflow
git switch -c feature/user-auth
# ... work ...
git add . && git commit -m "feat(auth): implement JWT"
git push -u origin feature/user-auth
gh pr create

# Branch naming
feature/feature-name     # New features
fix/bug-description      # Bug fixes
refactor/what-changed    # Refactors

合并冲突

# Identify conflicts
git status                    # Shows conflicted files

# Resolve manually, then:
git add resolved-file.ts
git commit -m "fix: resolve merge conflicts"

# Or accept one side
git checkout --ours file.ts   # Keep current branch version
git checkout --theirs file.ts # Keep incoming version

撤销操作

git restore file.ts                  # Discard working changes
git restore --staged file.ts         # Unstage
git reset --soft HEAD~1              # Undo commit, keep changes staged
git reset HEAD~1                     # Undo commit, keep changes unstaged
git revert abc123                    # Create new commit undoing a change

最佳实践

应该：

• 每次提交只包含一项逻辑变更
• 使用描述性主题行，且少于 50 个字符
• 使用祈使语气（“Add”，而不是“Added”）
• 在页脚引用 issue（Fixes #123）
• 使用工作树并行处理 issue

不应该：

• 不要对 main/master 强制推送
• 不要提交密钥、.env 文件或 API 密钥
• 不要在一次提交中合并无关变更
• 不要使用含糊的消息（“fix stuff”“update”）