forktree

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install forktree
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 forktree。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

forktree 是一个仅使用标准库的 Python 3.11+ CLI，为 shell 管道、CI 任务和无人值守的编程智能体封装 Git worktree 操作。其 create 命令会在添加 worktree 前执行七项安全预检，其他命令则支持列出、移除、垃圾回收、初始化配置和诊断。
对于 Openclaw Skills 用户，关键优势在于其对自动化友好的行为：数据输出到 stdout，诊断信息输出到 stderr，并通过定义的退出代码，让脚本能够可靠地处理成功、安全拒绝、Git 故障和严格配置错误。该工具没有第三方 Python 依赖。

应用场景

通过安全预检后，为智能体任务创建隔离的 worktree。
将新 worktree 的绝对路径保存到 shell 变量中，不混入进度消息。
以 JSON 或不含表头的 TSV 格式列出项目 worktree，供脚本和下游工具使用。
移除指定的 worktree，或识别过期 worktree，以便根据闲置时间和合并状态进行清理。
forktree doctor
检查安装和环境诊断信息。
在本地开发和 CI 中应用一致的项目级或用户级 TOML 配置。

工作原理

按照 CLI 标志、项目 .forktree.toml、~/.config/forktree/config.toml，再到内置默认值的顺序解析设置。
对于 create，在请求 Git 创建 worktree 前执行七项安全预检；如果操作被拒绝，将以非零代码退出且不会创建 worktree。
将机器可读的结果发送到 stdout，例如新 worktree 的绝对路径、JSON 或 TSV 格式的 worktree 列表，或排序后的垃圾回收候选项。
将警告、错误、详细进度和 doctor 诊断信息发送到 stderr；错误格式为 forktree: : 。
返回脚本可用来区分成功、预检拒绝、Git／设置／用法故障以及严格配置错误的退出代码。
使用 remove 移除指定的 worktree，或使用 gc 根据闲置时间和合并状态评估过期 worktree；使用 gc --dry-run 预览清理操作。

配置指南

使用项目文档说明的安装方法安装 forktree CLI，然后确保 forktree 可执行文件位于 PATH 中，并且可使用 Python 3.11 或更高版本导入该包。此技能文件未指定安装命令或包管理器操作步骤。
验证安装：
command -v forktree
python3 -c "import forktree"
forktree --help
forktree doctor
创建包含有效解析设置的项目配置：
forktree init
配置按以下顺序解析：CLI 标志、项目 .forktree.toml、用户 ~/.config/forktree/config.toml，以及内置默认值。设置 FORKTREE_STRICT=1 可为所有子命令启用严格配置处理；或者使用 NO_COLOR=1 禁用人类可读输出中的 ANSI 颜色。严格模式下，格式错误的 TOML 将以代码 3 退出。
适用于智能体的安全调用示例：
wt=$(forktree create "$project_path" "$slug" 2>/tmp/forktree.err) || {
cat /tmp/forktree.err
exit 1
}
cd "$wt"
继续操作前请检查退出状态并读取 stderr：create 失败意味着没有创建 worktree。使用 forktree --help 查看特定命令的标志。

数据架构

forktree 使用 TOML 进行配置，并确保命令输出适用于 shell 自动化。
数据或输出 格式和行为
项目配置 项目目录中的 .forktree.toml
用户配置 ~/.config/forktree/config.toml
配置优先级 CLI 标志 > 项目配置 > 用户配置 > 内置默认值
create stdout 一行内容，包含新 worktree 的绝对路径
list --porcelain stdout 每个 worktree 一行，不含表头的 TSV
list --json stdout JSON 对象数组；通过管道输出时为紧凑格式，在 TTY 中则为美化格式
gc --dry-run stdout 排序后的 worktree slug，每行一个
诊断信息 警告、错误、详细进度和 doctor 报告输出到 stderr
技能文件未列出完整的 TOML 架构；有关支持的配置字段，请参阅项目 README。错误格式为 forktree: : 。退出代码：成功为 0，预检拒绝为 1，Git 操作、设置钩子或用法故障为 2，严格配置错误为 3。

高级特性

七项安全预检可保护 worktree 创建；
create
返回非零结果即明确表示不得继续操作。
适用于管道的 stdout／stderr 分离支持命令替换和
jq
等工具，避免诊断文本混入数据。
list
同时支持机器可读的 JSON 和 porcelain TSV 输出。
gc
根据闲置时间和合并状态评估过期 worktree；
gc --dry-run
会在执行操作前预览排序后的清理候选项。
TOML 配置支持 CLI、项目级和用户级设置，并可通过 --strict FORKTREE_STRICT=1
启用可选的严格错误处理。
可选的
[worktree].setup_script
钩子会在 worktree 设置期间运行；该功能需显式启用，且钩子以非零代码退出时会移除 worktree。
doctor
提供诊断信息并始终以代码 0 退出；请查看其 stderr 输出了解发现的问题。
CLI 需要 Python 3.11+，且仅使用标准库，没有第三方依赖。

name: forktree description: Use the forktree Python CLI to safely create, list, remove, and garbage-collect git worktrees from a shell pipeline, CI job, or unattended coding agent. Wraps git worktree with safety pre-flights, TOML configuration, and a strict stdout/stderr contract. homepage: https://github.com/BottaniCals/forktree