gitbutler

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitButler CLI Guide

GitButler CLI 指南

GitButler (

but

) is a modern Git client that makes history manipulation safe and reversible.

GitButler（

but

）是一款现代化Git客户端，让历史操作变得安全且可撤销。

[IMPORTANT] Detect GitButler Workspace

[重要] 检测GitButler工作区

Before running any git commands, check if GitButler is active:

bash

git branch --show-current

If the result is
gitbutler/workspace
:

[PREFER]
```
but
```
commands when equivalent exists (commit, squash, undo, amend)
[OK] Native git for operations
```
but
```
doesn't cover (cherry-pick, stash, tag, revert, blame)
[CAUTION] Some git commands can corrupt virtual branch state (see below)

Git Command Guidelines:

Prefer `but`	Use `git` freely	Use `git` with caution
`but commit` over `git commit`	`git cherry-pick`	`git reset --hard`
`but rub` over `git rebase -i`	`git stash`	`git push --force`
`but undo` over `git reset`	`git tag`	`git rebase`
`but absorb` for amending	`git revert`	`git clean`
`but reword` for messages	`git blame` , `git bisect`	`git checkout <file>`

Why prefer
but
when available? GitButler manages virtual branches through its workspace:

```
but
```
commands maintain virtual branch tracking
```
but undo
```
and oplog provide safer recovery
Some raw git commands can corrupt the virtual branch state

Quick detection pattern:

bash

undefined

在运行任何Git命令之前，请检查GitButler是否处于激活状态：

bash

git branch --show-current

如果结果为
gitbutler/workspace
：

[优先] 当存在等效命令时使用
```
but
```
命令（commit、squash、undo、amend）
[允许] 原生Git用于
```
but
```
不支持的操作（cherry-pick、stash、tag、revert、blame）
[注意] 部分Git命令可能会破坏虚拟分支状态（见下文）

Git命令使用准则：

优先使用 `but`	可自由使用 `git`	谨慎使用 `git`
`but commit` 替代 `git commit`	`git cherry-pick`	`git reset --hard`
`but rub` 替代 `git rebase -i`	`git stash`	`git push --force`
`but undo` 替代 `git reset`	`git tag`	`git rebase`
`but absorb` 用于修改提交	`git revert`	`git clean`
`but reword` 用于修改提交信息	`git blame` , `git bisect`	`git checkout <file>`

为什么有可用的
but
命令时要优先使用？ GitButler通过其工作区管理虚拟分支：

```
but
```
命令可维护虚拟分支追踪
```
but undo
```
和oplog提供更安全的恢复机制
部分原生Git命令可能会破坏虚拟分支状态

快速检测脚本：

bash

undefined

At start of git-related tasks, check:

在Git相关任务开始时，执行以下检查：

if [[ $(git branch --show-current) == "gitbutler/workspace" ]]; then # Use 'but' commands instead of 'git' fi

---

if [[ $(git branch --show-current) == "gitbutler/workspace" ]]; then # 使用'but'命令替代'git' fi

---

Key Advantages Over Git

相较于Git的核心优势

Feature	Git	GitButler
Undo operations	Complex reflog	`but undo`
Time travel	Risky reset	`but restore <sha>`
Squash commits	`rebase -i` + editor	`but rub <src> <target>`
Fix old commit	stash → rebase → amend	`but absorb`
Multiple features	Switch branches constantly	Virtual branches (simultaneous)

功能特性	Git	GitButler
撤销操作	复杂的reflog	`but undo`
时光回溯	高风险的reset操作	`but restore <sha>`
压缩提交	`rebase -i` + 编辑器	`but rub <src> <target>`
修改旧提交	stash → rebase → amend	`but absorb`
多特性并行开发	频繁切换分支	虚拟分支（可同时进行）

Essential Commands

核心命令

Inspection (Always Start Here!)

状态检查（始终从这里开始！）

bash

but status              # View workspace state (branches, commits, changes)
but oplog               # View operation history (time-travel checkpoints)

Status output explained:

╭┄00 [Unassigned Changes]
┊   g0 M calculator.py [LOCKED] 8ebedce   ← File ID, status, dependency
┊
┊╭┄al [calculator-feature]                ← Branch ID
┊●   abc1234 Commit message               ← Commit
├╯
┊
┴ 6e7da9e (common base) [origin/main]

```
g0
```
,
```
h0
```
: File/change IDs (use with
```
but rub
```
)
```
al
```
,
```
ut
```
: Branch IDs
```
[LOCKED] <sha>
```
: GitButler detected this change belongs to that commit
```
M
```
,
```
A
```
,
```
D
```
: Modified, Added, Deleted

bash

but status              # 查看工作区状态（分支、提交、变更）
but oplog               # 查看操作历史（时光回溯检查点）

状态输出说明：

╭┄00 [未分配变更]
┊   g0 M calculator.py [LOCKED] 8ebedce   ← 文件ID、状态、依赖提交
┊
┊╭┄al [calculator-feature]                ← 分支ID
┊●   abc1234 提交信息               ← 提交记录
├╯
┊
┴ 6e7da9e (公共基线) [origin/main]

```
g0
```
,
```
h0
```
: 文件/变更ID（与
```
but rub
```
配合使用）
```
al
```
,
```
ut
```
: 分支ID
```
[LOCKED] <sha>
```
: GitButler检测到该变更属于此提交
```
M
```
,
```
A
```
,
```
D
```
: 已修改、已添加、已删除

The

rub

Multi-Tool

多功能工具

rub

The

rub

command performs different operations based on source/target types:

Source	Target	Operation	Example
File	Branch	Assign	`but rub g0 al`
File	Commit	Amend	`but rub g0 abc123`
Commit	Commit	Squash	`but rub abc123 def456`
Commit	Branch	Move	`but rub abc123 ut`

Squash workflow:

bash

but status                        # Get current SHAs
but rub <source-sha> <target-sha> # Squash source INTO target
but reword <new-sha> -m "Combined message"  # Update message

rub

命令会根据源和目标的类型执行不同操作：

源类型	目标类型	操作	示例
文件	分支	分配	`but rub g0 al`
文件	提交	修改	`but rub g0 abc123`
提交	提交	压缩	`but rub abc123 def456`
提交	分支	移动	`but rub abc123 ut`

压缩提交流程：

bash

but status                        # 获取当前提交SHA
but rub <源SHA> <目标SHA> # 将源提交压缩到目标提交中
but reword <新SHA> -m "合并后的提交信息"  # 更新提交信息

Smart Amending with

absorb

智能修改提交：

absorb

When you modify code, GitButler detects which commit introduced those lines:

bash

undefined

当你修改代码时，GitButler会检测到这些代码行来自哪个提交：

bash

undefined

Edit a file, then check status

编辑文件，然后查看状态

but status

Shows: g0 M file.py [LOCKED] abc123 ← Detected dependency!

输出示例：g0 M file.py [LOCKED] abc123 ← 检测到依赖关系！

Auto-amend to the correct commit

自动将修改合并到对应提交

but absorb


GitButler automatically:

1. Analyzes which lines changed
2. Finds the commit that introduced them
3. Amends the change into that commit
4. Rebases all dependent commits

---

but absorb


GitButler会自动执行以下操作：

1. 分析哪些代码行被修改
2. 找到引入这些代码行的提交
3. 将修改合并到该提交中
4. 对所有依赖提交执行变基操作

---

Commit Editing

提交编辑

bash

but reword <sha> -m "new message"  # Edit commit message (auto-rebases)
but absorb                            # Auto-amend changes to correct commits
but absorb <file-id>                  # Absorb specific file only

bash

but reword <sha> -m "新的提交信息"  # 编辑提交信息（自动执行变基）
but absorb                            # 自动将变更合并到对应提交
but absorb <文件ID>                  # 仅合并指定文件的变更

Undo & Recovery (Time Travel)

撤销与恢复（时光回溯）

bash

but undo                      # Undo last operation (one step back)
but oplog snapshot -m "checkpoint"  # Create named checkpoint
but restore <sha> --force     # Restore to any oplog snapshot

The oplog is your time machine:

bash

but oplog                     # See all operations

bash

but undo                      # 撤销上一次操作（回退一步）
but oplog snapshot -m "检查点"  # 创建命名检查点
but restore <sha> --force     # 恢复到任意oplog快照状态

oplog是你的时光机器：

bash

but oplog                     # 查看所有操作记录

Output:

输出示例：

7f8e652 [SQUASH] SquashCommit

7f8e652 [SQUASH] 压缩提交

abc1234 [CREATE] CreateCommit

abc1234 [CREATE] 创建提交

def5678 [MOVE_HUNK] MoveHunk

def5678 [MOVE_HUNK] 移动代码块

but restore 7f8e652 --force # Go back to that point


Even undos are tracked! You can undo an undo.

---

but restore 7f8e652 --force # 回退到该操作点


即使是撤销操作也会被记录！你可以撤销之前的撤销操作。

---

Virtual Branches (Work on Multiple Features)

虚拟分支（并行开发多特性）

Create and manage branches:

bash

but branch new <name>         # Create virtual branch
but branch list               # List all branches
but branch unapply <id>       # Hide branch temporarily
but branch apply <id>         # Show branch again

Work on multiple features simultaneously:

bash

undefined

创建和管理分支：

bash

but branch new <名称>         # 创建虚拟分支
but branch list               # 列出所有分支
but branch unapply <ID>       # 临时隐藏分支
but branch apply <ID>         # 重新显示分支

同时开发多个特性：

bash

undefined

Edit files for different features

为不同特性编辑文件

vim feature-a.py vim feature-b.py

Check status - assign to different branches

查看状态 - 将变更分配到不同分支

but status

g0 M feature-a.py

h0 M feature-b.py

but rub g0 al # Assign to branch 'al' but rub h0 ut # Assign to branch 'ut'

but rub g0 al # 将变更分配到分支'al' but rub h0 ut # 将变更分配到分支'ut'

Commit to each branch

分别向每个分支提交

but commit al -m "Feature A" --only but commit ut -m "Feature B" --only


**No context switching!** Both branches are active simultaneously.

---

but commit al -m "完成特性A" --only but commit ut -m "完成特性B" --only


**无需切换上下文！** 两个分支可同时处于激活状态。

---

Committing

提交操作

bash

but commit <branch> -m "message"        # Commit ALL uncommitted changes
but commit <branch> -m "message" --only # Commit ONLY assigned changes
but commit -c -m "message"              # Create new branch and commit

[CAUTION] Important: Without

--only

but commit

includes ALL uncommitted changes!

bash

but commit <分支> -m "提交信息"        # 提交所有未提交的变更
but commit <分支> -m "提交信息" --only # 仅提交已分配的变更
but commit -c -m "提交信息"              # 创建新分支并提交

[注意] 重要提示：如果不添加

--only

参数，

but commit

会包含所有未提交的变更！

Quick Reference: Git → But

快速参考：Git → But 命令映射

Git Command	But Command
`git status`	`but status`
`git reflog`	`but oplog`
`git checkout -b`	`but branch new`
`git add`	`but rub <file> <branch>`
`git commit`	`but commit <branch> -m`
`git commit --amend`	`but rub <file> <commit>` or `but absorb`
`git rebase -i` (squash)	`but rub <commit> <commit>`
`git rebase -i` (reword)	`but reword <sha> -m`
`git reset --hard`	`but restore <sha> --force`
N/A	`but undo`
N/A	`but oplog snapshot`
N/A	`but absorb`

Git命令	But命令
`git status`	`but status`
`git reflog`	`but oplog`
`git checkout -b`	`but branch new`
`git add`	`but rub <文件> <分支>`
`git commit`	`but commit <分支> -m`
`git commit --amend`	`but rub <文件> <提交>` 或 `but absorb`
`git rebase -i` （压缩）	`but rub <提交> <提交>`
`git rebase -i` （修改信息）	`but reword <sha> -m`
`git reset --hard`	`but restore <sha> --force`
无对应命令	`but undo`
无对应命令	`but oplog snapshot`
无对应命令	`but absorb`

Common Workflows

常见工作流

Fix typo in old commit message

修复旧提交信息中的拼写错误

bash

but status                           # Find the commit SHA
but reword <sha> -m "Fixed message"

bash

but status                           # 找到目标提交的SHA
but reword <SHA> -m "修正后的提交信息"

Squash multiple commits

压缩多个提交

bash

but status                           # Get SHAs
but rub <source> <target>            # Squash
but reword <new-sha> -m "Combined" # Update message

bash

but status                           # 获取所有相关提交的SHA
but rub <源SHA> <目标SHA>            # 压缩提交
but reword <新SHA> -m "合并后的提交信息" # 更新提交信息

Amend change to old commit

将修改合并到旧提交

bash

undefined

bash

undefined

Edit the file, then:

编辑文件，然后执行：

but status # Check for [LOCKED] dependency but absorb # Auto-amend

undefined

but status # 检查是否有[LOCKED]依赖标记 but absorb # 自动合并到对应提交

undefined

Recover from mistake

从错误操作中恢复

bash

but undo                             # Quick: undo last operation

bash

but undo                             # 快速撤销上一次操作

OR

或者

but oplog # Find the right snapshot but restore <sha> --force # Go back in time

---

but oplog # 找到合适的快照 but restore <SHA> --force # 回退到指定状态

---

Error Handling

错误处理

Common Errors and Recovery

常见错误与恢复方法

Error	Cause	Recovery
`but status` fails	GitButler not initialized	Run `but` to initialize, or check `.git/gitbutler` directory
"Branch not found"	Virtual branch deleted/renamed	Run `but status` to list available branches
"Conflict detected"	Merge conflict during operation	Resolve conflicts in files, then `but commit`
"Uncommitted changes"	Operation blocked by dirty state	Commit or stash changes first
Command hangs	Large repo or network issue	Wait, or Ctrl+C and retry

错误信息	原因	恢复方法
`but status` 执行失败	GitButler未初始化	运行 `but` 命令进行初始化，或检查 `.git/gitbutler` 目录是否存在
"分支未找到"	虚拟分支已被删除/重命名	运行 `but status` 查看可用分支列表
"检测到冲突"	操作过程中出现合并冲突	手动解决文件中的冲突，然后执行 `but commit`
"存在未提交的变更"	操作因工作区未清理而被阻止	先提交或暂存变更
命令执行卡住	仓库过大或网络问题	等待一段时间，或按Ctrl+C后重试

Recovery Commands

恢复命令

bash

but undo                    # Undo last operation (safe, always works)
but oplog                   # View all operations for recovery points
but restore <sha> --force   # Restore to any previous state
but oplog snapshot list           # List named checkpoints

bash

but undo                    # 撤销上一次操作（安全，始终可用）
but oplog                   # 查看所有操作记录以找到恢复点
but restore <sha> --force   # 恢复到任意之前的状态
but oplog snapshot list           # 列出所有命名检查点

When to Use

undo

restore

何时使用

undo

restore

but undo
: Quick single-step rollback. Use when the last operation went wrong.
but restore
: Time-travel to any point. Use when you need to go back multiple operations or to a named checkpoint.

[INFO] The oplog tracks everything, including undos. You can always recover!

but undo
: 快速单步回退。适用于上一次操作出现错误的场景。
but restore
: 回退到任意历史节点。适用于需要回退多步操作或回到指定命名检查点的场景。

[提示] oplog会记录所有操作，包括撤销操作。你永远都能恢复到之前的状态！

Claude Code Hooks Integration

Claude Code Hooks 集成

GitButler integrates with Claude Code through hooks (

but claude pre-tool

but claude post-tool

but claude stop

) that automatically manage commits during AI-assisted development sessions.

Key benefits:

Auto-assigns changes to appropriate branches
Generates commit messages from user prompts
Eliminates manual
```
but commit
```
during sessions

For detailed configuration and setup instructions, see

references/hooks.md

GitButler通过钩子命令（

but claude pre-tool

、

but claude post-tool

、

but claude stop

）与Claude Code集成，可在AI辅助开发会话中自动管理提交。

核心优势：

自动将变更分配到合适的分支
根据用户提示生成提交信息
消除会话中手动执行
```
but commit
```
的需求

如需详细配置和设置说明，请查看

references/hooks.md

。

Reference Files

参考文档

For detailed documentation, see:

```
references/cheatsheet.md
```
- Quick command reference with git → but mappings
```
references/tutorial.md
```
- Comprehensive step-by-step workflows
```
references/hooks.md
```
- Claude Code hooks setup guide

如需更详细的文档，请查看：

```
references/cheatsheet.md
```
- 快速命令参考，包含Git→But命令映射
```
references/tutorial.md
```
- 全面的分步工作流指南
```
references/hooks.md
```
- Claude Code钩子设置指南

gitbutler

Original

Translation

GitButler CLI Guide

GitButler CLI 指南

[IMPORTANT] Detect GitButler Workspace

[重要] 检测GitButler工作区

At start of git-related tasks, check:

在Git相关任务开始时，执行以下检查：

Key Advantages Over Git

相较于Git的核心优势

Essential Commands

核心命令

Inspection (Always Start Here!)

状态检查（始终从这里开始！）

The rub Multi-Tool

多功能工具rub

Smart Amending with absorb

智能修改提交：absorb

Edit a file, then check status

编辑文件，然后查看状态

Shows: g0 M file.py [LOCKED] abc123 ← Detected dependency!

输出示例：g0 M file.py [LOCKED] abc123 ← 检测到依赖关系！

Auto-amend to the correct commit

自动将修改合并到对应提交

Commit Editing

提交编辑

Undo & Recovery (Time Travel)

撤销与恢复（时光回溯）

Output:

输出示例：

7f8e652 [SQUASH] SquashCommit

7f8e652 [SQUASH] 压缩提交

abc1234 [CREATE] CreateCommit

abc1234 [CREATE] 创建提交

def5678 [MOVE_HUNK] MoveHunk

def5678 [MOVE_HUNK] 移动代码块

Virtual Branches (Work on Multiple Features)

虚拟分支（并行开发多特性）

Edit files for different features

为不同特性编辑文件

Check status - assign to different branches

查看状态 - 将变更分配到不同分支

g0 M feature-a.py

g0 M feature-a.py

h0 M feature-b.py

h0 M feature-b.py

Commit to each branch

分别向每个分支提交

Committing

提交操作

Quick Reference: Git → But

快速参考：Git → But 命令映射

Common Workflows

常见工作流

Fix typo in old commit message

修复旧提交信息中的拼写错误

Squash multiple commits

压缩多个提交

Amend change to old commit

将修改合并到旧提交

Edit the file, then:

编辑文件，然后执行：

Recover from mistake

从错误操作中恢复

OR

或者

Error Handling

错误处理

Common Errors and Recovery

常见错误与恢复方法

Recovery Commands

恢复命令

When to Use undo vs restore

何时使用undo vs restore

Claude Code Hooks Integration

Claude Code Hooks 集成

Reference Files

参考文档

The
`rub`
Multi-Tool

多功能工具
`rub`

Smart Amending with
`absorb`

智能修改提交：
`absorb`

When to Use
`undo`
vs
`restore`

何时使用
`undo`
vs
`restore`