nop-git-worktree

name	nop-git-worktree
description	涉及git worktree的操作优先使用这个skill。管理 Git bare 仓库和多个并行 worktree 的开发环境。支持初始化 bare 仓库结构、自动生成分支名并创建 feature worktree。

重要提示

⚠️ 必须遵守的操作规则

1. 所有 git worktree 相关命令必须在 .bare 目录中执行

   • ✅ 正确：git -C .bare worktree add ../feature-xxx -b feature-xxx
   • ❌ 错误：git -C .bare worktree add feature-xxx -b feature-xxx

2. 创建 worktree 时使用相对路径

   • ✅ 正确：使用相对路径 ../
   • ❌ 错误：使用绝对路径

3. 遇到错误时，按顺序清理

   cd ~/app/nop-entropy-wt
   git -C .bare worktree remove ../nop-entropy-feature-xxx 2>/dev/null || true
   rm -rf nop-entropy-feature-xxx 2>/dev/null || true
   git -C .bare worktree prune
   git -C .bare branch -D feature-xxx
   

4. 操作目录

   操作类型	执行目录
   创建/删除 worktree	cd ~/app/nop-entropy-wt && git -C .bare worktree ...
   查看 worktree 列表	cd ~/app/nop-entropy-wt && git -C .bare worktree list
   查看/操作分支	cd ~/app/nop-entropy-wt && git -C .bare branch ...
   在 worktree 中开发	cd ~/app/nop-entropy-wt/nop-entropy-feature-xxx

功能

操作类型 1: 初始化 bare + worktree 项目结构

创建适合 worktree 开发的项目结构：

• 创建 .bare 目录作为 Git bare 仓库（中心）
• 支持从远程仓库 clone 或从本地现有仓库迁移
• 自动创建 main/master 分支的 worktree 目录

操作类型 2: 创建新的 feature worktree

在已初始化的项目下创建新 worktree：

• 根据需求描述智能生成分支名
• 自动创建对应的 worktree 目录
• 确保分支名唯一且符合 Git 命名规范

使用时机

初始化项目结构：

• "初始化 bare + worktree 开发环境"
• "从远程仓库创建 bare 仓库和多个 worktree"
• "把现有 git 仓库转换成 bare + worktree 结构"

创建新 worktree：

• "创建一个新分支用于 [需求描述]"
• "添加一个新的 worktree 来开发 [功能]"

目录结构

project-root/                          # 项目根目录（如 ~/app/nop-entropy-wt）
├── .bare/                            # Git bare 仓库（中心），所有 git worktree 操作在此执行
│   ├── HEAD                          # 当前默认分支
│   ├── config                        # Git 配置
│   ├── objects/                      # Git 对象存储
│   ├── refs/                         # Git 引用
│   └── ...
├── nop-entropy-master/               # 主分支 worktree（开发时在此目录），目录名=项目名-分支名
│   └── ...                          # 项目文件
├── nop-entropy-feat-auth/            # 特性分支 worktree，目录名=项目名-分支名
│   ├── .mvn/
│   │   └── maven.config
│   └── ...
└── nop-entropy-fix-login/            # 修复分支 worktree，目录名=项目名-分支名
    ├── .mvn/
    │   └── maven.config
    └── ...

关键说明：

• .bare/ 目录：这是 Git bare 仓库，所有 git worktree 命令必须在此目录或通过 git -C .bare 执行
• worktree 目录命名：<PROJECT_NAME>-<BRANCH_NAME> 格式，便于在 IDE 中区分不同项目的 worktree
• nop-entropy-master/, nop-entropy-feat-auth/ 等目录：这些是实际的工作目录，开发时在这些目录中进行 git 操作（如 git commit, git status）

操作说明

初始化 bare + worktree 项目结构

参数：

• 项目根目录 (必填): 如 ~/app/nop-entropy-wt
• 远程仓库 URL (可选): 如 https://gitee.com/user/repo.git
• 本地仓库路径 (可选): 现有 git 仓库的路径

步骤：

cd ~/app/nop-entropy-wt

# 1. 创建 bare 仓库
git clone --bare https://gitee.com/canonical-entropy/nop-entropy.git .bare
# 或从本地克隆: git clone --bare ~/app/nop-entropy .bare

# 2. 启用长路径支持（Windows 平台重要配置）
# Windows 默认路径限制 260 字符，某些项目文件路径可能超限
git -C .bare config core.longpaths true
echo "Long paths enabled"

# 3. 识别项目名称（从 remote URL 提取）
PROJECT_NAME=$(git -C .bare config --get remote.origin.url | sed -E 's|.*/([^/]+?)(\.git)?$|\1|')
echo "Project name: $PROJECT_NAME"

# 4. 识别默认分支（优先从 .bare/HEAD 读取，兼容 bare 仓库）
DEFAULT_BRANCH=$(cat .bare/HEAD 2>/dev/null | sed 's@^refs/heads/@@')
# 如果 .bare/HEAD 读取失败，尝试从 remote 读取
if [ -z "$DEFAULT_BRANCH" ]; then
    DEFAULT_BRANCH=$(git -C .bare symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
fi
echo "Default branch: $DEFAULT_BRANCH"

# 5. 创建主分支 worktree（目录名: PROJECT_NAME-BRANCH_NAME）
git -C .bare worktree add "../${PROJECT_NAME}-${DEFAULT_BRANCH}" "$DEFAULT_BRANCH"

# 6. 验证
git -C .bare worktree list

创建新的 feature worktree

参数：

• 需求描述 (必填): 自然语言描述的功能需求
• 项目根目录 (必填): 如 ~/app/nop-entropy-wt

分支名生成规则：

需求类型	前缀	示例
新功能	add-, feat-	add-user-auth, feat-payment
修复	fix-	fix-login-error, fix-crash
重构	refactor-	refactor-db, refactor-job-scheduling
性能优化	perf-, optimize-	perf-query, optimize-cache
紧急修复	hotfix-	hotfix-security
文档	docs-	docs-api
测试/杂项	test-, chore-	test-auth, chore-deps

步骤：

cd ~/app/nop-entropy-wt

# 获取项目名称（从 remote URL 提取）
PROJECT_NAME=$(git -C .bare config --get remote.origin.url | sed -E 's|.*/([^/]+?)(\.git)?$|\1|')

BRANCH_NAME="refactor-job-scheduling"
WORKTREE_NAME="${PROJECT_NAME}-${BRANCH_NAME}"  # worktree 目录名: PROJECT_NAME-BRANCH_NAME

# 1. 如果分支已存在，先清理
if git -C .bare branch --list "$BRANCH_NAME" > /dev/null; then
    git -C .bare worktree remove "../$WORKTREE_NAME" 2>/dev/null || true
    rm -rf "$WORKTREE_NAME" 2>/dev/null || true
    git -C .bare worktree prune
    git -C .bare branch -D "$BRANCH_NAME"
fi

# 2. 创建 worktree（目录名: PROJECT_NAME-BRANCH_NAME）
git -C .bare worktree add "../$WORKTREE_NAME" -b "$BRANCH_NAME"

# 3. 创建 Maven 配置（Feature 分支专用）
mkdir -p "$WORKTREE_NAME/.mvn"

# 获取 worktree 的绝对路径并替换变量为实际路径
WORKTREE_ABS_PATH="$(cd "$WORKTREE_NAME" && pwd)"
cat > "$WORKTREE_NAME/.mvn/maven.config" <<EOF
-Dmaven.repo.local.head=$WORKTREE_ABS_PATH/.nop/repository
-Dmaven.repo.local.tail.ignoreAvailability=true
EOF

# 4. 验证
git -C .bare worktree list

常用命令

注意：所有 git worktree 相关命令必须在 .bare 目录中执行，或使用 git -C .bare 参数。

# 查看 worktree 列表
git -C .bare worktree list

# 删除 worktree（指定 worktree 目录名）
git -C .bare worktree remove nop-entropy-feature-auth

# 清理无效引用
git -C .bare worktree prune

# 移动 worktree
git -C .bare worktree move nop-entropy-old-name nop-entropy-new-name

# 切换 worktree 目录（目录名 = PROJECT_NAME-BRANCH_NAME）
cd ~/app/nop-entropy-wt/nop-entropy-master           # 主分支
cd ~/app/nop-entropy-wt/nop-entropy-feature-auth      # 功能分支

# 在 worktree 中查看状态
cd ~/app/nop-entropy-wt/nop-entropy-feature-auth
git status
git branch

分支更新模式

⚠️ 重要：区分两种更新模式

在更新分支时，必须明确区分以下两种情况：

模式	场景	操作	是否需要确认
普通更新	特性分支同步主分支最新内容，保留自己的修改	git rebase origin/master	否（默认行为）
强制重置	丢弃本地所有修改，完全同步主分支	git reset --hard origin/master	是（必须确认）

⚠️ 关键：正确更新远程跟踪分支

问题：git fetch origin 可能只更新 FETCH_HEAD，而不更新 refs/remotes/origin/master，导致 origin/master 指向旧版本。

解决方案：必须使用强制更新语法：

# ❌ 错误：可能不会更新 refs/remotes/origin/master
git fetch origin

# ✅ 正确：强制更新远程跟踪分支
git fetch origin +refs/heads/master:refs/remotes/origin/master

验证远程同步状态：在执行任何分支更新前，必须验证本地 origin/master 是否真正同步：

# 1. 检查远程实际最新提交
git ls-remote origin refs/heads/master

# 2. 检查本地 origin/master 指向的提交
git rev-parse origin/master

# 3. 两者应该相同，如果不同说明需要强制 fetch

普通更新（保留本地修改）

特性分支的默认行为：拉取主分支最新内容，然后将自己的提交叠加在上面。

cd ~/app/nop-entropy-wt

# 1. 【关键】强制更新远程跟踪分支（不是简单的 git fetch origin）
git fetch origin +refs/heads/master:refs/remotes/origin/master

# 2. 验证同步状态（可选但推荐）
git ls-remote origin refs/heads/master  # 远程实际
git rev-parse origin/master              # 本地跟踪

# 3. 在特性分支中 rebase（保留本地修改）
cd nop-entropy-feat-xxx
git rebase origin/master

# 4. 如果有冲突，智能解决后继续
git add .
git rebase --continue

强制重置（丢弃本地修改）

⚠️ 必须先向用户确认：此操作会丢失所有本地修改！

cd ~/app/nop-entropy-wt

# 1. 【关键】强制更新远程跟踪分支
git fetch origin +refs/heads/master:refs/remotes/origin/master

# 2. 确认后强制重置
cd nop-entropy-feat-xxx
git reset --hard origin/master

主分支更新

主分支（master）始终与远程同步：

cd ~/app/nop-entropy-wt

# 1. 【关键】强制更新远程跟踪分支
git fetch origin +refs/heads/master:refs/remotes/origin/master

# 2. 验证同步
git log --oneline HEAD..origin/master  # 应该为空

# 3. 更新主分支
cd nop-entropy-master
git pull --ff-only origin master
# 或者：git reset --hard origin/master

批量更新所有分支

当需要更新所有 worktree 分支时：

cd ~/app/nop-entropy-wt

# 1. 【关键】强制更新远程跟踪分支
git fetch origin +refs/heads/master:refs/remotes/origin/master

# 2. 遍历所有 worktree 并更新
for wt in nop-entropy-*; do
  if [ -d "$wt" ]; then
    echo "=== Updating $wt ==="
    cd "$wt"
    behind=$(git rev-list --count HEAD..origin/master 2>/dev/null || echo "N/A")
    if [ "$behind" != "0" ] && [ "$behind" != "N/A" ]; then
      git stash -u -m "pre-rebase stash" 2>/dev/null
      git rebase origin/master 2>&1 | head -5
      git stash pop 2>/dev/null || true
    fi
    cd ..
  fi
done

最佳实践

1. worktree 目录命名：使用 <PROJECT_NAME>-<BRANCH_NAME> 格式（如 nop-entropy-master, nop-entropy-feat-auth），便于在 IDE 中区分不同项目的 worktree
2. 分支命名：使用清晰的语义化分支名（小写字母、数字、连字符，20-30 字符）
3. 命令执行位置：
   • git worktree 相关命令：在 .bare 目录中执行，或使用 git -C .bare
   • git 提交、状态查看等：在对应的 worktree 目录中执行
4. 及时清理：完成功能后及时删除 worktree
5. 独立环境：每个 worktree 独立安装依赖
6. 路径使用：始终使用相对路径（如 ../nop-entropy-feature-xxx）
7. 特性分支更新：默认使用 rebase 保留本地修改，只有明确要求时才 reset --hard
8. ⚠️ 远程同步检查：
   • 永远不要假设 git fetch origin 已同步远程
   • 更新前必须用 git ls-remote origin refs/heads/master 验证远程实际状态
   • 使用 git fetch origin +refs/heads/master:refs/remotes/origin/master 强制更新
   • 用 git log --oneline HEAD..origin/master 确认是否有新提交

Maven 配置说明

主分支 vs Feature 分支的 Maven 配置：

分支类型	Maven 配置	说明
主分支 (main/master)	不配置	使用系统默认仓库（~/.m2/repository）
Feature 分支	配置 .mvn/maven.config	使用独立局部仓库（.nop/repository），避免依赖冲突

Feature 分支 Maven 配置文件格式：

# 示例：创建时自动计算绝对路径
WORKTREE_ABS_PATH="$(cd "nop-entropy-feat-auth" && pwd)"
cat > "nop-entropy-feat-auth/.mvn/maven.config" <<EOF
-Dmaven.repo.local.head=$WORKTREE_ABS_PATH/.nop/repository
-Dmaven.repo.local.tail.ignoreAvailability=true
EOF

实际生成的配置文件内容示例：

-Dmaven.repo.local.head=/Users/abc/app/nop-entropy-wt/nop-entropy-feat-auth/.nop/repository
-Dmaven.repo.local.tail.ignoreAvailability=true

参数说明：

• maven.repo.local.head: 优先使用当前 worktree 的 .nop/repository 目录
• maven.repo.local.tail.ignoreAvailability=true: 忽略尾部仓库可用性检查，提高启动速度

Worktree 提交流程

流程假设：

• 项目根目录：~/app/nop-entropy-wt
• 项目名称：nop-entropy
• feature worktree：~/app/nop-entropy-wt/nop-entropy-feat-stream-processing
• 主分支 worktree：~/app/nop-entropy-wt/nop-entropy-master

步骤：

# 获取项目名称
PROJECT_NAME="nop-entropy"

# 1. 更新主分支到最新
cd ~/app/nop-entropy-wt/${PROJECT_NAME}-master
git pull origin master

# 2. 软重置 feature 分支到基础分支（保留所有修改，但撤销提交历史）
cd ../${PROJECT_NAME}-feat-stream-processing
git reset --soft master

# 3. 查看修改内容
git diff --cached --stat

# 4. 生成提交信息并提交（遵循约定式提交格式）
git commit -m "feat: 实现流处理数据源接入

支持多种数据源接入：
- Kafka 数据源
- 文件数据源
- HTTP 数据源
- 数据库数据源"

# 5. 生成差异文件（可选）
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
git diff master > "${PROJECT_NAME}-feat-stream-processing-${TIMESTAMP}.diff"

# 6. 合并到主分支
cd ../${PROJECT_NAME}-master
git merge feat-stream-processing --ff-only

# 7. 同步主分支最新内容回 feature 分支
cd ../${PROJECT_NAME}-feat-stream-processing
git rebase master

约定式提交格式：

类型	含义	示例
feat	新功能	feat: 添加用户登录功能
fix	修复 bug	fix: 修复登录时的空指针异常
refactor	重构	refactor: 优化数据库查询逻辑
perf	性能优化	perf: 减少重复的网络请求
docs	文档	docs: 更新 API 文档
test	测试	test: 添加单元测试覆盖
chore	构建/工具	chore: 升级依赖版本

故障排查

常见错误

错误信息	原因	解决方案
fatal: a branch named 'xxx' already exists	分支已存在	git -C .bare branch -D xxx
fatal: '../xxx' already exists	worktree 目录已存在	rm -rf xxx
Preparing worktree (new branch 'xxx') failed	路径格式错误或无效引用	参考清理步骤
worktree list 显示奇怪路径	在错误目录执行命令	参考清理步骤
Filename too long	Windows 路径超过 260 字符限制	启用长路径支持：git -C .bare config core.longpaths true
error: unable to create file: Filename too long	Windows 路径超过 260 字符限制	启用长路径支持：git -C .bare config core.longpaths true
分支显示已同步但实际落后远程	git fetch 未更新远程跟踪分支	使用强制 fetch：git fetch origin +refs/heads/master:refs/remotes/origin/master

远程同步问题诊断

症状：git status 显示与 origin/master 同步，但实际远程有新提交。

诊断步骤：

# 1. 检查远程实际最新提交
git ls-remote origin refs/heads/master
# 输出: 4ed4a35629860072fec6f7c1c0f16b3aadd2c31b	refs/heads/master

# 2. 检查本地 origin/master
git rev-parse origin/master
# 输出: 813f1552cb826e3ddc72af8bd1fedc9d4d40df66

# 3. 如果两者不同，说明本地跟踪分支过期

解决方案：

# 强制更新远程跟踪分支
git fetch origin +refs/heads/master:refs/remotes/origin/master

# 验证更新成功
git rev-parse origin/master
# 应该输出与 git ls-remote 相同的 commit hash

Windows 长路径问题

问题描述： Windows 默认路径限制为 260 字符（MAX_PATH），某些项目（如 Nop 平台）的模板文件路径可能超过此限制。

解决方案：

1. 启用 Git 长路径支持（推荐）：

cd ~/app/nop-entropy-wt
git -C .bare config core.longpaths true

2. 系统级别启用长路径（可选，需要管理员权限）：

# 以管理员身份运行 PowerShell
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
    -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

配置写入位置：

• Git 长路径配置写入 .bare/config 文件：

[core]
    longpaths = true

适用场景：

• 创建 worktree 时遇到路径过长错误
• checkout 时遇到 Filename too long 错误
• 包含深层嵌套目录的项目

清理步骤

遇到路径混乱或无效引用时：

cd ~/app/nop-entropy-wt

# 获取项目名称（从 remote URL 提取）
PROJECT_NAME=$(git -C .bare config --get remote.origin.url | sed -E 's|.*/([^/]+?)(\.git)?$|\1|')

# 删除 worktree 引用（使用完整的 worktree 目录名）
git -C .bare worktree remove "../${PROJECT_NAME}-xxx" 2>/dev/null || true

# 删除目录
rm -rf "${PROJECT_NAME}-xxx" 2>/dev/null || true

# 清理无效引用
git -C .bare worktree prune

# 删除分支
git -C .bare branch -D xxx

# 重新创建（目录名: PROJECT_NAME-BRANCH_NAME）
git -C .bare worktree add "../${PROJECT_NAME}-xxx" -b xxx

诊断命令

cd ~/app/nop-entropy-wt

# 查看 worktree 详细状态
git -C .bare worktree list --porcelain

# 查看所有分支
git -C .bare branch -a