git-workflows

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git & GitHub Workflows (via Grove Wrap)

Git & GitHub工作流（基于Grove Wrap）

All git and GitHub operations go through
gw
— never use raw

git

gh

commands directly. Grove Wrap adds safety tiers, Conventional Commits enforcement, protected branch guards, and agent-safe defaults.

所有git和GitHub操作都通过
gw
执行——请勿直接使用原生

git

或

gh

命令。 Grove Wrap提供了安全分级、Conventional Commits强制校验、受保护分支防护以及Agent安全默认配置。

When to Activate

启用场景

Activate this skill when:

Making git commits, pushing, pulling, branching, or stashing
Creating, reviewing, or merging pull requests
Creating, viewing, or closing GitHub issues
Checking CI/workflow run status
Reviewing git history, diffs, or blame
Resolving merge conflicts
Any version control operation

当出现以下场景时启用本技能：

执行git提交、推送、拉取、分支操作或暂存操作
创建、评审或合并pull request
创建、查看或关闭GitHub issue
检查CI/工作流运行状态
查看git历史、差异或blame信息
解决合并冲突
任何版本控制操作

Safety System

安全体系

gw enforces a three-tier safety model:

Tier	Flag Required	Examples
READ	None	`gw git status` , `gw git log` , `gw gh pr list`
WRITE	`--write`	`gw git commit` , `gw git push` , `gw git pull` , `gw gh pr create`
DANGEROUS	`--write --force`	`gw git reset` , `gw git force-push` , `gw git rebase`

Protected branches (

main

master

production

staging

) can NEVER be force-pushed, even with

--force

Agent mode (auto-detected for Claude Code): stricter row limits, force operations blocked, all operations audit-logged.

Dry run any command with

--dry-run

to preview what would happen.

gw强制采用三级安全模型：

级别	需要的标志	示例
只读	无	`gw git status` , `gw git log` , `gw gh pr list`
写入	`--write`	`gw git commit` , `gw git push` , `gw git pull` , `gw gh pr create`
危险操作	`--write --force`	`gw git reset` , `gw git force-push` , `gw git rebase`

受保护分支（

main

、

master

、

production

、

staging

）绝对禁止强制推送，即使添加

--force

参数也无法执行。

Agent模式（Claude Code会自动检测）：更严格的行限制、强制操作被阻断、所有操作都会记录审计日志。

任何命令都可添加

--dry-run

参数试运行，预览即将执行的操作效果。

Conventional Commits Format

Conventional Commits格式

gw validates commit messages against Conventional Commits automatically. Format:

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

<optional body>

<optional footer>

gw会自动根据Conventional Commits规范校验提交信息，格式如下：

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

<optional body>

<optional footer>

Commit Types

提交类型

Type	Purpose	Example
`feat`	New feature	`feat: add user authentication`
`fix`	Bug fix	`fix: correct validation error`
`docs`	Documentation	`docs: update README`
`style`	Code formatting	`style: format with prettier`
`refactor`	Code restructure	`refactor: extract helper function`
`test`	Add/modify tests	`test: add auth tests`
`chore`	Maintenance	`chore: update dependencies`
`perf`	Performance	`perf: optimize query speed`
`ci`	CI/CD changes	`ci: fix deploy workflow`

Breaking changes: Add an exclamation mark after the type, e.g. feat!: replace XML config with YAML

类型	用途	示例
`feat`	新增功能	`feat: add user authentication`
`fix`	修复Bug	`fix: correct validation error`
`docs`	文档修改	`docs: update README`
`style`	代码格式调整	`style: format with prettier`
`refactor`	代码重构	`refactor: extract helper function`
`test`	新增/修改测试	`test: add auth tests`
`chore`	维护性变更	`chore: update dependencies`
`perf`	性能优化	`perf: optimize query speed`
`ci`	CI/CD修改	`ci: fix deploy workflow`

破坏性变更：在类型后添加感叹号，例如 feat!: replace XML config with YAML

Git Commands — Reading (Always Safe)

Git命令——只读类（始终安全）

bash

gw git status                  # Enhanced git status
gw git log                     # Formatted commit history
gw git log --limit 20          # Last 20 commits
gw git diff                    # Show changes
gw git diff --staged           # Show staged changes
gw git blame file.ts           # Blame with context
gw git show abc123             # Show commit details

bash

gw git status                  # 增强版git status
gw git log                     # 格式化的提交历史
gw git log --limit 20          # 最近20条提交记录
gw git diff                    # 展示变更内容
gw git diff --staged           # 展示暂存区的变更
gw git blame file.ts           # 带上下文的blame信息
gw git show abc123             # 展示提交详情

Git Commands — Writing (Needs

--write

)

Git命令——写入类（需要

--write

参数）

bash

gw git add --write .                              # Stage files
gw git add --write src/lib/thing.ts               # Stage specific file
gw git commit --write -m "feat: add new feature"  # Commit (validates conventional commits!)
gw git push --write                               # Push to remote
gw git pull --write                               # Pull from remote
gw git pull --write --rebase                      # Pull with rebase strategy
gw git branch --write feature/new-thing           # Create branch
gw git switch --write feature/new-thing           # Switch branches
gw git stash --write                              # Stash changes
gw git stash --write pop                          # Pop stash
gw git unstage --write file.ts                    # Unstage files

bash

gw git add --write .                              # 暂存所有文件
gw git add --write src/lib/thing.ts               # 暂存指定文件
gw git commit --write -m "feat: add new feature"  # 提交（自动校验Conventional Commits规范!）
gw git push --write                               # 推送到远程仓库
gw git pull --write                               # 从远程仓库拉取
gw git pull --write --rebase                      # 以rebase策略拉取
gw git branch --write feature/new-thing           # 创建分支
gw git switch --write feature/new-thing           # 切换分支
gw git stash --write                              # 暂存变更
gw git stash --write pop                          # 恢复暂存的变更
gw git unstage --write file.ts                    # 取消暂存文件

Git Commands — Dangerous (Needs

--write --force

)

Git命令——危险操作（需要

--write --force

参数）

bash

gw git push --write --force          # Force push (blocked to protected branches!)
gw git reset --write --force HEAD~1  # Hard reset
gw git rebase --write --force main   # Rebase onto main
gw git merge --write --force feature # Merge branches

bash

gw git push --write --force          # 强制推送（受保护分支会被拦截!）
gw git reset --write --force HEAD~1  # 硬重置
gw git rebase --write --force main   # 基于main分支rebase
gw git merge --write --force feature # 合并分支

Grove Shortcuts

Grove快捷命令

These combine common multi-step operations into single commands:

bash

undefined

这些命令将常见的多步操作合并为单条命令：

bash

undefined

Quick save: stage all + WIP commit

快速保存：暂存所有变更 + WIP提交

gw git save --write

Quick sync: fetch + rebase + push

快速同步：fetch + rebase + push

gw git sync --write

WIP commit that skips hooks

跳过钩子的WIP提交

gw git wip --write

Undo last commit (keeps changes staged)

撤销上一次提交（保留变更在暂存区）

gw git undo --write

Amend last commit message

修改上一次提交的信息

gw git amend --write -m "better message"

FAST MODE: skip ALL hooks, commit + push in one shot

快速模式：跳过所有钩子，一次性提交+推送

gw git fast --write -m "fix: emergency hotfix"

undefined

gw git fast --write -m "fix: emergency hotfix"

undefined

Branching Strategy

分支策略

Branch Naming

分支命名规范

feature/feature-name    # New features
fix/bug-description     # Bug fixes
experiment/new-idea     # Experiments
release/v1.0.0          # Releases

feature/feature-name    # 新功能分支
fix/bug-description     # Bug修复分支
experiment/new-idea     # 实验性分支
release/v1.0.0          # 发布分支

Feature Branch Workflow

功能分支工作流

bash

undefined

bash

undefined

Create and switch to feature branch

创建并切换到功能分支

gw git branch --write feature/user-auth gw git switch --write feature/user-auth

Work and commit

开发并提交

gw git add --write . gw git commit --write -m "feat: add JWT authentication"

Push and create PR

推送并创建PR

gw git push --write gw gh pr create --write --title "feat: add JWT authentication"

undefined

gw git push --write gw gh pr create --write --title "feat: add JWT authentication"

undefined

GitHub — Pull Requests

GitHub——Pull Requests

bash

undefined

bash

undefined

Reading (always safe)

只读类（始终安全）

gw gh pr list # List open PRs gw gh pr view 123 # View PR details gw gh pr status # PR status (CI, reviews, etc.)

gw gh pr list # 列出打开的PR gw gh pr view 123 # 查看PR详情 gw gh pr status # PR状态（CI、评审情况等）

Writing (needs --write)

写入类（需要--write参数）

gw gh pr create --write --title "feat: new thing" --body "Description" gw gh pr comment --write 123 "LGTM!" gw gh pr merge --write 123 # Merge PR (prompts for confirmation)

undefined

gw gh pr create --write --title "feat: new thing" --body "Description" gw gh pr comment --write 123 "LGTM!" gw gh pr merge --write 123 # 合并PR（会弹出确认提示）

undefined

GitHub — Issues

GitHub——Issues

bash

undefined

bash

undefined

Reading (always safe)

只读类（始终安全）

gw gh issue list # List open issues gw gh issue view 456 # View issue details

gw gh issue list # 列出打开的issue gw gh issue view 456 # 查看issue详情

Writing (needs --write)

写入类（需要--write参数）

gw gh issue create --write --title "Bug: thing broke" gw gh issue close --write 456

undefined

gw gh issue create --write --title "Bug: thing broke" gw gh issue close --write 456

undefined

GitHub — Workflow Runs (CI)

GitHub——工作流运行（CI）

bash

undefined

bash

undefined

Reading (always safe)

只读类（始终安全）

gw gh run list # List recent runs gw gh run view 12345678 # View run details gw gh run watch 12345678 # Watch a running workflow

gw gh run list # 列出最近的运行记录 gw gh run view 12345678 # 查看运行详情 gw gh run watch 12345678 # 监听运行中的工作流

Writing (needs --write)

写入类（需要--write参数）

gw gh run rerun --write 12345678 --failed # Rerun failed jobs gw gh run cancel --write 12345678 # Cancel a run

undefined

gw gh run rerun --write 12345678 --failed # 重新运行失败的任务 gw gh run cancel --write 12345678 # 取消运行

undefined

GitHub — API & Rate Limits

GitHub——API与速率限制

bash

undefined

bash

undefined

GET requests (always safe)

GET请求（始终安全）

gw gh api repos/AutumnsGrove/Lattice

POST/PATCH (needs --write)

POST/PATCH请求（需要--write参数）

gw gh api --write repos/{owner}/{repo}/labels -X POST -f name="bug"

DELETE (needs --write --force)

DELETE请求（需要--write --force参数）

gw gh api --write --force repos/{owner}/{repo}/labels/old -X DELETE

Check rate limit status

查看速率限制状态

gw gh rate-limit

undefined

gw gh rate-limit

undefined

GitHub — Project Boards

GitHub——项目看板

bash

gw gh project list              # List project boards
gw gh project view              # View current project

bash

gw gh project list              # 列出项目看板
gw gh project view              # 查看当前项目

Commit Examples

提交示例

Feature

功能提交

bash

gw git commit --write -m "feat: add dark mode toggle

- Implement theme switching logic
- Add localStorage persistence
- Update CSS variables"

bash

gw git commit --write -m "feat: add dark mode toggle

- 实现主题切换逻辑
- 添加localStorage持久化
- 更新CSS变量"

Bug Fix with Issue Link

关联Issue的Bug修复

bash

gw git commit --write -m "fix: correct timezone handling bug

Fixes off-by-one error in date calculations.

Closes #123"

bash

gw git commit --write -m "fix: correct timezone handling bug

修复了日期计算中的差一错误。

Closes #123"

Breaking Change

破坏性变更

bash

gw git commit --write -m "feat!: replace XML config with YAML

BREAKING CHANGE: XML configuration no longer supported.
See docs/migration.md for upgrade instructions."

bash

gw git commit --write -m "feat!: replace XML config with YAML

BREAKING CHANGE: 不再支持XML配置。
升级说明请查看 docs/migration.md。"

Agent-Optimized Commands (NEW)

Agent优化命令（新增）

These commands are specifically designed for agentic workflows:

这些命令是专门为Agent工作流设计的：

Session Start (Always run this first!)

会话启动（请始终优先运行此命令!）

bash

gw context                      # One-shot session snapshot (rich output)
gw --json context               # JSON snapshot (branch, changes, packages, issues)

bash

gw context                      # 一站式会话快照（富文本输出）
gw --json context               # JSON格式快照（分支、变更、包、issue信息）

Ship with Auto-Stage

自动暂存发布

bash

undefined

bash

undefined

Stage all + format + check + commit + push in ONE command

一站式完成：暂存所有变更 + 格式化 + 校验 + 提交 + 推送

gw git ship --write -a -m "feat: implement feature"

Equivalent to: gw git add --write . && gw git ship --write -m "..."

等价于: gw git add --write . && gw git ship --write -m "..."

undefined

undefined

PR Preparation

PR准备

bash

gw git pr-prep                  # Full PR readiness report
gw --json git pr-prep           # JSON: commits, files, packages, suggested title

bash

gw git pr-prep                  # 完整的PR就绪报告
gw --json git pr-prep           # JSON格式：提交、文件、包、建议标题

Targeted CI

定向CI检查

bash

gw ci --affected               # Only check packages with changes
gw ci --affected --fail-fast   # Fast feedback: stop on first failure
gw ci --diagnose               # Structured error output when steps fail
gw --json ci --affected        # JSON with parsed error details

bash

gw ci --affected               # 仅检查有变更的包
gw ci --affected --fail-fast   # 快速反馈：第一个失败就停止
gw ci --diagnose               # 步骤失败时输出结构化错误信息
gw --json ci --affected        # 带解析后错误详情的JSON输出

Batch Issue Creation

批量创建Issue

bash

undefined

bash

undefined

Create multiple issues from JSON

从JSON批量创建issue

gw gh issue batch --write --from-json issues.json echo '[{"title":"Bug: thing","labels":["bug"]}]' | gw gh issue batch --write --from-json -

undefined

gw gh issue batch --write --from-json issues.json echo '[{"title":"Bug: thing","labels":["bug"]}]' | gw gh issue batch --write --from-json -

undefined

Impact Analysis (via gf)

影响分析（通过gf）

bash

gf impact src/lib/auth.ts       # Who imports this? What tests? Which routes?
gf test-for src/lib/auth.ts     # Find tests covering this file
gf diff-summary                 # Structured diff with per-file stats
gf --json impact src/lib/auth.ts  # All of the above as parseable JSON

bash

gf impact src/lib/auth.ts       # 哪些模块导入了这个文件？对应哪些测试？哪些路由？
gf test-for src/lib/auth.ts     # 查找覆盖这个文件的测试
gf diff-summary                 # 带每个文件统计的结构化diff
gf --json impact src/lib/auth.ts  # 以上所有信息的可解析JSON格式

Common Workflows

常见工作流

Start a new feature

启动新功能开发

bash

gw context                      # Orient: what branch, what's changed?
gw git branch --write feature/my-feature
gw git switch --write feature/my-feature

bash

gw context                      # 确认当前状态：当前分支、已有变更？
gw git branch --write feature/my-feature
gw git switch --write feature/my-feature

... make changes ...

... 开发变更 ...

gw git ship --write -a -m "feat: implement my feature" gw git pr-prep # Check readiness gw gh pr create --write --title "feat: implement my feature"

undefined

gw git ship --write -a -m "feat: implement my feature" gw git pr-prep # 检查PR就绪状态 gw gh pr create --write --title "feat: implement my feature"

undefined

Quick fix and ship

快速修复并发布

bash

gw git fast --write -m "fix: correct typo in header"

bash

gw git fast --write -m "fix: correct typo in header"

Ship with full checks

带完整校验的发布

bash

gw git ship --write -a -m "feat: add auth refresh"

bash

gw git ship --write -a -m "feat: add auth refresh"

This does: auto-stage all → format → type-check → commit → push

执行逻辑：自动暂存所有 → 格式化 → 类型校验 → 提交 → 推送

undefined

undefined

Check CI before merging

合并前检查CI状态

bash

gw ci --affected --fail-fast    # Quick: only changed packages
gw gh pr status                 # See CI status on current PR
gw gh run list                  # See recent workflow runs
gw gh run watch 12345678        # Watch the current run

bash

gw ci --affected --fail-fast    # 快速检查：仅变更的包
gw gh pr status                 # 查看当前PR的CI状态
gw gh run list                  # 查看最近的工作流运行记录
gw gh run watch 12345678        # 监听当前运行的工作流

Pull latest changes

拉取最新变更

bash

gw git pull --write             # Pull from remote (merge strategy)
gw git pull --write --rebase    # Pull with rebase (cleaner history)
gw git pull --write origin main # Pull specific remote/branch

bash

gw git pull --write             # 从远程拉取（merge策略）
gw git pull --write --rebase    # 以rebase策略拉取（更干净的历史）
gw git pull --write origin main # 拉取指定远程/分支

Sync branch with main

分支与main同步

bash

gw git sync --write             # Fetch + rebase + push

bash

gw git sync --write             # Fetch + rebase + push

Save work in progress

保存进行中的工作

bash

gw git save --write             # Stage all + WIP commit

bash

gw git save --write             # 暂存所有 + WIP提交

or

或者

gw git stash --write # Stash without committing

undefined

gw git stash --write # 暂存不提交

undefined

Merge Conflicts

合并冲突

When conflicts occur during sync/rebase/merge:

bash

gw git status                   # See conflicted files

当同步/rebase/合并过程中出现冲突时：

bash

gw git status                   # 查看冲突文件

Edit files to resolve conflicts:

编辑文件解决冲突：

<<<<<<< HEAD

Your changes

你的变更

=======

Incoming changes

传入的变更

>>>>>>> feature-branch

After resolving:

解决后：

gw git add --write resolved-file.ts gw git commit --write -m "fix: resolve merge conflicts"

undefined

gw git add --write resolved-file.ts gw git commit --write -m "fix: resolve merge conflicts"

undefined

Worktrees

工作树

Work on multiple branches simultaneously without stashing:

bash

gw git worktree add --write ../grove-hotfix fix/urgent
gw git worktree list
gw git worktree remove --write ../grove-hotfix

无需暂存即可同时在多个分支上工作：

bash

gw git worktree add --write ../grove-hotfix fix/urgent
gw git worktree list
gw git worktree remove --write ../grove-hotfix

Best Practices

最佳实践

DO

DON'T

禁止做法

Use raw
```
git
```
or
```
gh
```
commands directly
Force-push to protected branches
Use vague messages ("Update files", "Fix stuff")
Combine multiple unrelated changes in one commit
Skip the
```
--write
```
flag (even if it seems tedious — it's a safety net)

直接使用原生
```
git
```
或
```
gh
```
命令
向受保护分支强制推送
使用模糊的提交信息（比如「Update files」、「Fix stuff」）
单次提交包含多个不相关的变更
省略
```
--write
```
参数（即使看起来麻烦——这是安全防护网）

Troubleshooting

问题排查

"Protected branch"

「受保护分支」报错

You tried to force-push to

main

. Create a PR instead:

bash

gw gh pr create --write --title "My changes"

你尝试向

main

分支强制推送，请创建PR：

bash

gw gh pr create --write --title "My changes"

"Rate limit exhausted"

「速率限制耗尽」报错

bash

gw gh rate-limit               # Check when it resets

bash

gw gh rate-limit               # 查看重置时间

Committed to wrong branch

提交到了错误的分支

bash

gw git log --limit 1            # Note the commit hash
gw git switch --write correct-branch

bash

gw git log --limit 1            # 记录提交哈希
gw git switch --write correct-branch

Cherry-pick the commit, then remove from wrong branch

拣选该提交，然后从错误分支移除该提交

undefined

undefined

Need to undo last commit

需要撤销上一次提交

bash

gw git undo --write             # Keeps changes staged

bash

gw git undo --write             # 保留变更在暂存区

git-workflows

Original

Translation

Git & GitHub Workflows (via Grove Wrap)

Git & GitHub工作流（基于Grove Wrap）

When to Activate

启用场景

Safety System

安全体系

Conventional Commits Format

Conventional Commits格式

Commit Types

提交类型

Git Commands — Reading (Always Safe)

Git命令——只读类（始终安全）

Git Commands — Writing (Needs --write)

Git命令——写入类（需要--write参数）

Git Commands — Dangerous (Needs --write --force)

Git命令——危险操作（需要--write --force参数）

Grove Shortcuts

Grove快捷命令

Quick save: stage all + WIP commit

快速保存：暂存所有变更 + WIP提交

Quick sync: fetch + rebase + push

快速同步：fetch + rebase + push

WIP commit that skips hooks

跳过钩子的WIP提交

Undo last commit (keeps changes staged)

撤销上一次提交（保留变更在暂存区）

Amend last commit message

修改上一次提交的信息

FAST MODE: skip ALL hooks, commit + push in one shot

快速模式：跳过所有钩子，一次性提交+推送

Branching Strategy

分支策略

Branch Naming

分支命名规范

Feature Branch Workflow

功能分支工作流

Create and switch to feature branch

创建并切换到功能分支

Work and commit

开发并提交

Push and create PR

推送并创建PR

GitHub — Pull Requests

GitHub——Pull Requests

Reading (always safe)

只读类（始终安全）

Writing (needs --write)

写入类（需要--write参数）

GitHub — Issues

GitHub——Issues

Reading (always safe)

只读类（始终安全）

Writing (needs --write)

写入类（需要--write参数）

GitHub — Workflow Runs (CI)

GitHub——工作流运行（CI）

Reading (always safe)

只读类（始终安全）

Writing (needs --write)

写入类（需要--write参数）

GitHub — API & Rate Limits

GitHub——API与速率限制

GET requests (always safe)

GET请求（始终安全）

POST/PATCH (needs --write)

POST/PATCH请求（需要--write参数）

DELETE (needs --write --force)

DELETE请求（需要--write --force参数）

Check rate limit status

查看速率限制状态

GitHub — Project Boards

GitHub——项目看板

Commit Examples

提交示例

Feature

功能提交

Bug Fix with Issue Link

Git Commands — Writing (Needs
`--write`
)

Git命令——写入类（需要
`--write`
参数）

Git Commands — Dangerous (Needs
`--write --force`
)

Git命令——危险操作（需要
`--write --force`
参数）