這篇教學的每一條指令都來自本站在 RTX A6000 48 GB 工作站 上實際錄下的終端機過程（2026-11-04 的版本，commit bac7f7e137cf），照順序做即可。
開始前
本教學基於 Ubuntu 24.04 LTS (Linux 7.0.0-38-generic) 環境，硬體為 Intel Core i7-9700 搭配 62 GB RAM 及 NVIDIA RTX A6000。軟體方面需預先安裝 Python 3.12.3、uv 0.11.2 以及 Node.js v18.19.1。由於 Worktrunk 是 Rust 編譯的 CLI 工具，建議確保系統有基本的 curl 與 tar 指令可用，並預留約 26 MB 的磁碟空間存放原始碼與執行檔。
安裝與執行
步驟 1：取得專案原始碼
從 GitHub 複製 max-sixty/worktrunk 專案並切換至指定 commit，以便後續參考或建置。
git clone https://github.com/max-sixty/worktrunk worktrunk cd worktrunk
成功時會看到：git log 顯示 commit bac7f7e 與日期 2026-11-04，目錄大小約 26M，並列出 Cargo.toml 等檔案。（這一步我們花了 1.3 秒，結束碼 0）
benches dev LICENSE Taskfile.yaml build.rs dist-workspace.toml nix templates Cargo.lock docs plugins tests Cargo.toml flake.lock README.md CHANGELOG.md flake.nix rust-toolchain.toml clippy.toml gemini-extension.json skills
步驟 2：下載並安裝執行檔
直接下載官方釋出的 Linux 靜態連結執行檔，驗證 SHA256 雜湊值後安裝至 ~/.local/bin，避免編譯耗時。
mkdir -p "~/lab/wtbin" "$HOME/.local/bin" && curl -LsS -o "~/lab/wt.tar.xz" https://github.com/max-sixty/worktrunk/releases/download/v0.81.0/worktrunk-x86_64-unknown-linux-musl.tar.xz && echo "$(curl -LsS https://github.com/max-sixty/worktrunk/releases/download/v0.81.0/worktrunk-x86_64-unknown-linux-musl.tar.xz.sha256 | cut -d" " -f1) ~/lab/wt.tar.xz" | sha256sum -c - && tar -xJf "~/lab/wt.tar.xz" -C "~/lab/wtbin" && B=$(find "~/lab/wtbin" -type f -name wt | head -1) && install -m755 "$B" "$HOME/.local/bin/wt" && wt --version
成功時會看到：sha256sum 驗證顯示「成功」，最後執行 wt --version 顯示「wt v0.81.0」。（這一步我們花了 43.4 秒，結束碼 0）
/home/user/lab/notes/max-sixty-worktrunk/wt.tar.xz: 成功 wt v0.81.0
步驟 3：初始化測試 Git 倉庫
建立一個乾淨的本地 Git 倉庫並提交初始檔案，作為後續測試 worktree 功能的基礎。
rm -rf demo-repo demo-repo.* && git init -q -b main demo-repo && cd demo-repo && git config user.email "test@example.com" && git config user.name "Test" && echo "# Demo" > README.md && git add . && git commit -qm init && git log --oneline
成功時會看到：git log --oneline 顯示一筆 commit 訊息為「init」，分支為 main。（這一步我們花了 0.0 秒，結束碼 0）
WARNING: terminal is not fully functional Press RETURN to continue 3ab6fa9 (HEAD -> main) init
步驟 4：建立新分支工作樹
使用 wt switch --create 指令同時建立新分支與對應的 worktree 目錄，模擬並行開發場景。
cd "~/lab/demo-repo" && wt switch --create feature-auth && git worktree list
成功時會看到：畫面顯示「✓ Created branch feature-auth...」，且 git worktree list 列出兩個目錄分別對應 main 與 feature-auth 分支。（這一步我們花了 0.0 秒，結束碼 0）
✓ Created branch feature-auth from main and worktree @ ~/lab/notes/max-sixty-worktrunk/demo-repo.feature-auth ↳ To customize worktree locations, run wt config create ▲ Cannot change directory — shell integration not installed ❯ Install shell integration? [y/N/?] ↳ To enable automatic cd, run wt config shell install /home/user/lab/notes/max-sixty-worktrunk/demo-repo 3ab6fa9 [main] /home/user/lab/notes/max-sixty-worktrunk/demo-repo.feature-auth 3ab6fa9 [feature-auth]
步驟 5：在工作樹中提交變更
進入新建立的 feature-auth worktree 目錄，修改檔案並提交，驗證 worktree 的獨立性。
D=$(git -C "~/lab/demo-repo" worktree list --porcelain | awk '/^worktree /{p=$2} /^branch refs\/heads\/feature-auth$/{print p}') && cd "$D" && pwd && echo "# Auth" >> README.md && git add . && git commit -qm "add auth" && git log --oneline成功時會看到：pwd 顯示路徑包含 .feature-auth，git log 顯示新增了一筆「add auth」的 commit。（這一步我們花了 0.0 秒，結束碼 0）
/home/user/lab/notes/max-sixty-worktrunk/demo-repo.feature-auth WARNING: terminal is not fully functional Press RETURN to continue 1354f54 (HEAD -> feature-auth) add auth 3ab6fa9 (main) init
步驟 6：列出所有工作樹狀態
使用 wt list 檢視目前所有 worktree 的狀態、分支關係與差異，確認管理工具運作正常。
cd "~/lab/demo-repo" && wt list
成功時會看到：表格顯示 main 與 feature-auth 兩個分支，並標示 feature-auth 比 main 多一個 commit (↑1)。（這一步我們花了 0.1 秒，結束碼 0）
@ main ^ . 3ab6fa9 now init + feature-auth ../demo-repo.feature-auth 1354f54 now add auth + feature-auth ↑1 ../demo-repo.feature-auth 1354f54 now add auth + feature-auth ↑ ↑1 ../demo-repo.feature-auth 1354f54 now add auth + feature-auth ↑ ↑1 +1 ../demo-repo.feature-auth 1354f54 now add auth ○ Showing 2 worktrees, 1 ahead
步驟 7：合併分支並清理
執行 wt merge main 將 feature-auth 合併回主分支，並自動清理已合併的 worktree 與分支。
D=$(git -C "~/lab/demo-repo" worktree list --porcelain | awk '/^worktree /{p=$2} /^branch refs\/heads\/feature-auth$/{print p}') && cd "$D" && wt merge main成功時會看到：畫面顯示「✓ Merged to main」以及「Removing feature-auth worktree & branch in background」。（這一步我們花了 0.3 秒，結束碼 0）
README.md | 1 + 1 file changed, 1 insertion(+) ✓ Merged to main (1 commit, 1 file, +1) ◎ Removing feature-auth worktree & branch in background (same commit as main, _) ▲ Worktree for main @ ~/lab/notes/max-sixty-worktrunk/demo-repo, but cannot change directory — shell integration not installed ↳ To enable automatic cd, run wt config shell install
步驟 8：確認合併結果
檢查主分支的歷史記錄與剩餘 worktree 數量，確保合併成功且環境已恢復乾淨。
cd "~/lab/demo-repo" && git log --oneline && git worktree list && wt list
成功時會看到：git log 顯示 main 分支包含「add auth」commit，wt list 僅顯示 1 個 worktree (main)。（這一步我們花了 0.1 秒，結束碼 0）
Branch Status HEAD± main↕ main…± Remote⇅ Path Commit Age Message main . 1354f54 ○ 1 worktree — loading details… main . 1354f54 now add auth @ main ^ . 1354f54 now add auth ○ Showing 1 worktree
確認裝好了
執行 wt list 後，畫面僅顯示一個位於當前目錄的 main 分支 worktree，且 git log 確認合併後的 commit 已存在於 main 分支，代表 Worktrunk 成功管理了從建立、開發到合併清理的完整流程。
可能遇到的問題
1. 若終端機顯示 'WARNING: terminal is not fully functional'，請手動按下 Enter 鍵繼續執行。
2. 若執行 wt switch 後提示 'Cannot change directory — shell integration not installed'，這是因為未安裝 shell 整合，可手動 cd 進入目錄或執行 wt config shell install 解決。
接下來
安裝完成後，您可以嘗試安裝 shell 整合以啟用自動切換目錄功能，或參考 README 設定 hooks 與 plugins 來自動化 AI Agent 的開發工作流。
