git-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Workflow

Git工作流

Guided workflows for common git operations that benefit from structured steps.

针对常见Git操作的引导式工作流，通过结构化步骤提升操作效率。

PR Preparation

PR准备

When preparing a pull request:

Gather context
- ```
git log main..HEAD --oneline
```
  — list all commits on the branch
- ```
git diff main...HEAD --stat
```
  — see all changed files
- ```
git status
```
  — check for uncommitted work
Draft PR content
- Title: under 70 chars, describes the change (not the branch name)
- Body: summarise the "why", list key changes, add test plan
- Use the commit history to write the summary — don't rely on memory

Push and create

bash

git push -u origin HEAD
gh pr create --title "..." --body "$(cat <<'EOF'
## Summary
- ...

## Test plan
- [ ] ...

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Verify —
```
gh pr view --web
```
to open in browser

准备拉取请求（PR）时：

收集上下文信息
- ```
git log main..HEAD --oneline
```
  — 列出当前分支的所有提交
- ```
git diff main...HEAD --stat
```
  — 查看所有已修改文件
- ```
git status
```
  — 检查是否有未提交的工作内容
撰写PR内容草稿
- 标题：不超过70个字符，清晰描述变更内容（而非分支名称）
- 正文：总结变更原因、列出关键修改点、添加测试计划
- 利用提交历史撰写总结，不要依赖记忆

推送并创建PR

bash

git push -u origin HEAD
gh pr create --title "..." --body "$(cat <<'EOF'
## 总结
- ...

## 测试计划
- [ ] ...

🤖 由[Claude Code](https://claude.com/claude-code)生成
EOF
)"

验证 — 执行
```
gh pr view --web
```
在浏览器中打开PR进行检查

Branch Cleanup

分支清理

Clean up merged branches safely:

Switch to main and pull latest
bash
```
git checkout main && git pull
```

List merged branches (excludes main/master/develop)

bash

git branch --merged main | grep -vE '^\*|main|master|develop'

Delete local merged branches

bash

git branch --merged main | grep -vE '^\*|main|master|develop' | xargs -r git branch -d

Prune remote tracking refs
bash
```
git fetch --prune
```

List remote branches with no local tracking (optional)

bash

git branch -r --merged origin/main | grep -vE 'main|master|develop|HEAD'

安全清理已合并的分支：

切换到主分支并拉取最新代码
bash
```
git checkout main && git pull
```

列出已合并的分支（排除main/master/develop分支）

bash

git branch --merged main | grep -vE '^\*|main|master|develop'

删除本地已合并的分支

bash

git branch --merged main | grep -vE '^\*|main|master|develop' | xargs -r git branch -d

清理远程跟踪引用
bash
```
git fetch --prune
```

列出无本地跟踪的远程分支（可选）

bash

git branch -r --merged origin/main | grep -vE 'main|master|develop|HEAD'

Merge Conflict Resolution

合并冲突解决

When a PR has conflicts:

Assess the conflict scope

bash

git fetch origin
git merge origin/main --no-commit --no-ff
git diff --name-only --diff-filter=U  # List conflicted files

For each conflicted file, read the file and resolve:
- Keep both changes if they're in different areas
- If architecturally incompatible, prefer the main branch's approach and re-apply the PR's intent on top

If rebase is cleaner (few commits, no shared history):

bash

git rebase origin/main
# Resolve conflicts per commit, then:
git rebase --continue

If rebase is messy (many conflicts, architectural divergence):
- Abort:
```
git rebase --abort
```
  or
```
git merge --abort
```
- Extract useful code:
```
git show origin/branch:path/to/file > /tmp/extracted.txt
```
- Apply changes manually to main
- Close original PR with explanation
Verify — run tests, check the diff looks right

当PR存在冲突时：

评估冲突范围

bash

git fetch origin
git merge origin/main --no-commit --no-ff
git diff --name-only --diff-filter=U  # 列出存在冲突的文件

针对每个冲突文件，读取文件内容并解决冲突：
- 如果变更位于不同区域，可保留双方修改
- 如果存在架构上的不兼容，优先采用主分支的实现方式，再基于此重新应用PR的变更意图

如果变基更简洁（提交数量少、无共享历史）：

bash

git rebase origin/main
# 逐个提交解决冲突，然后执行：
git rebase --continue

如果变基操作混乱（大量冲突、架构差异大）：
- 终止操作：
```
git rebase --abort
```
  或
```
git merge --abort
```
- 提取有用代码：
```
git show origin/branch:path/to/file > /tmp/extracted.txt
```
- 手动将变更应用到主分支
- 关闭原PR并附上说明
验证 — 运行测试，检查差异内容是否符合预期

Monorepo Release Tags

单体仓库发布标签

In monorepos, scope tags to the package:

bash

undefined

在单体仓库（monorepo）中，需为标签添加包范围：

bash

undefined

❌ Ambiguous in monorepos

❌ 在单体仓库中含义模糊

git tag v2.1.0

✅ Scoped to package

✅ 限定到具体包

git tag contextbricks-v2.1.0 git push origin contextbricks-v2.1.0


Pattern: `{package-name}-v{semver}`

git tag contextbricks-v2.1.0 git push origin contextbricks-v2.1.0


命名模式：`{package-name}-v{semver}`

.gitignore-First Init

.gitignore优先初始化

When creating a new repo, always create

.gitignore

BEFORE the first

git add

bash

cat > .gitignore << 'EOF'
node_modules/
.wrangler/
dist/
.dev.vars
*.log
.DS_Store
.env
.env.local
EOF

git init && git add . && git commit -m "Initial commit"

If node_modules is already tracked:

bash

git rm -r --cached node_modules/
git commit -m "Remove node_modules from tracking"

创建新仓库时，务必在首次执行

git add

前创建

.gitignore

文件：

bash

cat > .gitignore << 'EOF'
node_modules/
.wrangler/
dist/
.dev.vars
*.log
.DS_Store
.env
.env.local
EOF

git init && git add . && git commit -m "Initial commit"

如果node_modules已被跟踪：

bash

git rm -r --cached node_modules/
git commit -m "Remove node_modules from tracking"

Private Repo License Audit

私有仓库许可证审计

Before publishing or sharing a private repo:

bash

gh repo view --json visibility -q '.visibility'

PRIVATE

, ensure:

```
LICENSE
```
contains proprietary notice (not MIT/Apache)

package.json

has

"license": "UNLICENSED"

and

"private": true

No
```
CONTRIBUTING.md
```
or "contributions welcome" in README

发布或共享私有仓库前：

bash

gh repo view --json visibility -q '.visibility'

如果仓库为

PRIVATE

，需确保：

```
LICENSE
```
文件包含专有声明（而非MIT/Apache许可证）

package.json

中设置

"license": "UNLICENSED"

和

"private": true

README中无
```
CONTRIBUTING.md
```
或“欢迎贡献”相关内容