Skip to content

gitstq/gitworktree

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
gitworktree
gitworktree
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
pyproject.toml
pyproject.toml
 
 
setup.py
setup.py
 
 

Repository files navigation

简体中文 | 繁體中文 | English

Python License Zero Deps Platform

简体中文

gitworktree -- 轻量级 Git Worktree 管理 CLI 工具

让 git worktree 管理像切换分支一样简单

快速开始 · 详细文档 · 安装部署 · 贡献指南

🎉 项目介绍

gitworktree 是一款轻量级的 Git Worktree 命令行管理工具，旨在让开发者能够以最简洁、最直观的方式管理多个工作树（worktree）。

核心定位

一键管理，告别繁琐的 git worktree 命令。

gitworktree 将 Git 原生的 worktree 子命令封装为 8 个简洁的子命令，提供彩色终端输出、交互式选择器、智能命名模板等开箱即用的功能，让你专注于编码本身。

解决的痛点

痛点 gitworktree 的方案
原生 git worktree 命令参数繁多、记忆成本高 提供 8 个语义化子命令，wt list、wt add 一目了然
AI 编码助手（Claude Code、Codex 等）需要并行工作树 提供 一键创建/切换 工作树的能力，完美适配 AI Agent 工作流
手动管理多个 worktree 容易遗漏、出错 提供 孤儿工作树自动检测 与 批量清理 功能
无法直观看到各 worktree 的分支状态 提供 实时分支状态追踪（ahead/behind/dirty），彩色高亮一目了然
不同项目需要不同的 worktree 目录结构 支持 自定义命名模板，灵活适配各种工作流

与同类工具的差异化

  • 零外部依赖 -- 仅使用 Python 标准库，无需安装任何第三方包，最大兼容性
  • 彩色 TUI 输出 -- 自动检测终端能力，支持 NO_COLOR 环境变量
  • 交互式选择器 -- wt switch 提供数字编号的交互式工作树切换
  • 智能命名模板 -- 支持 {branch}、{short_hash}、{author}、{date} 占位符
  • 分支状态追踪 -- 实时显示 ahead/behind/dirty 状态，无需手动 git fetch
  • 孤儿检测 -- 自动识别分支已删除但工作树仍残留的情况

灵感来源

随着 AI 编码助手（如 Claude Code、OpenAI Codex、Cursor 等）的兴起，开发者越来越多地需要在同一仓库中并行处理多个任务。每个 AI Agent 可能需要独立的工作树来避免冲突，而原生的 git worktree 命令行体验远不够友好。gitworktree 正是在这一背景下诞生的 -- 让并行工作树管理变得像切换分支一样自然。

✨ 核心特性

  • 🌳 交互式工作树切换器 -- 带彩色状态标记的数字选择器，告别手动 cd
  • 📊 实时分支状态 -- 直观显示 ahead / behind / dirty / diverged 状态
  • 🏷️ 智能命名模板 -- 支持 {branch}、{short_hash}、{author}、{date} 自定义目录命名
  • 🧹 孤儿工作树检测与清理 -- 自动发现分支已删除的残留工作树，一键清理
  • 🔄 批量操作支持 -- 合并后自动删除分支和工作树，清理时批量处理
  • 📋 多格式输出 -- 支持 table（表格）、json（结构化）、compact（紧凑）三种输出格式
  • 🎨 精美的彩色 TUI -- 自动检测终端能力，尊重 NO_COLOR 环境变量
  • 🚀 零依赖 -- 纯 Python 标准库实现，Python 3.8+ 即可运行
  • 💻 跨平台 -- 完美支持 Windows、macOS、Linux

🚀 快速开始

环境要求

依赖 最低版本
Python >= 3.8
Git >= 2.15

安装

# 通过 pip 安装（推荐）
pip install gitworktree

# 或者克隆仓库后以开发模式安装
git clone https://github.com/gitstq/gitworktree.git
cd gitworktree
pip install -e .

安装完成后，你将获得两个可执行命令：wt 和 gitworktree，两者功能完全一致，推荐使用更简短的 wt。

快速上手

# 查看所有工作树
wt list

# 为已有分支创建工作树
wt add feature/login

# 创建新分支并同时创建工作树
wt add -b feature/new

# 交互式切换工作树
wt switch

# 移除指定工作树
wt remove feature/old

# 将 feature 分支合并到主分支
wt merge feature/done

# 查看工作树详细信息
wt info feature/login

# 清理孤儿工作树
wt clean

# 获取工作树路径（适合脚本调用）
wt path feature/login

📖 详细使用指南

wt list -- 列出所有工作树

列出当前仓库中所有的工作树，并显示分支名称、路径、状态和最后修改时间。

# 默认表格格式输出
wt list

# 紧凑格式输出
wt list --format compact

# JSON 格式输出（适合脚本处理）
wt list --format json

# 按日期排序
wt list --sort date

# 按分支名排序
wt list --sort branch

# 只显示有未提交更改的工作树
wt list --filter dirty

# 只显示干净的工作树
wt list --filter clean

参数说明：

参数 缩写 说明 默认值
--format -f 输出格式：table / json / compact table
--sort -s 排序方式：name / date / branch name
--filter -- 过滤条件：clean / dirty 无

别名： ls

wt add -- 创建工作树

为指定分支创建一个新的工作树。支持为已有分支创建，也支持同时创建新分支。

# 为已有分支创建工作树
wt add feature/login

# 创建新分支并同时创建工作树
wt add -b feature/new

# 创建新分支并跟踪远程分支
wt add -b feature/new --track origin/feature/new

# 使用自定义命名模板
wt add feature/auth --template "{branch}-{short_hash}"

# 指定工作树基础目录
wt add feature/api --base-dir ".wt"

参数说明：

参数 缩写 说明 默认值
branch -- 分支名称（必填） --
--create-branch -b 创建新分支 false
--track -- 跟踪远程分支 无
--template -- 路径命名模板 {branch}
--base-dir -- 工作树基础目录 .worktrees

可用模板占位符：

占位符 说明 示例
{branch} 分支名称 feature/login
{short_hash} 短提交哈希（7 位） a1b2c3d
{author} 提交作者 zhangsan
{date} 日期（YYYY-MM-DD） 2025-01-15

别名： create

wt switch -- 交互式切换工作树

提供交互式数字选择器，让你快速切换到目标工作树。

# 交互式选择工作树
wt switch

# 输出 shell 可执行的 cd 命令（适合 shell 集成）
wt switch --shell

# 配合 eval 使用，直接切换目录
eval "$(wt switch --shell)"

参数说明：

参数 说明 默认值
--shell 输出 cd <path> 格式的 shell 命令 false

别名： sw、cd

wt remove -- 移除工作树

移除指定分支或路径对应的工作树，支持强制移除和自动清理。

# 按分支名移除（会弹出确认提示）
wt remove feature/old

# 强制移除，跳过确认
wt remove feature/old --force

# 按路径移除
wt remove /path/to/worktree

# 移除但不清理过期的 worktree 条目
wt remove feature/old --no-prune

参数说明：

参数 缩写 说明 默认值
identifier -- 分支名或工作树路径（必填） --
--force -f 跳过确认，强制移除 false
--no-prune -- 不执行 prune 清理 false

⚠️ 注意： 不允许移除主工作树（main worktree）。如果分支已合并，工具会提示你可以安全删除该分支。

别名： rm、delete

wt merge -- 合并工作树分支

将指定分支合并到目标分支（默认为主分支），合并后可选择自动清理。

# 将 feature 分支合并到主分支
wt merge feature/done

# 合并到指定目标分支
wt merge feature/done --target develop

# 使用 --no-ff 强制创建合并提交
wt merge feature/done --no-ff

# 合并后自动删除分支和工作树
wt merge feature/done --delete

# 组合使用：合并 + 保留合并记录 + 自动清理
wt merge feature/done --delete --no-ff

参数说明：

参数 缩写 说明 默认值
source -- 源分支名称（必填） --
--target -t 目标分支 自动检测（main/master）
--delete -- 合并后删除源分支和工作树 false
--no-ff -- 禁止快进合并，强制创建合并提交 false

wt info -- 查看工作树详情

显示指定工作树的详细信息，包括分支、路径、提交、状态、未提交更改等。

# 按分支名查看
wt info feature/login

# 按路径查看
wt info /path/to/worktree

输出示例：

Worktree Information
==================================================
  Branch:    feature/login
  Path:      /project/.worktrees/feature-login
  Commit:    a1b2c3d
  Author:    zhangsan
  Date:      2025-01-15T10:30:00+08:00
  Status:    [>] AHEAD
  Ahead:     3 commit(s)
  Changes:   2 modified, 1 added

别名： show、details

wt clean -- 清理孤儿工作树

自动检测并清理那些分支已被删除但工作树目录仍然残留的孤儿工作树。

# 预览模式：查看哪些孤儿工作树会被清理（不实际执行）
wt clean --dry-run

# 交互式清理（需要确认）
wt clean

# 强制清理，跳过确认
wt clean --force

参数说明：

参数 缩写 说明 默认值
--dry-run -- 预览模式，不实际执行清理 false
--force -f 跳过确认 false

💡 建议： 首次使用时建议加上 --dry-run 参数，确认无误后再执行实际清理。

wt path -- 获取工作树路径

输出指定分支对应的工作树路径，适合在 shell 脚本中使用。

# 获取分支对应的工作树路径
wt path feature/login

# 在脚本中切换到工作树目录
cd $(wt path feature/login)

# 在 Makefile 中使用
WORKTREE_DIR = $(shell wt path feature/login)

全局选项

参数 说明
--no-color 禁用彩色输出（也可通过 NO_COLOR 环境变量控制）
--repo <path> 指定 Git 仓库路径（默认从当前目录自动检测）
--version 显示版本号

环境变量

变量名 说明 默认值
NO_COLOR 设置任意值即禁用彩色输出 未设置
GITWORKTREE_BASE_DIR 工作树基础目录 .worktrees
GITWORKTREE_TEMPLATE 默认路径命名模板 {branch}
GITWORKTREE_FORMAT 默认输出格式 table

💡 设计思路与迭代规划

为什么选择纯 Python 标准库？

  • 最大兼容性 -- 零外部依赖意味着在任何 Python 3.8+ 环境中都可以直接运行，不受网络环境限制
  • 安装即用 -- pip install 后立即可用，无需处理依赖冲突
  • 轻量可靠 -- 不依赖第三方库的版本更新和 API 变更，长期稳定
  • 适合中国大陆用户 -- 无需访问 PyPI 下载大量依赖包，安装速度更快

为什么 CLI 优先？

  • 终端是开发者的自然栖息地 -- CLI 工具可以无缝集成到各种工作流中
  • 脚本友好 -- 所有命令的输出都可以被其他程序解析和处理
  • AI Agent 友好 -- Claude Code、Codex 等 AI 编码助手可以直接调用 CLI 命令
  • 跨平台一致 -- 无论在哪个操作系统上，体验都保持一致

迭代规划

阶段 功能 状态
v1.0 核心 8 个命令、彩色 TUI、交互式选择器 ✅ 已完成
v1.1 Shell 自动补全（bash / zsh / fish） 📋 规划中
v1.2 Git hooks 集成（自动创建/清理工作树） 📋 规划中
v1.3 工作树模板（预配置开发环境） 📋 规划中
v2.0 TUI 仪表盘（实时状态面板） 💡 构想中
v2.1 插件系统（自定义命令扩展） 💡 构想中

📦 安装与部署

pip 安装（推荐）

pip install gitworktree

pipx 安装（隔离环境）

# 推荐使用 pipx 安装到独立虚拟环境中
pipx install gitworktree

# 升级
pipx upgrade gitworktree

直接运行

# 克隆仓库
git clone https://github.com/gitstq/gitworktree.git
cd gitworktree

# 无需安装，直接以模块方式运行
python -m gitworktree list
python -m gitworktree add feature/login

源码安装（开发模式）

git clone https://github.com/gitstq/gitworktree.git
cd gitworktree
pip install -e .

Docker 使用（可选）

# 构建镜像
docker build -t gitworktree .

# 在容器中使用
docker run --rm -v $(pwd):/repo gitworktree list

🤝 贡献指南

我们欢迎任何形式的贡献！无论是提交 Bug 报告、改进文档，还是提交代码 PR。

提交 Issue

在提交 Issue 之前，请先搜索是否已有相同的问题。提交 Issue 时请包含以下信息：

  • 问题描述 -- 清晰描述你遇到了什么问题
  • 复现步骤 -- 提供最小化的复现步骤
  • 环境信息 -- 操作系统、Python 版本、Git 版本
  • 期望行为 -- 你期望的正确行为是什么

提交 PR

  1. Fork 本仓库
  2. Clone 你的 Fork 到本地
  3. 创建分支 -- git checkout -b feature/your-feature
  4. 开发与测试 -- 编写代码并确保测试通过
  5. 提交代码 -- 使用 Conventional Commits 规范
feat: add shell completion for bash
fix: handle detached HEAD state in switch command
docs: update README with new examples
  1. 推送并创建 PR -- git push origin feature/your-feature

开发环境搭建

# 克隆仓库
git clone https://github.com/gitstq/gitworktree.git
cd gitworktree

# 以开发模式安装（修改代码后立即生效）
pip install -e .

# 运行测试
python -m pytest tests/

# 检查代码风格
python -m flake8 gitworktree/

代码风格要求

  • 遵循 PEP 8 编码规范
  • 使用 type hints 类型注解
  • 所有公开函数必须包含 docstring
  • 提交信息遵循 Conventional Commits 规范

📄 开源协议

本项目基于 MIT License 开源。

MIT License

Copyright (c) 2024 gitworktree contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

繁體中文

gitworktree -- 輕量級 Git Worktree 管理 CLI 工具

讓 git worktree 管理像切換分支一樣簡單

快速開始 · 詳細文件 · 安裝部署 · 貢獻指南

🎉 專案介紹

gitworktree 是一款輕量級的 Git Worktree 命令列管理工具，旨在讓開發者能夠以最簡潔、最直觀的方式管理多個工作樹（worktree）。

核心定位

一鍵管理，告別繁瑣的 git worktree 命令。

gitworktree 將 Git 原生的 worktree 子命令封裝為 8 個簡潔的子命令，提供彩色終端輸出、互動式選擇器、智慧命名模板等開箱即用的功能，讓你專注於編碼本身。

解決的痛點

痛點 gitworktree 的方案
原生 git worktree 命令參數繁多、記憶成本高 提供 8 個語義化子命令，wt list、wt add 一目了然
AI 編碼助手（Claude Code、Codex 等）需要平行工作樹 提供 一鍵建立/切換 工作樹的能力，完美適配 AI Agent 工作流
手動管理多個 worktree 容易遺漏、出錯 提供 孤兒工作樹自動偵測 與 批次清理 功能
無法直觀看到各 worktree 的分支狀態 提供 即時分支狀態追蹤（ahead/behind/dirty），彩色高亮一目了然
不同專案需要不同的 worktree 目錄結構 支援 自訂命名模板，靈活適配各種工作流

與同類工具的差異化

  • 零外部依賴 -- 僅使用 Python 標準函式庫，無需安裝任何第三方套件，最大相容性
  • 彩色 TUI 輸出 -- 自動偵測終端能力，支援 NO_COLOR 環境變數
  • 互動式選擇器 -- wt switch 提供數字編號的互動式工作樹切換
  • 智慧命名模板 -- 支援 {branch}、{short_hash}、{author}、{date} 佔位符
  • 分支狀態追蹤 -- 即時顯示 ahead/behind/dirty 狀態，無需手動 git fetch
  • 孤兒偵測 -- 自動識別分支已刪除但工作樹仍殘留的情況

靈感來源

隨著 AI 編碼助手（如 Claude Code、OpenAI Codex、Cursor 等）的興起，開發者越來越多地需要在同一個儲存庫中平行處理多個任務。每個 AI Agent 可能需要獨立的工作樹來避免衝突，而原生的 git worktree 命令列體驗遠不夠友善。gitworktree 正是在這一背景下誕生的 -- 讓平行工作樹管理變得像切換分支一樣自然。

✨ 核心特性

  • 🌳 互動式工作樹切換器 -- 帶彩色狀態標記的數字選擇器，告別手動 cd
  • 📊 即時分支狀態 -- 直觀顯示 ahead / behind / dirty / diverged 狀態
  • 🏷️ 智慧命名模板 -- 支援 {branch}、{short_hash}、{author}、{date} 自訂目錄命名
  • 🧹 孤兒工作樹偵測與清理 -- 自動發現分支已刪除的殘留工作樹，一鍵清理
  • 🔄 批次操作支援 -- 合併後自動刪除分支和工作樹，清理時批次處理
  • 📋 多格式輸出 -- 支援 table（表格）、json（結構化）、compact（緊湊）三種輸出格式
  • 🎨 精美的彩色 TUI -- 自動偵測終端能力，尊重 NO_COLOR 環境變數
  • 🚀 零依賴 -- 純 Python 標準函式庫實作，Python 3.8+ 即可執行
  • 💻 跨平台 -- 完美支援 Windows、macOS、Linux

🚀 快速開始

環境需求

依賴 最低版本
Python >= 3.8
Git >= 2.15

安裝

# 透過 pip 安裝（推薦）
pip install gitworktree

# 或者複製儲存庫後以開發模式安裝
git clone https://github.com/gitstq/gitworktree.git
cd gitworktree
pip install -e .

安裝完成後，你將獲得兩個可執行命令：wt 和 gitworktree，兩者功能完全一致，推薦使用更簡短的 wt。

快速上手

# 查看所有工作樹
wt list

# 為已有分支建立工作樹
wt add feature/login

# 建立新分支並同時建立工作樹
wt add -b feature/new

# 互動式切換工作樹
wt switch

# 移除指定工作樹
wt remove feature/old

# 將 feature 分支合併到主分支
wt merge feature/done

# 查看工作樹詳細資訊
wt info feature/login

# 清理孤兒工作樹
wt clean

# 取得工作樹路徑（適合腳本呼叫）
wt path feature/login

📖 詳細使用指南

wt list -- 列出所有工作樹

列出目前儲存庫中所有的工作樹，並顯示分支名稱、路徑、狀態和最後修改時間。

# 預設表格格式輸出
wt list

# 緊湊格式輸出
wt list --format compact

# JSON 格式輸出（適合腳本處理）
wt list --format json

# 按日期排序
wt list --sort date

# 按分支名排序
wt list --sort branch

# 只顯示有未提交變更的工作樹
wt list --filter dirty

# 只顯示乾淨的工作樹
wt list --filter clean

參數說明：

參數 縮寫 說明 預設值
--format -f 輸出格式：table / json / compact table
--sort -s 排序方式：name / date / branch name
--filter -- 過濾條件：clean / dirty 無

別名： ls

wt add -- 建立工作樹

為指定分支建立一個新的工作樹。支援為已有分支建立，也支援同時建立新分支。

# 為已有分支建立工作樹
wt add feature/login

# 建立新分支並同時建立工作樹
wt add -b feature/new

# 建立新分支並追蹤遠端分支
wt add -b feature/new --track origin/feature/new

# 使用自訂命名模板
wt add feature/auth --template "{branch}-{short_hash}"

# 指定工作樹基礎目錄
wt add feature/api --base-dir ".wt"

參數說明：

參數 縮寫 說明 預設值
branch -- 分支名稱（必填） --
--create-branch -b 建立新分支 false
--track -- 追蹤遠端分支 無
--template -- 路徑命名模板 {branch}
--base-dir -- 工作樹基礎目錄 .worktrees

可用模板佔位符：

佔位符 說明 範例
{branch} 分支名稱 feature/login
{short_hash} 短提交雜湊（7 位） a1b2c3d
{author} 提交作者 zhangsan
{date} 日期（YYYY-MM-DD） 2025-01-15

別名： create

wt switch -- 互動式切換工作樹

提供互動式數字選擇器，讓你快速切換到目標工作樹。

# 互動式選擇工作樹
wt switch

# 輸出 shell 可執行的 cd 命令（適合 shell 整合）
wt switch --shell

# 配合 eval 使用，直接切換目錄
eval "$(wt switch --shell)"

參數說明：

參數 說明 預設值
--shell 輸出 cd <path> 格式的 shell 命令 false

別名： sw、cd

wt remove -- 移除工作樹

移除指定分支或路徑對應的工作樹，支援強制移除和自動清理。

# 按分支名移除（會彈出確認提示）
wt remove feature/old

# 強制移除，跳過確認
wt remove feature/old --force

# 按路徑移除
wt remove /path/to/worktree

# 移除但不清理過期的 worktree 條目
wt remove feature/old --no-prune

參數說明：

參數 縮寫 說明 預設值
identifier -- 分支名或工作樹路徑（必填） --
--force -f 跳過確認，強制移除 false
--no-prune -- 不執行 prune 清理 false

⚠️ 注意： 不允許移除主工作樹（main worktree）。如果分支已合併，工具會提示你可以安全刪除該分支。

別名： rm、delete

wt merge -- 合併工作樹分支

將指定分支合併到目標分支（預設為主分支），合併後可選擇自動清理。

# 將 feature 分支合併到主分支
wt merge feature/done

# 合併到指定目標分支
wt merge feature/done --target develop

# 使用 --no-ff 強制建立合併提交
wt merge feature/done --no-ff

# 合併後自動刪除分支和工作樹
wt merge feature/done --delete

# 組合使用：合併 + 保留合併記錄 + 自動清理
wt merge feature/done --delete --no-ff

參數說明：

參數 縮寫 說明 預設值
source -- 來源分支名稱（必填） --
--target -t 目標分支 自動偵測（main/master）
--delete -- 合併後刪除來源分支和工作樹 false
--no-ff -- 禁止快轉合併，強制建立合併提交 false

wt info -- 查看工作樹詳情

顯示指定工作樹的詳細資訊，包括分支、路徑、提交、狀態、未提交變更等。

# 按分支名查看
wt info feature/login

# 按路徑查看
wt info /path/to/worktree

輸出範例：

Worktree Information
==================================================
  Branch:    feature/login
  Path:      /project/.worktrees/feature-login
  Commit:    a1b2c3d
  Author:    zhangsan
  Date:      2025-01-15T10:30:00+08:00
  Status:    [>] AHEAD
  Ahead:     3 commit(s)
  Changes:   2 modified, 1 added

別名： show、details

wt clean -- 清理孤兒工作樹

自動偵測並清理那些分支已被刪除但工作樹目錄仍然殘留的孤兒工作樹。

# 預覽模式：查看哪些孤兒工作樹會被清理（不實際執行）
wt clean --dry-run

# 互動式清理（需要確認）
wt clean

# 強制清理，跳過確認
wt clean --force

參數說明：

參數 縮寫 說明 預設值
--dry-run -- 預覽模式，不實際執行清理 false
--force -f 跳過確認 false

💡 建議： 首次使用時建議加上 --dry-run 參數，確認無誤後再執行實際清理。

wt path -- 取得工作樹路徑

輸出指定分支對應的工作樹路徑，適合在 shell 腳本中使用。

# 取得分支對應的工作樹路徑
wt path feature/login

# 在腳本中切換到工作樹目錄
cd $(wt path feature/login)

# 在 Makefile 中使用
WORKTREE_DIR = $(shell wt path feature/login)

全域選項

參數 說明
--no-color 停用彩色輸出（也可透過 NO_COLOR 環境變數控制）
--repo <path> 指定 Git 儲存庫路徑（預設從目前目錄自動偵測）
--version 顯示版本號

環境變數

變數名 說明 預設值
NO_COLOR 設定任意值即停用彩色輸出 未設定
GITWORKTREE_BASE_DIR 工作樹基礎目錄 .worktrees
GITWORKTREE_TEMPLATE 預設路徑命名模板 {branch}
GITWORKTREE_FORMAT 預設輸出格式 table

💡 設計思路與迭代規劃

為什麼選擇純 Python 標準函式庫？

  • 最大相容性 -- 零外部依賴意味著在任何 Python 3.8+ 環境中都可以直接執行，不受網路環境限制
  • 安裝即用 -- pip install 後即可使用，無需處理依賴衝突
  • 輕量可靠 -- 不依賴第三方函式庫的版本更新和 API 變更，長期穩定
  • 適合網路受限環境 -- 無需從 PyPI 下載大量依賴套件，安裝速度更快

為什麼 CLI 優先？

  • 終端是開發者的自然棲息地 -- CLI 工具可以無縫整合到各種工作流中
  • 腳本友善 -- 所有命令的輸出都可以被其他程式解析和處理
  • AI Agent 友善 -- Claude Code、Codex 等 AI 編碼助手可以直接呼叫 CLI 命令
  • 跨平台一致 -- 無論在哪個作業系統上，體驗都保持一致

迭代規劃

階段 功能 狀態
v1.0 核心 8 個命令、彩色 TUI、互動式選擇器 ✅ 已完成
v1.1 Shell 自動補全（bash / zsh / fish） 📋 規劃中
v1.2 Git hooks 整合（自動建立/清理工作樹） 📋 規劃中
v1.3 工作樹模板（預配置開發環境） 📋 規劃中
v2.0 TUI 儀表板（即時狀態面板） 💡 構想中
v2.1 外掛系統（自訂命令擴充） 💡 構想中

📦 安裝與部署

pip 安裝（推薦）

pip install gitworktree

pipx 安裝（隔離環境）

# 推薦使用 pipx 安裝到獨立虛擬環境中
pipx install gitworktree

# 升級
pipx upgrade gitworktree

直接執行

# 複製儲存庫
git clone https://github.com/gitstq/gitworktree.git
cd gitworktree

# 無需安裝，直接以模組方式執行
python -m gitworktree list
python -m gitworktree add feature/login

原始碼安裝（開發模式）

git clone https://github.com/gitstq/gitworktree.git
cd gitworktree
pip install -e .

Docker 使用（選用）

# 建置映像檔
docker build -t gitworktree .

# 在容器中使用
docker run --rm -v $(pwd):/repo gitworktree list

🤝 貢獻指南

我們歡迎任何形式的貢獻！無論是提交 Bug 回報、改進文件，還是提交程式碼 PR。

提交 Issue

在提交 Issue 之前，請先搜尋是否已有相同的問題。提交 Issue 時請包含以下資訊：

  • 問題描述 -- 清晰描述你遇到了什麼問題
  • 重現步驟 -- 提供最小化的重現步驟
  • 環境資訊 -- 作業系統、Python 版本、Git 版本
  • 期望行為 -- 你期望的正確行為是什麼

提交 PR

  1. Fork 本儲存庫
  2. Clone 你的 Fork 到本機
  3. 建立分支 -- git checkout -b feature/your-feature
  4. 開發與測試 -- 編寫程式碼並確保測試通過
  5. 提交程式碼 -- 使用 Conventional Commits 規範
feat: add shell completion for bash
fix: handle detached HEAD state in switch command
docs: update README with new examples
  1. 推送並建立 PR -- git push origin feature/your-feature

開發環境搭建

# 複製儲存庫
git clone https://github.com/gitstq/gitworktree.git
cd gitworktree

# 以開發模式安裝（修改程式碼後立即生效）
pip install -e .

# 執行測試
python -m pytest tests/

# 檢查程式碼風格
python -m flake8 gitworktree/

程式碼風格要求

  • 遵循 PEP 8 編碼規範
  • 使用 type hints 型別註解
  • 所有公開函式必須包含 docstring
  • 提交訊息遵循 Conventional Commits 規範

📄 開源協議

本專案基於 MIT License 開源。

MIT License

Copyright (c) 2024 gitworktree contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

English

gitworktree -- Lightweight Git Worktree Management CLI

Make git worktree management as easy as switching branches

Quick Start · Detailed Guide · Installation · Contributing

🎉 Project Introduction

gitworktree is a lightweight command-line tool for managing Git worktrees, designed to provide the simplest and most intuitive experience for developers working with multiple worktrees.

Core Positioning

One command to manage them all -- say goodbye to verbose git worktree commands.

gitworktree wraps Git's native worktree subcommands into 8 clean, semantic commands with colored terminal output, an interactive picker, smart naming templates, and more -- so you can focus on what matters: writing code.

Pain Points Solved

Pain Point gitworktree Solution
Native git worktree commands are verbose and hard to remember 8 semantic subcommands -- wt list, wt add are self-explanatory
AI coding agents (Claude Code, Codex, etc.) need parallel worktrees One-click create/switch worktrees, perfectly suited for AI Agent workflows
Manually managing multiple worktrees is error-prone Orphaned worktree auto-detection and batch cleanup
No way to see branch status across worktrees at a glance Real-time branch status tracking (ahead/behind/dirty) with color highlighting
Different projects need different worktree directory structures Customizable naming templates that adapt to any workflow

What Sets Us Apart

  • Zero external dependencies -- Built entirely on the Python standard library for maximum compatibility
  • Colored TUI output -- Auto-detects terminal capabilities and respects the NO_COLOR environment variable
  • Interactive picker -- wt switch provides a numbered interactive worktree selector
  • Smart naming templates -- Supports {branch}, {short_hash}, {author}, {date} placeholders
  • Branch status tracking -- Real-time ahead/behind/dirty status display without manual git fetch
  • Orphan detection -- Automatically identifies worktrees whose branches have been deleted

Inspiration

The rise of AI coding assistants (such as Claude Code, OpenAI Codex, Cursor, and others) has created a growing need for developers to work on multiple tasks in parallel within the same repository. Each AI Agent may need its own isolated worktree to avoid conflicts, yet the native git worktree command-line experience is far from user-friendly. gitworktree was born from this need -- making parallel worktree management feel as natural as switching branches.

✨ Core Features

  • 🌳 Interactive worktree switcher -- Numbered picker with colored status indicators, no more manual cd
  • 📊 Real-time branch status -- Visual display of ahead / behind / dirty / diverged states
  • 🏷️ Smart naming templates -- Custom directory naming with {branch}, {short_hash}, {author}, {date} placeholders
  • 🧹 Orphaned worktree detection & cleanup -- Auto-discover worktrees with deleted branches and clean them up in one command
  • 🔄 Batch operations -- Auto-delete branches and worktrees after merge, batch-process during cleanup
  • 📋 Multi-format output -- table (formatted), json (structured), compact (one-line) output modes
  • 🎨 Beautiful colored TUI -- Auto-detects terminal capabilities, respects NO_COLOR environment variable
  • 🚀 Zero dependencies -- Pure Python standard library, runs on Python 3.8+
  • 💻 Cross-platform -- Full support for Windows, macOS, and Linux

🚀 Quick Start

Requirements

Dependency Minimum Version
Python >= 3.8
Git >= 2.15

Installation

# Install via pip (recommended)
pip install gitworktree

# Or clone and install in development mode
git clone https://github.com/gitstq/gitworktree.git
cd gitworktree
pip install -e .

After installation, you get two executable commands: wt and gitworktree. Both are fully equivalent -- we recommend using the shorter wt.

Quick Examples

# List all worktrees
wt list

# Create a worktree for an existing branch
wt add feature/login

# Create a new branch and worktree at the same time
wt add -b feature/new

# Interactive worktree switcher
wt switch

# Remove a worktree
wt remove feature/old

# Merge a feature branch into main
wt merge feature/done

# Show worktree details
wt info feature/login

# Clean orphaned worktrees
wt clean

# Get worktree path (for scripting)
wt path feature/login

📖 Detailed Usage Guide

wt list -- List All Worktrees

Lists all worktrees in the current repository with branch name, path, status, and last modified time.

# Default table format
wt list

# Compact format
wt list --format compact

# JSON format (for scripting)
wt list --format json

# Sort by date
wt list --sort date

# Sort by branch name
wt list --sort branch

# Show only dirty worktrees
wt list --filter dirty

# Show only clean worktrees
wt list --filter clean

Parameter Reference:

Parameter Short Description Default
--format -f Output format: table / json / compact table
--sort -s Sort by: name / date / branch name
--filter -- Filter by status: clean / dirty None

Aliases: ls

wt add -- Create a Worktree

Creates a new worktree for a specified branch. Supports both existing branches and creating new ones simultaneously.

# Create worktree for an existing branch
wt add feature/login

# Create a new branch and worktree together
wt add -b feature/new

# Create new branch tracking a remote branch
wt add -b feature/new --track origin/feature/new

# Use a custom naming template
wt add feature/auth --template "{branch}-{short_hash}"

# Specify a custom base directory
wt add feature/api --base-dir ".wt"

Parameter Reference:

Parameter Short Description Default
branch -- Branch name (required) --
--create-branch -b Create a new branch false
--track -- Track a remote branch None
--template -- Path naming template {branch}
--base-dir -- Base directory for worktrees .worktrees

Available Template Placeholders:

Placeholder Description Example
{branch} Branch name feature/login
{short_hash} Short commit hash (7 chars) a1b2c3d
{author} Commit author johndoe
{date} Date (YYYY-MM-DD) 2025-01-15

Aliases: create

wt switch -- Interactive Worktree Switcher

Provides an interactive numbered picker for quickly switching between worktrees.

# Interactive worktree selection
wt switch

# Output a shell-evaluable cd command (for shell integration)
wt switch --shell

# Use with eval to change directory directly
eval "$(wt switch --shell)"

Parameter Reference:

Parameter Description Default
--shell Output cd <path> shell command false

Aliases: sw, cd

wt remove -- Remove a Worktree

Removes the worktree associated with a branch or path. Supports forced removal and automatic cleanup.

# Remove by branch name (prompts for confirmation)
wt remove feature/old

# Force remove without confirmation
wt remove feature/old --force

# Remove by path
wt remove /path/to/worktree

# Remove without pruning stale worktree entries
wt remove feature/old --no-prune

Parameter Reference:

Parameter Short Description Default
identifier -- Branch name or worktree path (required) --
--force -f Skip confirmation, force removal false
--no-prune -- Do not prune stale entries false

⚠️ Note: The main worktree cannot be removed. If the branch has already been merged, the tool will suggest that you can safely delete the branch.

Aliases: rm, delete

wt merge -- Merge a Worktree Branch

Merges a specified branch into a target branch (defaults to the main branch), with optional automatic cleanup.

# Merge feature branch into main
wt merge feature/done

# Merge into a specific target branch
wt merge feature/done --target develop

# Force a merge commit with --no-ff
wt merge feature/done --no-ff

# Auto-delete branch and worktree after merge
wt merge feature/done --delete

# Combine: merge + preserve merge history + auto-cleanup
wt merge feature/done --delete --no-ff

Parameter Reference:

Parameter Short Description Default
source -- Source branch name (required) --
--target -t Target branch Auto-detect (main/master)
--delete -- Delete source branch and worktree after merge false
--no-ff -- Create a merge commit (no fast-forward) false

wt info -- Show Worktree Details

Displays detailed information about a specified worktree, including branch, path, commit, status, and uncommitted changes.

# Look up by branch name
wt info feature/login

# Look up by path
wt info /path/to/worktree

Example Output:

Worktree Information
==================================================
  Branch:    feature/login
  Path:      /project/.worktrees/feature-login
  Commit:    a1b2c3d
  Author:    johndoe
  Date:      2025-01-15T10:30:00+08:00
  Status:    [>] AHEAD
  Ahead:     3 commit(s)
  Changes:   2 modified, 1 added

Aliases: show, details

wt clean -- Clean Orphaned Worktrees

Automatically detects and cleans up orphaned worktrees whose branches have been deleted but whose directories still remain.

# Preview mode: see what would be cleaned (no changes made)
wt clean --dry-run

# Interactive cleanup (requires confirmation)
wt clean

# Force cleanup without confirmation
wt clean --force

Parameter Reference:

Parameter Short Description Default
--dry-run -- Preview mode, no actual changes false
--force -f Skip confirmation false

💡 Tip: We recommend running with --dry-run first to verify what will be cleaned before performing the actual cleanup.

wt path -- Get Worktree Path

Outputs the worktree path for a given branch, ideal for use in shell scripts.

# Get the worktree path for a branch
wt path feature/login

# Change to the worktree directory in a script
cd $(wt path feature/login)

# Use in a Makefile
WORKTREE_DIR = $(shell wt path feature/login)

Global Options

Option Description
--no-color Disable colored output (also respects NO_COLOR env var)
--repo <path> Path to the git repository (default: auto-detect from cwd)
--version Show version number

Environment Variables

Variable Description Default
NO_COLOR Set to any value to disable colored output Unset
GITWORKTREE_BASE_DIR Base directory for worktrees .worktrees
GITWORKTREE_TEMPLATE Default path naming template {branch}
GITWORKTREE_FORMAT Default output format table

💡 Design Philosophy & Roadmap

Why Pure Python Standard Library Only?

  • Maximum compatibility -- Zero external dependencies means it runs in any Python 3.8+ environment without network access
  • Install and go -- Ready to use immediately after pip install, no dependency conflicts to resolve
  • Lightweight and reliable -- No reliance on third-party library version changes or API breakage, ensuring long-term stability
  • Works everywhere -- No need to download large dependency trees from PyPI, faster installation even in restricted networks

Why CLI-First?

  • The terminal is the developer's natural habitat -- CLI tools integrate seamlessly into any workflow
  • Script-friendly -- All command output can be parsed and processed by other programs
  • AI Agent-friendly -- Claude Code, Codex, and other AI coding assistants can invoke CLI commands directly
  • Cross-platform consistency -- The same experience across all operating systems

Roadmap

Phase Feature Status
v1.0 Core 8 commands, colored TUI, interactive picker ✅ Done
v1.1 Shell completion (bash / zsh / fish) 📋 Planned
v1.2 Git hooks integration (auto create/cleanup worktrees) 📋 Planned
v1.3 Worktree templates (pre-configured dev environments) 📋 Planned
v2.0 TUI dashboard (real-time status panel) 💡 Concept
v2.1 Plugin system (custom command extensions) 💡 Concept

📦 Installation & Deployment

pip Install (Recommended)

pip install gitworktree

pipx Install (Isolated Environment)

# Install into an isolated virtual environment
pipx install gitworktree

# Upgrade
pipx upgrade gitworktree

Direct Run

# Clone the repository
git clone https://github.com/gitstq/gitworktree.git
cd gitworktree

# Run without installation, using Python module syntax
python -m gitworktree list
python -m gitworktree add feature/login

Source Installation (Development Mode)

git clone https://github.com/gitstq/gitworktree.git
cd gitworktree
pip install -e .

Docker Usage (Optional)

# Build the image
docker build -t gitworktree .

# Use in a container
docker run --rm -v $(pwd):/repo gitworktree list

🤝 Contributing

We welcome contributions of all forms! Whether it's filing bug reports, improving documentation, or submitting code PRs.

Filing Issues

Before submitting an issue, please search for existing ones. When filing an issue, please include:

  • Problem description -- Clearly describe what you encountered
  • Steps to reproduce -- Provide minimal reproduction steps
  • Environment info -- Operating system, Python version, Git version
  • Expected behavior -- What you expected to happen

Submitting PRs

  1. Fork this repository
  2. Clone your fork locally
  3. Create a branch -- git checkout -b feature/your-feature
  4. Develop and test -- Write code and ensure tests pass
  5. Commit -- Follow the Conventional Commits specification
feat: add shell completion for bash
fix: handle detached HEAD state in switch command
docs: update README with new examples
  1. Push and create a PR -- git push origin feature/your-feature

Development Setup

# Clone the repository
git clone https://github.com/gitstq/gitworktree.git
cd gitworktree

# Install in development mode (changes take effect immediately)
pip install -e .

# Run tests
python -m pytest tests/

# Check code style
python -m flake8 gitworktree/

Code Style Requirements

  • Follow PEP 8 coding conventions
  • Use type hints for all function signatures
  • All public functions must include docstrings
  • Commit messages must follow the Conventional Commits specification

📄 License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2024 gitworktree contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

About

🌳 Lightweight Git Worktree Management CLI - Interactive switcher, smart naming, batch ops, branch status tracking. Zero dependencies, Python 3.8+

github.com/gitstq/gitworktree

Topics

python git cli productivity terminal cross-platform developer-tools git-management worktree zero-dependencies

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages