using-maven-worktrees

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using Maven Worktrees

使用Maven Worktrees

Overview

概述

Git worktrees for Maven projects require isolated local repositories to prevent concurrent SNAPSHOT builds from clashing.

Core principle: maven.repo.local (isolation) + maven.repo.local.tail (shared cache) = safe parallel builds.

Announce at start: "I'm using the using-maven-worktrees skill to set up an isolated Maven workspace."

在Maven项目中使用Git worktrees需要隔离的本地仓库，避免并发SNAPSHOT构建产生冲突。

核心原则： maven.repo.local（隔离能力） + maven.repo.local.tail（共享缓存）= 安全的并行构建。

开头声明： "我正在使用using-maven-worktrees技能来设置隔离的Maven工作空间。"

The Problem

存在的问题

Without isolation: Multiple worktrees building the same SNAPSHOT version write to the same

~/.m2/repository/

path, causing:

Race conditions during concurrent builds
Artifacts from one feature contaminating another
Build failures from incomplete artifact writes

Solution: Each worktree gets its own maven.repo.local, with maven.repo.local.tail pointing to shared repository for dependencies.

没有隔离的情况： 多个工作树构建相同的SNAPSHOT版本时会写入同一条

~/.m2/repository/

路径，导致：

并发构建期间出现竞态条件
一个功能分支的制品污染另一个分支的制品
制品写入不完整导致构建失败

解决方案： 每个工作树都拥有独立的maven.repo.local，同时将maven.repo.local.tail指向共享的依赖仓库。

Directory Selection Process

目录选择流程

Follow the same priority as git worktrees:

遵循和git worktrees相同的优先级：

1. Check Existing Directories

1. 检查已存在的目录

bash

undefined

bash

undefined

Check in priority order

按优先级顺序检查

ls -d .worktrees 2>/dev/null # Preferred (hidden) ls -d worktrees 2>/dev/null # Alternative


**If found:** Use that directory. If both exist, `.worktrees` wins.

ls -d .worktrees 2>/dev/null # 优先选择（隐藏目录） ls -d worktrees 2>/dev/null # 备选方案


**如果找到：** 使用该目录。如果两个都存在，优先选择`.worktrees`。

2. Check CLAUDE.md

2. 检查CLAUDE.md

bash

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

If preference specified: Use it without asking.

bash

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

如果指定了偏好： 直接使用该目录，无需询问用户。

3. Ask User

3. 询问用户

If no directory exists and no CLAUDE.md preference:

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

如果不存在对应目录，且CLAUDE.md中没有指定偏好：

未找到工作树目录。我应该在哪里创建工作树？

1. .worktrees/ （项目本地，隐藏目录）
2. ~/.config/superpowers/worktrees/<项目名称>/ （全局位置）

您更倾向于哪种选择？

Safety Verification

安全性验证

For Project-Local Directories (.worktrees or worktrees)

针对项目本地目录（.worktrees或worktrees）

MUST verify directory is ignored before creating worktree:

bash

undefined

必须在创建工作树前必须验证目录已被忽略：

bash

undefined

Check if directory is ignored

检查目录是否被忽略

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null


**If NOT ignored:**

1. Add appropriate line to .gitignore
2. Commit the change
3. Proceed with worktree creation

**Why critical:** Prevents accidentally committing worktree contents to repository.

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null


**如果未被忽略：**

1. 在.gitignore中添加对应的忽略规则
2. 提交该修改
3. 继续创建工作树

**为什么这一步很关键：** 避免不小心将工作树内容提交到代码仓库。

For Global Directory (~/.config/superpowers/worktrees)

针对全局目录（~/.config/superpowers/worktrees）

No .gitignore verification needed - outside project entirely.

无需进行.gitignore验证——目录完全在项目范围之外。

Maven Isolation Setup

Maven隔离设置

CRITICAL: Both properties required, not just maven.repo.local.

关键要求： 必须同时配置两个属性，不能只配置maven.repo.local。

1. Create Worktree

1. 创建工作树

bash

undefined

bash

undefined

Determine full path (same as git worktrees)

确定完整路径（和git worktrees规则一致）

project=$(basename "$(git rev-parse --show-toplevel)")

case $LOCATION in .worktrees|worktrees) path="$LOCATION/$BRANCH_NAME" ;; ~~/.config/superpowers/worktrees/*) path="~~/.config/superpowers/worktrees/$project/$BRANCH_NAME" ;; esac

project=$(basename "$(git rev-parse --show-toplevel)")

case $LOCATION in .worktrees|worktrees) path="$LOCATION/$BRANCH_NAME" ;; ~~/.config/superpowers/worktrees/*) path="~~/.config/superpowers/worktrees/$project/$BRANCH_NAME" ;; esac

Create worktree

创建工作树

git worktree add "$path" -b "$BRANCH_NAME" cd "$path"

undefined

git worktree add "$path" -b "$BRANCH_NAME" cd "$path"

undefined

2. Configure Maven Isolation

2. 配置Maven隔离

Create
.mvn/maven.config
with BOTH properties:

bash

mkdir -p .mvn

cat > .mvn/maven.config << 'EOF'
-Dmaven.repo.local=${session.executionRootDirectory}/.m2/repository
-Dmaven.repo.local.tail=${user.home}/.m2/repository
EOF

Why both are required:

```
maven.repo.local
```
: Isolates SNAPSHOT installs (prevents clash)
```
maven.repo.local.tail
```
: Points to shared repository for dependencies (prevents re-downloads)

Without tail: Maven downloads entire repository fresh, fails to resolve corporate plugins.

创建包含两个属性的
.mvn/maven.config
文件：

bash

mkdir -p .mvn

cat > .mvn/maven.config << 'EOF'
-Dmaven.repo.local=${session.executionRootDirectory}/.m2/repository
-Dmaven.repo.local.tail=${user.home}/.m2/repository
EOF

为什么需要同时配置两个属性：

```
maven.repo.local
```
：隔离SNAPSHOT安装（避免冲突）
```
maven.repo.local.tail
```
：指向共享的依赖仓库（避免重复下载）

没有配置tail的问题： Maven会重新下载整个仓库的内容，也会导致企业插件解析失败。

3. Verify Configuration

3. 验证配置

bash

undefined

bash

undefined

Check maven.config exists and has both properties

检查maven.config是否存在且包含两个属性

cat .mvn/maven.config

Expected output:

预期输出：

-Dmaven.repo.local=${session.executionRootDirectory}/.m2/repository

-Dmaven.repo.local.tail=${user.home}/.m2/repository

undefined

undefined

Maven Command Selection

Maven命令选择

Use Maven wrapper if available, otherwise maven:

bash

undefined

**如果存在Maven wrapper则优先使用，否则使用maven：

bash

undefined

Check for wrapper

检查是否存在wrapper

if [ -f ./mvnw ]; then MVN_CMD="./mvnw" elif [ -f ../mvnw ]; then MVN_CMD="../mvnw" else MVN_CMD="mvn" fi

undefined

if [ -f ./mvnw ]; then MVN_CMD="./mvnw" elif [ -f ../mvnw ]; then MVN_CMD="../mvnw" else MVN_CMD="mvn" fi

undefined

Baseline Verification

基线验证

Use
mvn verify
NOT
mvn install
:

bash

$MVN_CMD verify

Why verify not install:

```
mvn install
```
pollutes local repository (defeats isolation purpose)
```
mvn verify
```
runs all tests including integration tests
```
mvn test
```
might skip integration tests

If tests fail: Report failures, ask whether to proceed or investigate.

If tests pass: Report ready.

**使用

mvn verify

而非

mvn install

：

bash

$MVN_CMD verify

**为什么使用verify而非install：

```
mvn install
```
会污染本地仓库（违背隔离的目的）
```
mvn verify
```
会运行所有测试，包括集成测试
```
mvn test
```
可能会跳过集成测试

如果测试失败： 上报失败问题，询问用户是继续推进还是排查问题。

如果测试通过： 告知用户环境已就绪。

IDE Files

IDE文件

IDE project files should be local to each worktree:

IntelliJ:
```
.idea/
```
,
```
*.iml
```
- generated per worktree
Eclipse:
```
.project
```
,
```
.classpath
```
,
```
.settings/
```
- generated per worktree
VS Code:
```
.vscode/
```
- can be shared via symlink if settings are branch-agnostic

Do NOT symlink
.idea/
or Eclipse files - different branches may need different:

Compiler settings
Source roots
Module structure

IDE项目文件应该每个工作树独立保存：

IntelliJ：
```
.idea/
```
、
```
*.iml
```
- 每个工作树单独生成
Eclipse：
```
.project
```
、
```
.classpath
```
、
```
.settings/
```
- 每个工作树单独生成
VS Code：
```
.vscode/
```
- 如果设置和分支无关的话可以通过软链接共享

不要对
.idea/
或Eclipse文件创建软链接 - 不同分支可能需要不同的：

编译器设置
源码根目录
模块结构

Quick Reference

快速参考

Situation	Action
`.worktrees/` exists	Use it (verify ignored)
`worktrees/` exists	Use it (verify ignored)
Both exist	Use `.worktrees/`
Neither exists	Check CLAUDE.md → Ask user
Directory not ignored	Add to .gitignore + commit
Tests fail during baseline	Report failures + ask
mvnw exists	Use `./mvnw` over `mvn`
Baseline verification	Use `mvn verify` not `mvn install`
IDE files	Generate per worktree, don't share

场景	操作
`.worktrees/` 存在	使用它（验证已被忽略）
`worktrees/` 存在	使用它（验证已被忽略）
两个都存在	使用 `.worktrees/`
两个都不存在	检查CLAUDE.md → 询问用户
目录未被忽略	添加到.gitignore + 提交
基线测试失败	上报失败 + 询问用户
存在mvnw	优先使用 `./mvnw` 而非 `mvn`
基线验证	使用 `mvn verify` 而非 `mvn install`
IDE文件	每个工作树单独生成，不要共享

Maven Config Verification Checklist

Maven配置验证检查清单

Before reporting "ready", verify:

```
.mvn/maven.config
```
exists

Contains

-Dmaven.repo.local=${session.executionRootDirectory}/.m2/repository

Contains

-Dmaven.repo.local.tail=${user.home}/.m2/repository

Both properties on separate lines
No typos in property names

在上报“就绪”之前，验证：

```
.mvn/maven.config
```
已存在

包含

-Dmaven.repo.local=${session.executionRootDirectory}/.m2/repository

包含

-Dmaven.repo.local.tail=${user.home}/.m2/repository

两个属性分两行展示
属性名称没有拼写错误

Common Mistakes

常见错误

Using shared

~/.m2/repository

使用共享的

~/.m2/repository

Problem: Multiple worktrees installing same SNAPSHOT version clash Fix: Always create

.mvn/maven.config

with maven.repo.local

问题： 多个工作树安装相同的SNAPSHOT版本时产生冲突 修复方案： 始终创建包含maven.repo.local配置的

.mvn/maven.config

文件

Setting maven.repo.local without maven.repo.local.tail

只配置maven.repo.local不配置maven.repo.local.tail

Problem:

Maven downloads entire repository fresh (slow)
Corporate/internal plugins fail to resolve
Defeats purpose of local repository cache

Fix: Always set BOTH properties

问题：

Maven会重新下载整个仓库的内容（速度很慢）
企业/内部插件解析失败
浪费本地仓库缓存的作用

修复方案： 始终同时配置两个属性

Using

mvn install

for baseline verification

基线验证使用

mvn install

Problem: Pollutes local repository, defeats isolation Fix: Use

mvn verify

- runs all tests without installing

问题： 污染本地仓库，违背隔离目的 修复方案： 使用

mvn verify

- 运行所有测试但不执行安装操作

Sharing IDE project files between worktrees

多个工作树共享IDE项目文件

Problem:

Different branches may have different source structure
IDE confusion when switching between worktrees
Conflicting compiler/module settings

Fix: Generate IDE files per worktree, add to .gitignore

问题：

不同分支可能有不同的源码结构
切换工作树时IDE出现识别混乱
编译器/模块设置冲突

修复方案： 每个工作树单独生成IDE文件，添加到.gitignore

Assuming default Maven config works

认为默认Maven配置可以正常工作

Problem: No isolation, SNAPSHOT artifacts clash Fix: Always explicitly configure maven.repo.local + tail

问题： 没有隔离能力，SNAPSHOT制品冲突 修复方案： 始终显式配置maven.repo.local + tail

Rationalization Table

合理性对照表

Excuse	Reality
"Default Maven config is fine"	Concurrent SNAPSHOT installs will clash without isolation
"maven.repo.local alone is enough"	Without tail, downloads everything fresh and plugins fail
"Shared repository is normal"	Normal for single workspace, broken for parallel worktrees
"No time for advanced setup"	Setup takes 30 seconds, debugging clashes takes hours
"This is complete isolation"	Complete = maven.repo.local + maven.repo.local.tail
"mvn install verifies properly"	mvn install pollutes repo, use mvn verify
"IDE files should be consistent"	IDE files reflect code structure, which varies by branch

借口	实际情况
"默认Maven配置就没问题"	没有隔离的话并发SNAPSHOT安装一定会冲突
"只配置maven.repo.local就够了"	没有tail的话会重新下载所有内容，插件也会解析失败
"共享仓库是常规操作"	单工作空间正常，并行工作树场景下会出问题
"没时间做高级配置"	配置只需要30秒，排查冲突问题需要几小时
"这就是完全隔离了"	完整隔离 = maven.repo.local + maven.repo.local.tail
"mvn install就能完成正确验证"	mvn install会污染仓库，应该用mvn verify
"IDE文件应该保持一致"	IDE文件反映代码结构，不同分支的结构可能不一样

Red Flags - STOP and Fix

危险信号 - 停止操作并修复

Never:

Create Maven worktree without
```
.mvn/maven.config
```
Set maven.repo.local without maven.repo.local.tail
Use
```
mvn install
```
for baseline verification
Symlink
```
.idea/
```
or Eclipse project files
Skip maven.config verification before reporting ready
Assume default Maven behavior works for worktrees

Always:

Configure BOTH maven.repo.local AND maven.repo.local.tail
Use
```
mvn verify
```
for baseline
Generate IDE files per worktree
Verify maven.config exists and is correct

绝对不要：

不创建
```
.mvn/maven.config
```
就创建Maven工作树
只配置maven.repo.local不配置maven.repo.local.tail
基线验证使用
```
mvn install
```
对
```
.idea/
```
或Eclipse项目文件创建软链接
上报就绪前跳过maven.config验证
认为默认Maven行为适配工作树场景

必须做到：

同时配置maven.repo.local 和 maven.repo.local.tail
基线验证使用
```
mvn verify
```
每个工作树单独生成IDE文件
验证maven.config存在且配置正确

Example Workflow

示例工作流

You: I'm using the using-maven-worktrees skill to set up an isolated Maven workspace.

[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms]
[Create worktree: git worktree add .worktrees/feature-auth -b feature/auth]
[cd .worktrees/feature-auth]
[Create .mvn/maven.config with maven.repo.local + maven.repo.local.tail]
[Verify config exists and has both properties]
[Run ./mvnw verify - 127 tests passing]

Worktree ready at /Users/max/myproject/.worktrees/feature-auth
Maven isolation configured:
  - maven.repo.local: .m2/repository (worktree-local)
  - maven.repo.local.tail: ~/.m2/repository (shared cache)
Tests passing (127 tests, 0 failures)
Ready to implement authentication feature

你：我正在使用using-maven-worktrees技能来设置隔离的Maven工作空间。

[检查 .worktrees/ - 存在]
[验证已被忽略 - git check-ignore确认]
[创建工作树：git worktree add .worktrees/feature-auth -b feature/auth]
[切换到目录：cd .worktrees/feature-auth]
[创建包含maven.repo.local + maven.repo.local.tail的.mvn/maven.config文件]
[验证配置存在且包含两个属性]
[运行 ./mvnw verify - 127个测试通过]

工作树已就绪，路径：/Users/max/myproject/.worktrees/feature-auth
Maven隔离已配置：
  - maven.repo.local: .m2/repository（工作树本地）
  - maven.repo.local.tail: ~/.m2/repository（共享缓存）
测试通过（127个测试，0个失败）
可以开始开发认证功能开发了

Real-World Impact

实际收益

Problem solved: Prevents hours of debugging why "it works in my worktree but fails in yours" when both are building same SNAPSHOT version.

Performance: maven.repo.local.tail prevents re-downloading 500MB+ of dependencies per worktree.

Corporate environments: Ensures internal/corporate Maven plugins resolve correctly via tail repository.

解决的问题： 避免花费数小时调试“在我的工作树能运行但在你的工作树失败”的问题，这类问题通常是两个工作树构建相同的SNAPSHOT版本导致的。

性能收益： maven.repo.local.tail避免每个工作树重新下载500MB以上的依赖。

企业环境适配： 通过tail仓库确保内部/企业Maven插件可以正常解析。

using-maven-worktrees

Original

Translation

Using Maven Worktrees

使用Maven Worktrees

Overview

概述

The Problem

存在的问题

Directory Selection Process

目录选择流程

1. Check Existing Directories

1. 检查已存在的目录

Check in priority order

按优先级顺序检查

2. Check CLAUDE.md

2. 检查CLAUDE.md

3. Ask User

3. 询问用户

Safety Verification

安全性验证

For Project-Local Directories (.worktrees or worktrees)

针对项目本地目录（.worktrees或worktrees）

Check if directory is ignored

检查目录是否被忽略

For Global Directory (~/.config/superpowers/worktrees)

针对全局目录（~/.config/superpowers/worktrees）

Maven Isolation Setup

Maven隔离设置

1. Create Worktree

1. 创建工作树

Determine full path (same as git worktrees)

确定完整路径（和git worktrees规则一致）

Create worktree

创建工作树

2. Configure Maven Isolation

2. 配置Maven隔离

3. Verify Configuration

3. 验证配置

Check maven.config exists and has both properties

检查maven.config是否存在且包含两个属性

Expected output:

预期输出：

-Dmaven.repo.local=${session.executionRootDirectory}/.m2/repository

-Dmaven.repo.local=${session.executionRootDirectory}/.m2/repository

-Dmaven.repo.local.tail=${user.home}/.m2/repository

-Dmaven.repo.local.tail=${user.home}/.m2/repository

Maven Command Selection

Maven命令选择

Check for wrapper

检查是否存在wrapper

Baseline Verification

基线验证

IDE Files

IDE文件

Quick Reference

快速参考

Maven Config Verification Checklist

Maven配置验证检查清单

Common Mistakes

常见错误

Using shared ~/.m2/repository

使用共享的~/.m2/repository

Setting maven.repo.local without maven.repo.local.tail

只配置maven.repo.local不配置maven.repo.local.tail

Using mvn install for baseline verification

基线验证使用mvn install

Sharing IDE project files between worktrees

多个工作树共享IDE项目文件

Assuming default Maven config works

认为默认Maven配置可以正常工作

Rationalization Table

合理性对照表

Red Flags - STOP and Fix

危险信号 - 停止操作并修复

Example Workflow

示例工作流

Real-World Impact

实际收益

Using shared
`~/.m2/repository`

使用共享的
`~/.m2/repository`

Using
`mvn install`
for baseline verification

基线验证使用
`mvn install`