worktrunk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Worktrunk

Help users work with Worktrunk, a CLI tool for managing git worktrees.

帮助用户使用Worktrunk，一款用于管理git worktrees的CLI工具。

Available Documentation

可用文档

Reference files are synced from worktrunk.dev documentation:

reference/config.md: User and project configuration (LLM, hooks, command defaults)
reference/hook.md: Hook types, timing, and execution order
reference/switch.md, merge.md, list.md, etc.: Command documentation
reference/llm-commits.md: LLM commit message generation
reference/tips-patterns.md: Language-specific tips and patterns
reference/shell-integration.md: Shell integration debugging
reference/troubleshooting.md: Troubleshooting for LLM and hooks (Claude-specific)

For command-specific options, run

wt <command> --help

. For configuration, follow the workflows below.

参考文件同步自worktrunk.dev文档：

reference/config.md：用户与项目配置（LLM、钩子、命令默认值）
reference/hook.md：钩子类型、执行时机与顺序
reference/switch.md、merge.md、list.md等：命令文档
reference/llm-commits.md：LLM提交信息生成
reference/tips-patterns.md：特定语言的技巧与模式
reference/shell-integration.md：Shell集成调试
reference/troubleshooting.md：LLM与钩子的故障排查（针对Claude的内容）

如需查看命令的具体选项，请运行

wt <command> --help

。配置相关内容，请遵循以下工作流程。

Two Types of Configuration

两种配置类型

Worktrunk uses two separate config files with different scopes and behaviors:

Worktrunk使用两个独立的配置文件，它们的作用范围和行为有所不同：

User Config (

~/.config/worktrunk/config.toml

)

用户配置（

~/.config/worktrunk/config.toml

）

Scope: Personal preferences for the individual developer
Location:
```
~/.config/worktrunk/config.toml
```
(never checked into git)
Contains: LLM integration, worktree path templates, command settings, user hooks, approved commands
Permission model: Always propose changes and get consent before editing
See:
```
reference/config.md
```
for detailed guidance

作用范围：针对单个开发者的个人偏好设置
位置：
```
~/.config/worktrunk/config.toml
```
（绝不会提交到git）
包含内容：LLM集成、工作树路径模板、命令设置、用户钩子、已批准命令
权限模式：修改前必须先提出变更并获得用户同意
详情请见：
```
reference/config.md
```
中的详细指南

Project Config (

.config/wt.toml

)

项目配置（

.config/wt.toml

）

Scope: Team-wide automation shared by all developers
Location:
```
<repo>/.config/wt.toml
```
(checked into git)
Contains: Hooks for worktree lifecycle (post-create, pre-merge, etc.)
Permission model: Proactive (create directly, changes are reversible via git)
See:
```
reference/hook.md
```
for detailed guidance

作用范围：团队共享的自动化设置，适用于所有开发者
位置：
```
<repo>/.config/wt.toml
```
（会提交到git）
包含内容：工作树生命周期钩子（post-create、pre-merge等）
权限模式：主动创建（可通过git撤销变更）
详情请见：
```
reference/hook.md
```
中的详细指南

Determining Which Config to Use

如何选择配置类型

When a user asks for configuration help, determine which type based on:

User config indicators:

"set up LLM" or "configure commit generation"
"change where worktrees are created"
"customize commit message templates"
Affects only their environment

Project config indicators:

"set up hooks for this project"
"automate npm install"
"run tests before merge"
Affects the entire team

Both configs may be needed: For example, setting up commit message generation requires user config, but automating quality checks requires project config.

当用户请求配置帮助时，可根据以下指标判断应使用哪种配置：

用户配置指标：

“设置LLM”或“配置提交信息生成”
“修改工作树创建路径”
“自定义提交信息模板”
仅影响用户个人环境

项目配置指标：

“为当前项目设置钩子”
“自动化npm install”
“合并前运行测试”
影响整个团队

可能需要同时使用两种配置：例如，设置提交信息生成需要用户配置，而自动化质量检查则需要项目配置。

Core Workflows

核心工作流程

Setting Up Commit Message Generation (User Config)

设置提交信息生成（用户配置）

Most common request. See

reference/llm-commits.md

for supported tools and exact command syntax.

Detect available tools

bash

which claude codex llm aichat 2>/dev/null

If none installed, recommend Claude Code (already available in Claude Code sessions)

Propose config change — Get the exact command from

reference/llm-commits.md

toml

[commit.generation]
command = "..."  # see reference/llm-commits.md for tool-specific commands

Ask: "Should I add this to your config?"

After approval, apply
- Check if config exists:
```
wt config show
```
- If not, guide through
```
wt config create
```
- Read, modify, write preserving structure

Suggest testing

bash

wt step commit --show-prompt | head  # verify prompt builds
wt merge  # in a repo with uncommitted changes

这是最常见的请求。请查看

reference/llm-commits.md

了解支持的工具和具体命令语法。

检测可用工具

bash

which claude codex llm aichat 2>/dev/null

若未安装任何工具，推荐Claude Code（Claude Code会话中已内置）

提出配置变更建议 — 从

reference/llm-commits.md

获取具体命令

toml

[commit.generation]
command = "..."  # 请查看reference/llm-commits.md获取对应工具的命令

询问用户：“是否要将此配置添加到你的文件中？”

获得批准后应用变更
- 检查配置文件是否存在：
```
wt config show
```
- 若不存在，引导用户运行
```
wt config create
```
- 读取、修改并保存文件，同时保留原有结构

建议进行测试

bash

wt step commit --show-prompt | head  # 验证提示信息是否正常生成
wt merge  # 在有未提交变更的仓库中执行

Setting Up Project Hooks (Project Config)

设置项目钩子（项目配置）

Common request for workflow automation. Follow discovery process:

Detect project type

bash

ls package.json Cargo.toml pyproject.toml

Identify available commands
- For npm: Read
```
package.json
```
  scripts
- For Rust: Common cargo commands
- For Python: Check pyproject.toml
Design appropriate hooks (7 hook types available)
- Dependencies (fast, must complete) →
```
post-create
```
- Tests/linting (must pass) →
```
pre-commit
```
  or
```
pre-merge
```
- Long builds, dev servers →
```
post-start
```
- Terminal/IDE updates →
```
post-switch
```
- Deployment →
```
post-merge
```
- Cleanup tasks →
```
pre-remove
```

Validate commands work

bash

npm run lint  # verify exists
which cargo   # verify tool exists

Create
.config/wt.toml

toml

# Install dependencies when creating worktrees
post-create = "npm install"

# Validate code quality before committing
[pre-commit]
lint = "npm run lint"
typecheck = "npm run typecheck"

# Run tests before merging
pre-merge = "npm test"

Add comments explaining choices
Suggest testing
bash
```
wt switch --create test-hooks
```

See
reference/hook.md
for complete details.

这是工作流自动化的常见请求，请遵循以下流程：

检测项目类型

bash

ls package.json Cargo.toml pyproject.toml

识别可用命令
- 对于npm项目：读取
```
package.json
```
  中的脚本
- 对于Rust项目：常用cargo命令
- 对于Python项目：检查pyproject.toml
设计合适的钩子（支持7种钩子类型）
- 依赖安装（快速，必须完成）→
```
post-create
```
- 测试/代码检查（必须通过）→
```
pre-commit
```
  或
```
pre-merge
```
- 长时构建、开发服务器启动→
```
post-start
```
- 终端/IDE更新→
```
post-switch
```
- 部署→
```
post-merge
```
- 清理任务→
```
pre-remove
```

验证命令可正常运行

bash

npm run lint  # 验证命令存在
which cargo   # 验证工具已安装

创建
.config/wt.toml
文件

toml

# 创建工作树时安装依赖
post-create = "npm install"

# 提交前验证代码质量
[pre-commit]
lint = "npm run lint"
typecheck = "npm run typecheck"

# 合并前运行测试
pre-merge = "npm test"

添加注释说明选择理由
建议进行测试
bash
```
wt switch --create test-hooks
```

详情请见
reference/hook.md
。

Adding Hooks to Existing Config

向现有配置添加钩子

When users want to add automation to an existing project:

Read existing config:
```
cat .config/wt.toml
```
Determine hook type - When should this run?
- Creating worktree (blocking) →
```
post-create
```
- Creating worktree (background) →
```
post-start
```
- Every switch →
```
post-switch
```
- Before committing →
```
pre-commit
```
- Before merging →
```
pre-merge
```
- After merging →
```
post-merge
```
- Before removal →
```
pre-remove
```

Handle format conversion if needed

Single command to named table:

toml

# Before
post-create = "npm install"

# After (adding db:migrate)
[post-create]
install = "npm install"
migrate = "npm run db:migrate"

Preserve existing structure and comments

当用户希望为现有项目添加自动化流程时：

读取现有配置：
```
cat .config/wt.toml
```
确定钩子类型 - 钩子应在何时运行？
- 创建工作树时（阻塞式）→
```
post-create
```
- 创建工作树时（后台执行）→
```
post-start
```
- 每次切换工作树时→
```
post-switch
```
- 提交前→
```
pre-commit
```
- 合并前→
```
pre-merge
```
- 合并后→
```
post-merge
```
- 删除工作树前→
```
pre-remove
```

如有需要，转换格式

从单个命令转换为命名表：

toml

# 转换前
post-create = "npm install"

# 转换后（添加db:migrate）
[post-create]
install = "npm install"
migrate = "npm run db:migrate"

保留现有结构与注释

Validation Before Adding Commands

添加命令前的验证

Before adding hooks, validate:

bash

undefined

添加钩子前，请进行以下验证：

bash

undefined

Verify command exists

验证命令是否存在

which npm which cargo

For npm, verify script exists

对于npm项目，验证脚本是否存在

npm run lint --dry-run

For shell commands, check syntax

对于Shell命令，检查语法

bash -n -c "if [ true ]; then echo ok; fi"


**Dangerous patterns** — Warn users before creating hooks with:
- Destructive commands: `rm -rf`, `DROP TABLE`
- External dependencies: `curl http://...`
- Privilege escalation: `sudo`

bash -n -c "if [ true ]; then echo ok; fi"


**危险模式提示** — 在创建包含以下内容的钩子前，请向用户发出警告：
- 破坏性命令：`rm -rf`、`DROP TABLE`
- 外部依赖：`curl http://...`
- 权限提升：`sudo`

Permission Models

权限模式

User Config: Conservative

用户配置：保守模式

Never edit without consent - Always show proposed change and wait for approval
Never install tools - Provide commands for users to run themselves
Preserve structure - Keep existing comments and organization
Validate first - Ensure TOML is valid before writing

未经同意绝不修改 - 必须先展示拟变更内容并等待用户批准
绝不自动安装工具 - 仅提供命令供用户自行运行
保留原有结构 - 保留现有注释与文件组织方式
先验证再保存 - 确保TOML格式有效后再写入文件

Project Config: Proactive

项目配置：主动模式

Create directly - Changes are versioned, easily reversible
Validate commands - Check commands exist before adding
Explain choices - Add comments documenting why hooks exist
Warn on danger - Flag destructive operations before adding

直接创建 - 变更会被版本化，可通过git轻松撤销
验证命令有效性 - 添加前检查命令是否存在
说明选择理由 - 添加注释解释钩子的作用
危险操作警告 - 添加破坏性操作前向用户发出警告

Common Tasks Reference

常见任务参考

User Config Tasks

用户配置任务

Set up commit message generation →
```
reference/llm-commits.md
```

Customize worktree paths →

reference/config.md#worktree-path-template

Custom commit templates →
```
reference/llm-commits.md#templates
```
Configure command defaults →
```
reference/config.md#command-settings
```
Set up personal hooks →
```
reference/config.md#user-hooks
```

设置提交信息生成 →
```
reference/llm-commits.md
```

自定义工作树路径 →

reference/config.md#worktree-path-template

自定义提交模板 →
```
reference/llm-commits.md#templates
```
配置命令默认值 →
```
reference/config.md#command-settings
```
设置个人钩子 →
```
reference/config.md#user-hooks
```

Project Config Tasks

项目配置任务

Set up hooks for new project →
```
reference/hook.md
```
Add hook to existing config →
```
reference/hook.md#configuration
```
Use template variables →
```
reference/hook.md#template-variables
```
Add dev server URL to list →
```
reference/config.md#dev-server-url
```

为新项目设置钩子 →
```
reference/hook.md
```
向现有配置添加钩子 →
```
reference/hook.md#configuration
```
使用模板变量 →
```
reference/hook.md#template-variables
```
向列表添加开发服务器URL →
```
reference/config.md#dev-server-url
```

Key Commands

关键命令

bash

undefined

bash

undefined

View all configuration

查看所有配置

wt config show

Create initial user config

创建初始用户配置

wt config create

LLM setup guide

LLM设置指南

wt config --help

undefined

wt config --help

undefined

Loading Additional Documentation

加载更多文档

Load reference files for detailed configuration, hook specifications, and troubleshooting.

Find specific sections with grep:

bash

grep -A 20 "## Setup" reference/llm-commits.md
grep -A 30 "### post-create" reference/hook.md
grep -A 20 "## Warning Messages" reference/shell-integration.md

加载参考文件以获取详细配置、钩子规范与故障排查信息。

使用grep查找特定内容：

bash

grep -A 20 "## Setup" reference/llm-commits.md
grep -A 30 "### post-create" reference/hook.md
grep -A 20 "## Warning Messages" reference/shell-integration.md

Advanced: Agent Handoffs

进阶：Agent转交

When the user requests spawning a worktree with Claude in a background session ("spawn a worktree for...", "hand off to another agent"), use the appropriate pattern for their terminal multiplexer:

tmux (check

$TMUX

env var):

bash

tmux new-session -d -s <branch-name> "wt switch --create <branch-name> -x claude -- '<task description>'"

Zellij (check

$ZELLIJ

env var):

bash

zellij run -- wt switch --create <branch-name> -x claude -- '<task description>'

Requirements (all must be true):

User explicitly requests spawning/handoff
User is in a supported multiplexer (tmux or Zellij)
User's CLAUDE.md or explicit instruction authorizes this pattern

Do not use this pattern for normal worktree operations.

Example (tmux):

bash

tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"

Example (Zellij):

bash

zellij run -- wt switch --create fix-auth-bug -x claude -- \
  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'

当用户请求在后台会话中使用Claude创建工作树（例如“为……创建工作树”“转交至其他Agent”），请根据用户使用的终端复用工具选择合适的命令：

tmux（检查

$TMUX

环境变量）：

bash

tmux new-session -d -s <branch-name> "wt switch --create <branch-name> -x claude -- '<task description>'"

Zellij（检查

$ZELLIJ

环境变量）：

bash

zellij run -- wt switch --create <branch-name> -x claude -- '<task description>'"

要求（必须全部满足）：

用户明确请求创建/转交
用户正在使用支持的复用工具（tmux或Zellij）
用户的CLAUDE.md或明确指令允许使用此模式

请勿将此模式用于常规工作树操作。

示例（tmux）：

bash

tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
  '登录会话5分钟后过期，请找到会话超时配置并将其延长至24小时。'"

示例（Zellij）：

bash

zellij run -- wt switch --create fix-auth-bug -x claude -- \
  '登录会话5分钟后过期，请找到会话超时配置并将其延长至24小时。'"

worktrunk

Original

Translation

Worktrunk

Worktrunk

Available Documentation

可用文档

Two Types of Configuration

两种配置类型

User Config (~/.config/worktrunk/config.toml)

用户配置（~/.config/worktrunk/config.toml）

Project Config (.config/wt.toml)

项目配置（.config/wt.toml）

Determining Which Config to Use

如何选择配置类型

Core Workflows

核心工作流程

Setting Up Commit Message Generation (User Config)

设置提交信息生成（用户配置）

Setting Up Project Hooks (Project Config)

设置项目钩子（项目配置）

Adding Hooks to Existing Config

向现有配置添加钩子

Validation Before Adding Commands

添加命令前的验证

Verify command exists

验证命令是否存在

For npm, verify script exists

对于npm项目，验证脚本是否存在

For shell commands, check syntax

对于Shell命令，检查语法

Permission Models

权限模式

User Config: Conservative

用户配置：保守模式

Project Config: Proactive

项目配置：主动模式

Common Tasks Reference

常见任务参考

User Config Tasks

用户配置任务

Project Config Tasks

项目配置任务

Key Commands

关键命令

View all configuration

查看所有配置

Create initial user config

创建初始用户配置

LLM setup guide

LLM设置指南

Loading Additional Documentation

加载更多文档

Advanced: Agent Handoffs

进阶：Agent转交

User Config (
`~/.config/worktrunk/config.toml`
)

用户配置（
`~/.config/worktrunk/config.toml`
）

Project Config (
`.config/wt.toml`
)

项目配置（
`.config/wt.toml`
）