git-worktree-manager
Git Worktree Manager
- License 许可
- MIT
- 最近更新
- 2026-04-01
- Stars
- ★ 3
- Forks
- 2
01 前言 Front Matter
- name
- git-worktree-manager
- description
- Git Worktree Manager
02 资源文件 5
- 参考文档README.md1.3 KB
- 参考文档references/docker-compose-patterns.md1.1 KB
- 参考文档references/port-allocation-strategy.md1.0 KB
- 脚本scripts/worktree_cleanup.py6.5 KB
- 脚本scripts/worktree_manager.py8.4 KB
03 SKILL.md 正文
Git Worktree Manager
Tier: POWERFUL
Category: Engineering
Domain: Parallel Development & Branch Isolation
Overview
Use this skill to run parallel feature work safely with Git worktrees. It standardizes branch isolation, port allocation, environment sync, and cleanup so each worktree behaves like an independent local app without stepping on another branch.
This skill is optimized for multi-agent workflows where each agent or terminal session owns one worktree.
Core Capabilities
- Create worktrees from new or existing branches with deterministic naming
- Auto-allocate non-conflicting ports per worktree and persist assignments
- Copy local environment files (
.env*) from main repo to new worktree - Optionally install dependencies based on lockfile detection
- Detect stale worktrees and uncommitted changes before cleanup
- Identify merged branches and safely remove outdated worktrees
When to Use
- You need 2+ concurrent branches open locally
- You want isolated dev servers for feature, hotfix, and PR validation
- You are working with multiple agents that must not share a branch
- Your current branch is blocked but you need to ship a quick fix now
- You want repeatable cleanup instead of ad-hoc
rm -rfoperations
Key Workflows
1. Create a Fully-Prepared Worktree
- Pick a branch name and worktree name.
- Run the manager script (creates branch if missing).
- Review generated port map.
- Start app using allocated ports.
python scripts/worktree_manager.py \
--repo . \
--branch feature/new-auth \
--name wt-auth \
--base-branch main \
--install-deps \
--format text
If you use JSON automation input:
cat config.json | python scripts/worktree_manager.py --format json
# or
python scripts/worktree_manager.py --input config.json --format json
2. Run Parallel Sessions
Recommended convention:
- Main repo: integration branch (
main/develop) on default port - Worktree A: feature branch + offset ports
- Worktree B: hotfix branch + next offset
Each worktree contains .worktree-ports.json with assigned ports.
3. Cleanup with Safety Checks
- Scan all worktrees and stale age.
- Inspect dirty trees and branch merge status.
- Remove only merged + clean worktrees, or force explicitly.
python scripts/worktree_cleanup.py --repo . --stale-days 14 --format text
python scripts/worktree_cleanup.py --repo . --remove-merged --format text
4. Docker Compose Pattern
Use per-worktree override files mapped from allocated ports. The script outputs a deterministic port map; apply it to docker-compose.worktree.yml.
See docker-compose-patterns.md for concrete templates.
5. Port Allocation Strategy
Default strategy is base + (index * stride) with collision checks:
- App:
3000 - Postgres:
5432 - Redis:
6379 - Stride:
10
See port-allocation-strategy.md for the full strategy and edge cases.
Script Interfaces
python scripts/worktree_manager.py --help- Create/list worktrees
- Allocate/persist ports
- Copy
.env*files - Optional dependency installation
python scripts/worktree_cleanup.py --help- Stale detection by age
- Dirty-state detection
- Merged-branch detection
- Optional safe removal
Both tools support stdin JSON and --input file mode for automation pipelines.
Common Pitfalls
- Creating worktrees inside the main repo directory
- Reusing
localhost:3000across all branches - Sharing one database URL across isolated feature branches
- Removing a worktree with uncommitted changes
- Forgetting to prune old metadata after branch deletion
- Assuming merged status without checking against the target branch
Best Practices
- One branch per worktree, one agent per worktree.
- Keep worktrees short-lived; remove after merge.
- Use a deterministic naming pattern (
wt-<topic>). - Persist port mappings in file, not memory or terminal notes.
- Run cleanup scan weekly in active repos.
- Use
--format jsonfor machine flows and--format textfor human review. - Never force-remove dirty worktrees unless changes are intentionally discarded.
Validation Checklist
Before claiming setup complete:
git worktree listshows expected path + branch..worktree-ports.jsonexists and contains unique ports..envfiles copied successfully (if present in source repo).- Dependency install command exits with code
0(if enabled). - Cleanup scan reports no unintended stale dirty trees.
References
- port-allocation-strategy.md
- docker-compose-patterns.md
- README.md for quick start and installation details
Decision Matrix
Use this quick selector before creating a new worktree:
- Need isolated dependencies and server ports -> create a new worktree
- Need only a quick local diff review -> stay on current tree
- Need hotfix while feature branch is dirty -> create dedicated hotfix worktree
- Need ephemeral reproduction branch for bug triage -> create temporary worktree and cleanup same day
Operational Checklist
Before Creation
- Confirm main repo has clean baseline or intentional WIP commits.
- Confirm target branch naming convention.
- Confirm required base branch exists (
main/develop). - Confirm no reserved local ports are already occupied by non-repo services.
After Creation
- Verify
git statusbranch matches expected branch. - Verify
.worktree-ports.jsonexists. - Verify app boots on allocated app port.
- Verify DB and cache endpoints target isolated ports.
Before Removal
- Verify branch has upstream and is merged when intended.
- Verify no uncommitted files remain.
- Verify no running containers/processes depend on this worktree path.
CI and Team Integration
- Use worktree path naming that maps to task ID (
wt-1234-auth). - Include the worktree path in terminal title to avoid wrong-window commits.
- In automated setups, persist creation metadata in CI artifacts/logs.
- Trigger cleanup report in scheduled jobs and post summary to team channel.
Failure Recovery
- If
git worktree addfails due to existing path: inspect path, do not overwrite. - If dependency install fails: keep worktree created, mark status and continue manual recovery.
- If env copy fails: continue with warning and explicit missing file list.
- If port allocation collides with external service: rerun with adjusted base ports.
04 同仓库更多 Skills
soc2-compliance
Use when the user asks to prepare for SOC 2 audits, map Trust Service Criteria, build control matrices, collect audit evidence, perform gap analysis, or assess SOC 2 Type I vs Type II readiness.
risk-management-specialist
Medical device risk management specialist implementing ISO 14971 throughout product lifecycle. Provides risk analysis, risk evaluation, risk control, and post-production information analysis. Use when user mentions risk management, ISO 14971, risk analysis, FMEA, fault tree analysis, hazard identification, risk control, risk matrix, benefit-risk analysis, residual risk, risk acceptability, or post-market risk.
regulatory-affairs-head
Senior Regulatory Affairs Manager for HealthTech and MedTech companies. Prepares FDA 510(k), De Novo, and PMA submission packages; analyzes regulatory pathways for new medical devices; drafts responses to FDA deficiency letters and Notified Body queries; develops CE marking technical documentation under EU MDR 2017/745; coordinates multi-market approval strategies across FDA, EU, Health Canada, PMDA, and NMPA; and maintains regulatory intelligence on evolving standards. Use when users need to plan or execute FDA submissions, navigate 510(k) or PMA approval processes, achieve CE marking, prepare pre-submission meeting materials, write regulatory strategy documents, respond to agency queries, or manage compliance documentation for medical device market access.
quality-manager-qms-iso13485
ISO 13485 Quality Management System implementation and maintenance for medical device organizations. Provides QMS design, documentation control, internal auditing, CAPA management, and certification support. Use when working with medical device quality systems, preparing for ISO 13485 audits, managing regulatory compliance documentation, setting up corrective actions, or building audit preparation programs. Useful for quality management, audit preparation, regulatory compliance, medical device documentation, and corrective action workflows.
quality-manager-qmr
Senior Quality Manager Responsible Person (QMR) for HealthTech and MedTech companies. Provides quality system governance, management review leadership, regulatory compliance oversight, and quality performance monitoring per ISO 13485 Clause 5.5.2.
quality-documentation-manager
Document control system management for medical device QMS. Covers document numbering, version control, change management, and 21 CFR Part 11 compliance. Use for document control procedures, change control workflow, document numbering, version management, electronic signature compliance, or regulatory documentation review.