Git Worktree 使用详解——分支管理与并行开发最佳实践

# 查看当前仓库的所有工作树
git worktree list
# 示例输出：
# /path/to/repo                bb7c4a5 [main]
# /path/to/repo/feature-branch 1a2b3c4 [feature/new-feature]
# /path/to/repo/hotfix-branch  5d6e7f8 [hotfix/critical-bug]

# 查看详细信息
git worktree list --porcelain

# 传统分支方式 - 需要切换
git checkout main
git checkout feature/new-feature
git checkout hotfix/urgent-fix

# Worktree方式 - 同时工作
# 主工作树
cd /repo/main
git checkout main

# 功能分支工作树
cd /repo/feature
git checkout feature/new-feature

# 紧急修复工作树
cd /repo/hotfix
git checkout hotfix/urgent-fix

# 创建新的工作树
git worktree add ../feature-branch main
git worktree add ../hotfix-branch -b hotfix/new-fix origin/main

# 列出所有工作树
git worktree list

# 删除工作树
git worktree remove ../feature-branch

# 锁定工作树（防止意外删除）
git worktree lock ../important-branch

# 解锁工作树
git worktree unlock ../important-branch

# 场景：同时开发多个功能，互不干扰

# 1. 创建主工作树
git clone https://github.com/user/project.git main-work
cd main-work

# 2. 为功能1创建独立工作树
git worktree add ../feature-login main
cd ../feature-login
git checkout -b feature/login-page

# 3. 为功能2创建独立工作树
git worktree add ../feature-dashboard main
cd ../feature-dashboard
git checkout -b feature/dashboard-widgets

# 4. 同时在不同目录开发不同功能
# 可以同时运行不同的开发服务器
# cd ../feature-login && npm run dev
# cd ../feature-dashboard && npm run dev

# 5. 分别提交和推送
# 在feature-login目录
git add .
git commit -m "Add login page"
git push origin feature/login-page

# 在feature-dashboard目录
git add .
git commit -m "Add dashboard widgets"
git push origin feature/dashboard-widgets

# 场景：开发新功能的同时修复紧急Bug

# 主开发工作树
cd ~/project-main
git checkout develop
# 继续开发新功能...

# 创建紧急修复工作树
git worktree add ../bugfix/hotfix-urgent-issue main
cd ../bugfix/hotfix-urgent-issue

# 在独立环境中修复Bug
git checkout -b hotfix/urgent-issue
# 修复代码...

# 提交Bug修复
git add .
git commit -m "Fix urgent issue"
git push origin hotfix/urgent-issue

# 创建PR并合并到main
git checkout main
git merge hotfix/urgent-issue
git push origin main

# 将修复合并到开发分支
cd ~/project-main
git fetch origin
git merge main  # 将修复合并到当前开发分支

# 场景：维护主代码和文档站点

# 主代码工作树
cd ~/my-project
git checkout main

# 文档站点工作树
git worktree add ../my-project-docs gh-pages
cd ../my-project-docs

# 构建文档
npm run docs:build
cp -r dist/* ./
git add .
git commit -m "Update documentation"
git push origin gh-pages

# 或者维护文档的独立分支
git worktree add ../my-project-docs-dev gh-pages
cd ../my-project-docs-dev
# 在这里编辑文档，预览，然后构建到gh-pages分支

# 场景：维护多个软件版本

# 主开发分支
cd ~/project
git checkout main

# 维护v1.x版本
git worktree add ../project-v1.x release-v1.x
cd ../project-v1.x
# 在这里维护v1.x版本的bug修复

# 维护v2.x版本
git worktree add ../project-v2.x release-v2.x
cd ../project-v2.x
# 在这里维护v2.x版本的bug修复

# 查看所有版本的工作状态
git worktree list

# 创建基于远程分支的工作树
git worktree add ../team-feature origin/feature/team-work
cd ../team-feature
# 自动创建本地分支跟踪远程分支

# 或者创建并切换到远程分支
git worktree add ../review-pr --track origin/pr/123

# 快速创建实验环境
git worktree add ../experiment main
cd ../experiment
# 进行各种实验，不用担心破坏主分支

# 实验完成后删除
cd ..
rm -rf experiment
git worktree prune  # 清理失效的工作树引用

# 将构建输出放在独立的工作树中
git worktree add ../build-output gh-pages
cd ../build-output

# 构建项目
cd ../main-project
npm run build

# 将构建结果复制到输出工作树
cp -r dist/* ../build-output/
cd ../build-output

# 提交构建结果
git add .
git commit -m "Update build output"
git push origin gh-pages

# 在CI/CD中使用worktree进行多分支测试

# checkout代码
git clone https://github.com/user/repo.git .
git fetch --all

# 为不同的测试目标创建工作树
git worktree add ../test-node-14 main
git worktree add ../test-node-16 main
git worktree add ../test-node-18 main

# 在不同工作树中运行不同的测试
# Node 14测试
cd ../test-node-14 && nvm use 14 && npm test

# Node 16测试
cd ../test-node-16 && nvm use 16 && npm test

# Node 18测试
cd ../test-node-18 && nvm use 18 && npm test

#!/bin/bash
# git-worktree-manager.sh - Worktree管理脚本

case "$1" in
  "list")
    echo "=== Active Worktrees ==="
    git worktree list
    ;;

  "add-feature")
    if [ -z "$2" ]; then
      echo "Usage: $0 add-feature <feature-name>"
      exit 1
    fi

    feature_name="$2"
    worktree_dir="../feature-$feature_name"

    if [ -d "$worktree_dir" ]; then
      echo "Error: Directory $worktree_dir already exists"
      exit 1
    fi

    git worktree add "$worktree_dir" main
    cd "$worktree_dir"
    git checkout -b "feature/$feature_name"
    echo "Created feature worktree: $worktree_dir"
    ;;

  "add-hotfix")
    if [ -z "$2" ]; then
      echo "Usage: $0 add-hotfix <hotfix-name>"
      exit 1
    fi

    hotfix_name="$2"
    worktree_dir="../hotfix-$hotfix_name"

    git worktree add "$worktree_dir" main
    cd "$worktree_dir"
    git checkout -b "hotfix/$hotfix_name"
    echo "Created hotfix worktree: $worktree_dir"
    ;;

  "cleanup")
    echo "Cleaning up inactive worktrees..."
    git worktree prune
    echo "Done."
    ;;

  "status")
    echo "=== Worktree Status ==="
    for wt in $(git worktree list --porcelain | grep worktree | cut -d' ' -f2); do
      echo "Worktree: $wt"
      cd "$wt"
      branch=$(git branch --show-current)
      status=$(git status --porcelain)
      if [ -z "$status" ]; then
        echo "  Branch: $branch (clean)"
      else
        echo "  Branch: $branch (modified)"
        echo "  Files:"
        git status --short | sed 's/^/    /'
      fi
      cd - > /dev/null
      echo
    done
    ;;

  *)
    echo "Usage: $0 {list|add-feature|add-hotfix|cleanup|status}"
    exit 1
    ;;
esac

# 添加Git别名来简化worktree操作
git config alias.wt 'worktree'
git config alias.wta 'worktree add'
git config alias.wtl 'worktree list'
git config alias.wtr 'worktree remove'
git config alias.wtp 'worktree prune'

# 自定义别名
git config alias.wtf '!f() { git worktree add "../$1" main && cd "../$1" && git checkout -b "feature/$1"; }; f'
git config alias.wth '!f() { git worktree add "../hotfix-$1" main && cd "../hotfix-$1" && git checkout -b "hotfix/$1"; }; f'

git wtf user-authentication    # 创建用户认证功能工作树
git wth critical-bug          # 创建紧急修复工作树

// VS Code 工作区配置示例
{
  "folders": [
    {
      "name": "Main Project",
      "path": "."
    },
    {
      "name": "Feature Branch",
      "path": "../feature-user-management"
    },
    {
      "name": "Documentation",
      "path": "../docs-site"
    }
  ],
  "settings": {
    "git.repository": ".",
    "files.exclude": {
      "../feature-*": true,
      "../hotfix-*": true
    }
  }
}

# 推荐的命名约定
git worktree add ../feature-user-login main           # 功能开发
git worktree add ../hotfix-payment-bug main          # 紧急修复
git worktree add ../experiment-performance main      # 性能实验
git worktree add ../docs-update gh-pages             # 文档更新
git worktree add ../release-candidate main           # 发布候选

#!/bin/bash
# clean-old-worktrees.sh - 清理不活动的工作树

DAYS_OLD=30
CURRENT_DIR=$(pwd)

# 获取30天前的日期戳
CUTOFF_DATE=$(date -d "$DAYS_OLD days ago" +%s)

for worktree_path in $(git worktree list --porcelain | grep worktree | cut -d' ' -f2); do
  # 跳过当前目录
  if [ "$worktree_path" = "$CURRENT_DIR" ]; then
    continue
  fi

  # 检查最后一次修改时间
  if [ -d "$worktree_path" ]; then
    LAST_MODIFIED=$(stat -c %Y "$worktree_path")
    if [ $LAST_MODIFIED -lt $CUTOFF_DATE ]; then
      echo "Removing inactive worktree: $worktree_path"

      # 检查是否有未提交的更改
      cd "$worktree_path" 2>/dev/null
      if ! git diff-index --quiet HEAD --; then
        echo "Warning: $worktree_path has uncommitted changes!"
        read -p "Do you want to proceed? (y/N): " -n 1 -r
        echo
        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
          continue
        fi
      fi

      cd - > /dev/null
      rm -rf "$worktree_path"
    fi
  fi
done

# 清理git引用
git worktree prune

# 为不同的工作树设置不同的配置
cd ../feature-new-ui
git config user.name "John Developer"
git config user.email "john.feature@example.com"
git config core.fileMode false  # 遾Linux/Mac混合环境中避免文件权限问题

cd ../hotfix-security
git config user.name "Jane Security"
git config user.email "jane.security@example.com"
git config core.hooksPath .githooks/security  # 使用特定的hooks

# 1. 工作树消失但仍被引用
git worktree prune  # 清理失效的引用

# 2. 无法删除工作树（有未提交更改）
cd /path/to/worktree
git status
git add . && git commit -m "WIP"  # 提交临时更改
# 或者
git reset --hard HEAD  # 丢弃更改（谨慎使用）

# 3. 磁盘空间不足
git worktree list
du -sh ../worktree-*  # 检查各工作树大小
# 删除不需要的工作树

# 4. 权限问题
chmod 755 ../worktree-directory
git worktree remove ../worktree-directory

# 对于大型仓库的优化配置
git config core.preloadindex true
git config core.fscache true
git config gc.auto 256

# 减少git操作对系统的影响
git config core.precomposeunicode true  # 在Mac上

# 在主仓库设置通用hooks
mkdir -p .githooks/{pre-commit,commit-msg,pre-push}
ln -sf ../../.githooks/pre-commit/* .git/hooks/

# 不同工作树可以有不同的hooks
../feature-security/.githooks/security-checks
../docs/.githooks/spell-check

# 实用的worktree相关别名
git config alias.wtf '!f() { git worktree add "../feature-$1" main && cd "../feature-$1" && git checkout -b "feature/$1"; }; f'
git config alias.wtc '!f() { git worktree add "../chore-$1" main && cd "../chore-$1" && git checkout -b "chore/$1"; }; f'
git config alias.wtlv 'worktree list --porcelain'
git config alias.wtd 'worktree remove'

# GitHub Actions - 使用worktree进行多环境测试
name: Multi-Environment Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [14, 16, 18]
        worktree: [main, feature, experimental]

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: Create worktree for environment
        run: |
          git worktree add ../${{ matrix.worktree }} main
          cd ../${{ matrix.worktree }}
          git checkout ${{ matrix.worktree }} || git checkout -b ${{ matrix.worktree }} origin/main

      - name: Install dependencies
        run: cd ../${{ matrix.worktree }} && npm ci

      - name: Run tests
        run: cd ../${{ matrix.worktree }} && npm test