Git Workflow

Git 工作流

Essential Git patterns for effective version control. Eliminates ~120-150 lines of redundant Git guidance per agent.

实现高效版本控制的必备Git模式。可减少每个Agent约120-150行重复的Git指导内容。

Commit Best Practices

提交最佳实践

Conventional Commits Format

规范提交格式

<type>(<scope>): <subject>

<body>

<footer>

Types:

```
feat
```
: New feature
```
fix
```
: Bug fix
```
docs
```
: Documentation only
```
refactor
```
: Code change that neither fixes bug nor adds feature
```
perf
```
: Performance improvement
```
test
```
: Adding or updating tests
```
chore
```
: Build process, dependencies, tooling

Examples:

bash

feat(auth): add OAuth2 authentication

Implements OAuth2 flow using Google provider.
Includes token refresh and validation.

Closes #123

fix(api): handle null response in user endpoint

Previously crashed when user not found.
Now returns 404 with error message.

perf(db): optimize user query with index

Reduces query time from 500ms to 50ms.

<type>(<scope>): <subject>

<body>

<footer>

类型：

```
feat
```
: 新功能
```
fix
```
: 修复Bug
```
docs
```
: 仅更新文档
```
refactor
```
: 既不修复Bug也不添加功能的代码变更
```
perf
```
: 性能优化
```
test
```
: 添加或更新测试
```
chore
```
: 构建流程、依赖、工具相关变更

示例：

bash

feat(auth): add OAuth2 authentication

Implements OAuth2 flow using Google provider.
Includes token refresh and validation.

Closes #123

fix(api): handle null response in user endpoint

Previously crashed when user not found.
Now returns 404 with error message.

perf(db): optimize user query with index

Reduces query time from 500ms to 50ms.

Atomic Commits

原子提交

bash

undefined

bash

undefined

Good: Each commit does one thing

良好实践：每个提交仅做一件事

git commit -m "feat: add user authentication" git commit -m "test: add auth tests" git commit -m "docs: update API docs for auth"

Bad: Multiple unrelated changes

不良实践：包含多个无关变更

git commit -m "add auth, fix bugs, update docs"

undefined

git commit -m "add auth, fix bugs, update docs"

undefined

Branching Strategy

分支策略

Git Flow (Feature Branches)

Git Flow（功能分支）

bash

undefined

bash

undefined

Create feature branch from main

从main分支创建功能分支

git checkout main git pull origin main git checkout -b feature/user-authentication

Work on feature with regular commits

在功能分支上进行常规提交

git add src/auth.py git commit -m "feat(auth): implement login endpoint"

Keep branch updated with main

保持分支与main分支同步

git checkout main git pull origin main git checkout feature/user-authentication git rebase main # Or: git merge main

git checkout main git pull origin main git checkout feature/user-authentication git rebase main # 或：git merge main

Push and create PR

推送分支并创建PR

git push -u origin feature/user-authentication

undefined

git push -u origin feature/user-authentication

undefined

Trunk-Based Development

主干开发模式

bash

undefined

bash

undefined

Work directly on main with short-lived branches

在main分支上直接使用短期分支开发

git checkout main git pull origin main git checkout -b fix/null-pointer

Make small change

进行小修改

git commit -m "fix: handle null in user query" git push origin fix/null-pointer

Merge immediately via PR

通过PR立即合并

undefined

undefined

Common Workflows

常见工作流

Updating Branch with Latest Changes

用最新变更更新分支

bash

undefined

bash

undefined

Option 1: Rebase (cleaner history)

选项1：变基（更清晰的提交历史）

git checkout feature-branch git fetch origin git rebase origin/main

Resolve conflicts if any

如有冲突则解决

git add resolved_file.py git rebase --continue

Option 2: Merge (preserves history)

选项2：合并（保留完整历史）

git checkout feature-branch git merge origin/main

undefined

git checkout feature-branch git merge origin/main

undefined

Undoing Changes

撤销变更

bash

undefined

bash

undefined

Undo last commit (keep changes)

撤销最后一次提交（保留变更内容）

git reset --soft HEAD~1

Undo last commit (discard changes)

撤销最后一次提交（丢弃变更内容）

git reset --hard HEAD~1

Undo changes to specific file

撤销特定文件的变更

git checkout -- file.py

Revert a commit (creates new commit)

回滚提交（创建新的提交）

git revert abc123

Amend last commit

修改最后一次提交

git add forgotten_file.py git commit --amend --no-edit

undefined

git add forgotten_file.py git commit --amend --no-edit

undefined

Stashing Work

暂存工作内容

bash

undefined

bash

undefined

Save current work temporarily

临时保存当前工作

git stash

List stashes

列出所有暂存

git stash list

Apply most recent stash

应用最近一次暂存

git stash pop

Apply specific stash

应用指定暂存

git stash apply stash@{0}

Create named stash

创建命名暂存

git stash save "WIP: authentication feature"

undefined

git stash save "WIP: authentication feature"

undefined

Cherry-Picking Commits

挑选提交

bash

undefined

bash

undefined

Apply specific commit from another branch

将其他分支的特定提交应用到当前分支

git cherry-pick abc123

Cherry-pick multiple commits

挑选多个提交

git cherry-pick abc123 def456

Cherry-pick without committing

挑选提交但不自动提交

git cherry-pick -n abc123

undefined

git cherry-pick -n abc123

undefined

Resolving Conflicts

解决冲突

bash

undefined

bash

undefined

When conflicts occur during merge/rebase

在合并/变基时发生冲突

1. Check conflicted files

1. 查看冲突文件

git status

2. Edit files to resolve conflicts

2. 编辑文件解决冲突

Look for conflict markers:

查找冲突标记：

<<<<<<< HEAD Your changes

Their changes

branch-name

<<<<<<< HEAD 你的变更

对方的变更

branch-name

3. Mark as resolved

3. 标记文件为已解决

git add resolved_file.py

4. Continue operation

4. 继续操作

git rebase --continue # or git merge --continue

undefined

git rebase --continue # 或 git merge --continue

undefined

Viewing History

查看提交历史

bash

undefined

bash

undefined

Compact log

简洁日志

git log --oneline -10

Graphical log

图形化日志

git log --graph --oneline --all

Commits by author

按作者查看提交

git log --author="John Doe"

Commits affecting specific file

查看影响特定文件的提交

git log -- path/to/file.py

See changes in commit

查看提交的具体变更

git show abc123

Compare branches

对比分支差异

git diff main..feature-branch

undefined

git diff main..feature-branch

undefined

Branch Management

分支管理

bash

undefined

bash

undefined

List branches

列出分支

git branch -a # All branches (local + remote)

git branch -a # 所有分支（本地+远程）

Delete local branch

删除本地分支

git branch -d feature-branch # Safe delete (merged only) git branch -D feature-branch # Force delete

git branch -d feature-branch # 安全删除（仅合并过的分支） git branch -D feature-branch # 强制删除

Delete remote branch

删除远程分支

git push origin --delete feature-branch

Rename branch

重命名分支

git branch -m old-name new-name

Track remote branch

跟踪远程分支

git checkout --track origin/feature-branch

undefined

git checkout --track origin/feature-branch

undefined

Create lightweight tag

创建轻量标签

git tag v1.0.0

Create annotated tag (recommended)

创建附注标签（推荐）

git tag -a v1.0.0 -m "Release version 1.0.0"

Push tags to remote

将标签推送到远程仓库

git push origin v1.0.0 git push origin --tags # Push all tags

git push origin v1.0.0 git push origin --tags # 推送所有标签

Checkout tag

切换到指定标签

git checkout v1.0.0

Delete tag

删除标签

git tag -d v1.0.0 git push origin --delete v1.0.0

undefined

git tag -d v1.0.0 git push origin --delete v1.0.0

undefined

Advanced Operations

高级操作

Interactive Rebase

交互式变基

bash

undefined

bash

undefined

Edit last 3 commits

编辑最近3次提交

git rebase -i HEAD~3

Options in editor:

编辑器中的选项：

pick = use commit

pick = 使用该提交

reword = change commit message

reword = 修改提交信息

edit = stop to amend commit

edit = 暂停以修改提交

squash = combine with previous commit

squash = 与上一个提交合并

fixup = like squash but discard message

fixup = 类似squash，但丢弃提交信息

drop = remove commit

drop = 删除该提交

undefined

undefined

Bisect (Find Bug Introduction)

二分查找（定位Bug引入点）

bash

undefined

bash

undefined

Start bisect

开始二分查找

git bisect start git bisect bad # Current version has bug git bisect good v1.0.0 # This version was good

git bisect start git bisect bad # 当前版本存在Bug git bisect good v1.0.0 # 该版本无Bug

Git checks out middle commit

Git会检出中间版本

Test if bug exists

测试是否存在Bug

git bisect bad # if bug exists git bisect good # if bug doesn't exist

git bisect bad # 如果存在Bug git bisect good # 如果不存在Bug

Git narrows down until finding first bad commit

Git会逐步缩小范围直到找到第一个引入Bug的提交

git bisect reset # Return to original branch

undefined

git bisect reset # 返回原分支

undefined

Blame (Find Who Changed Line)

追溯代码变更（查看每行的修改者）

bash

undefined

bash

undefined

See who last modified each line

查看每行最后一次修改的作者

git blame file.py

Ignore whitespace changes

忽略空白字符变更

git blame -w file.py

Show specific line range

查看指定行范围的变更

git blame -L 10,20 file.py

undefined

git blame -L 10,20 file.py

undefined

Git Hooks

Git 钩子

bash

undefined

bash

undefined

Pre-commit hook (runs before commit)

提交前钩子（提交前运行）

.git/hooks/pre-commit

#!/bin/bash npm run lint npm test

Pre-push hook (runs before push)

推送前钩子（推送前运行）

.git/hooks/pre-push

#!/bin/bash npm run test:integration

undefined

#!/bin/bash npm run test:integration

undefined

Best Practices

最佳实践

✅ DO

✅ 建议

Commit frequently with atomic changes
Write clear, descriptive commit messages
Pull before push to avoid conflicts
Review changes before committing (
```
git diff --staged
```
)
Use branches for features and fixes
Keep commits small and focused

频繁提交，保持每个提交为原子变更
编写清晰、描述性强的提交信息
推送前先拉取，避免冲突
提交前检查变更内容（
```
git diff --staged
```
）
使用分支开发功能和修复Bug
保持提交内容小而聚焦

❌ DON'T

❌ 禁忌

Commit sensitive data (use
```
.gitignore
```
)
Commit generated files (build artifacts,
```
node_modules
```
)
Force push to shared branches (
```
git push --force
```
)
Commit work-in-progress to main
Include multiple unrelated changes in one commit
Rewrite public history

提交敏感数据（使用
```
.gitignore
```
）
提交生成文件（构建产物、
```
node_modules
```
）
对共享分支强制推送（
```
git push --force
```
）
将未完成的工作提交到main分支
在一个提交中包含多个无关变更
重写公开的提交历史

.gitignore Patterns

.gitignore 模式

gitignore

undefined

gitignore

undefined

Dependencies

依赖

node_modules/ venv/ pycache/

Build outputs

构建输出

dist/ build/ *.pyc *.o *.exe

IDE

.vscode/ .idea/ *.swp

Secrets

敏感信息

.env *.key *.pem secrets.yml

OS

系统文件

.DS_Store Thumbs.db

Logs

日志

*.log logs/

undefined

*.log logs/

undefined

Quick Command Reference

快速命令参考

bash

undefined

bash

undefined

Status and diff

状态与差异

git status git diff git diff --staged

Commit

提交

git add . git commit -m "message" git push

Branch

分支

git branch git checkout -b branch-name git merge branch-name

Update

更新

git pull git fetch

Undo

撤销

git reset HEAD~1 git checkout -- file git revert commit-hash

History

历史

git log git log --oneline git show commit-hash

undefined

git log git log --oneline git show commit-hash

undefined

Remember

注意事项

Commit often - Small commits are easier to review and revert
Descriptive messages - Future you will thank present you
Pull before push - Stay synchronized with team
Use branches - Keep main stable
Review before commit - Check what is being committed

频繁提交 - 小提交更易于评审和回滚
描述性信息 - 未来的你会感谢现在的自己
推送前拉取 - 与团队保持同步
使用分支 - 保持main分支稳定
提交前检查 - 确认要提交的内容

git-workflow

Original

Translation

Git Workflow

Git 工作流

Commit Best Practices

提交最佳实践

Conventional Commits Format

规范提交格式

Atomic Commits

原子提交

Good: Each commit does one thing

良好实践：每个提交仅做一件事

Bad: Multiple unrelated changes

不良实践：包含多个无关变更

Branching Strategy

分支策略

Git Flow (Feature Branches)

Git Flow（功能分支）

Create feature branch from main

从main分支创建功能分支

Work on feature with regular commits

在功能分支上进行常规提交

Keep branch updated with main

保持分支与main分支同步

Push and create PR

推送分支并创建PR

Trunk-Based Development

主干开发模式

Work directly on main with short-lived branches

在main分支上直接使用短期分支开发

Make small change

进行小修改

Merge immediately via PR

通过PR立即合并

Common Workflows

常见工作流

Updating Branch with Latest Changes

用最新变更更新分支

Option 1: Rebase (cleaner history)

选项1：变基（更清晰的提交历史）

Resolve conflicts if any

如有冲突则解决

Option 2: Merge (preserves history)

选项2：合并（保留完整历史）

Undoing Changes

撤销变更

Undo last commit (keep changes)

撤销最后一次提交（保留变更内容）

Undo last commit (discard changes)

撤销最后一次提交（丢弃变更内容）

Undo changes to specific file

撤销特定文件的变更

Revert a commit (creates new commit)

回滚提交（创建新的提交）

Amend last commit

修改最后一次提交

Stashing Work

暂存工作内容

Save current work temporarily

临时保存当前工作

List stashes

列出所有暂存

Apply most recent stash

应用最近一次暂存

Apply specific stash

应用指定暂存

Create named stash

创建命名暂存

Cherry-Picking Commits

挑选提交

Apply specific commit from another branch

将其他分支的特定提交应用到当前分支

Cherry-pick multiple commits

挑选多个提交

Cherry-pick without committing

挑选提交但不自动提交

Resolving Conflicts

解决冲突

When conflicts occur during merge/rebase