git-worktree-manager

Tổng quan về git-worktree-manager skill

git-worktree-manager dùng để làm gì

git-worktree-manager là một engineering skill giúp vận hành nhiều Git worktree cục bộ cùng lúc mà không bị xung đột branch, port, môi trường hoặc dọn dẹp. Skill này kết hợp hướng dẫn thao tác với các script hỗ trợ bằng Python để tạo worktree đã chuẩn bị sẵn, gán port theo quy tắc ổn định, sao chép file môi trường cục bộ, tùy chọn cài dependency, và rà soát các worktree cũ trước khi xóa.

Hãy dùng git-worktree-manager skill khi các lệnh git worktree thông thường chưa đủ, vì mỗi branch cần hoạt động như một ứng dụng riêng có thể chạy độc lập.

Phù hợp nhất cho workflow Git song song

Người dùng phù hợp nhất là developer, tech lead hoặc người vận hành coding agent thường mở từ hai branch trở lên cùng lúc: làm feature, hotfix, review PR, kiểm thử migration hoặc triển khai đa agent. git-worktree-manager for Git Workflows đặc biệt hữu ích khi mỗi agent hoặc mỗi phiên terminal nên sở hữu một branch và một runtime tách biệt, thay vì cùng dùng chung một checkout.

Skill này sẽ kém hữu ích hơn nếu bạn chỉ thỉnh thoảng chuyển branch, không chạy service cục bộ, hoặc đã có một wrapper worktree nội bộ đủ hoàn thiện.

Điểm khác biệt chính trước khi cài đặt

Giá trị thực tế không chỉ là “tạo một worktree”. Skill này bổ sung các quy ước có thể lặp lại cho:

• đặt tên worktree và tạo branch theo quy tắc ổn định
• phân bổ port không chồng lấn cho app, database và Redis
• đồng bộ .env, .env.local, .env.development và .envrc
• phát hiện nhu cầu cài dependency từ các lockfile phổ biến
• kiểm tra worktree cũ, còn thay đổi chưa commit, và branch đã merge trước khi dọn dẹp
• mẫu Docker Compose để cô lập service theo từng worktree

Vì vậy, git-worktree-manager skill thiên về vận hành thực tế hơn một prompt Git worktree chung chung.

Cách sử dụng git-worktree-manager skill

Tùy chọn cài đặt git-worktree-manager

Với thiết lập skill kiểu Claude, hãy cài từ repository bằng skill manager nếu có:

npx skills add alirezarezvani/claude-skills --skill git-worktree-manager

Nếu cài thủ công, sao chép thư mục skill từ:

engineering/skills/git-worktree-manager

vào thư mục skills cục bộ của bạn, chẳng hạn ~/.claude/skills/git-worktree-manager, ~/.codex/skills/git-worktree-manager, hoặc một thư mục agent skill tương thích khác. Sau khi cài, hãy kiểm tra các file sau đã có mặt: SKILL.md, README.md, scripts/worktree_manager.py, scripts/worktree_cleanup.py, và hai file nằm trong references/.

Nên đọc các file này trước

Để bắt đầu nhanh, hãy đọc theo thứ tự sau:

1. README.md để nắm dạng lệnh và danh sách công cụ.
2. SKILL.md để hiểu workflow dự kiến và hướng dẫn khi nào nên dùng.
3. references/port-allocation-strategy.md trước khi thay đổi port service.
4. references/docker-compose-patterns.md nếu ứng dụng của bạn dùng Compose.
5. scripts/worktree_manager.py và scripts/worktree_cleanup.py trước khi tin tưởng automation trong repository production.

Điều này quan trọng vì các script sẽ thao tác lên checkout thật, sao chép file env và có thể cài dependency. Hãy rà soát các giá trị mặc định trước khi chạy trên một monorepo lớn hoặc repository có cấu hình cục bộ nhạy cảm.

Cách dùng git-worktree-manager trong thực tế

Một flow tạo và chuẩn bị worktree điển hình là:

python scripts/worktree_manager.py \
  --repo . \
  --branch feature/api-hardening \
  --name wt-api-hardening \
  --base-branch main \
  --install-deps \
  --format text

Một flow rà soát dọn dẹp là:

python scripts/worktree_cleanup.py \
  --repo . \
  --stale-days 14 \
  --format text

Cả hai công cụ đều hỗ trợ input JSON qua --input <json-file> hoặc stdin, rất hữu ích cho automation. Hãy yêu cầu agent tạo kế hoạch lệnh trước, rồi chỉ chạy script sau khi bạn đã xác nhận repo path, branch name, base branch, hành vi cài dependency và chính sách cleanup.

Mẫu prompt để có kết quả tốt hơn

Prompt yếu:

Set up a worktree for my feature.

Prompt tốt hơn:

Use git-worktree-manager to prepare a new worktree for branch feature/billing-webhooks from main in repo /Users/me/app. Name it wt-billing-webhooks. I run app, Postgres, and Redis locally, so allocate non-conflicting ports and write the resulting mapping. Copy env files but do not install dependencies until I approve the command. Show the exact script command and any Docker Compose override I may need.

Prompt này cung cấp đủ thông tin để skill chọn chiến lược branch, tránh xung đột port, giữ an toàn với các file .env*, và tách riêng bước lập kế hoạch khỏi bước thực thi.

FAQ về git-worktree-manager skill

git-worktree-manager chỉ dành cho AI agent phải không?

Không. Skill này được tối ưu cho công việc đa agent, nhưng các script và quy ước của nó cũng hữu ích cho developer làm việc thủ công. Lợi ích chính là tính lặp lại: mỗi worktree đều có branch, thư mục, port, file env được sao chép và bước rà soát cleanup theo quy tắc rõ ràng, thay vì phụ thuộc vào lịch sử lệnh shell rời rạc.

Khác gì so với git worktree thông thường?

git worktree add thông thường chỉ tạo thêm một checkout. Nó không giải quyết các xung đột khi chạy app cục bộ. git-worktree-manager bổ sung workflow xung quanh: các block port, .worktree-ports.json, sao chép file môi trường, tùy chọn cài dependency, gợi ý cô lập Docker Compose, và kiểm tra cleanup cho branch cũ hoặc đã merge.

Người mới có thể dùng an toàn không?

Có, nếu xem đây là một workflow có hướng dẫn thay vì một công cụ chạy lệnh mù quáng. Người mới nên bắt đầu bằng các thao tác liệt kê/rà soát, dùng --format text, tránh xóa tự động, và kiểm tra các lệnh được tạo trước khi thực thi. Script cleanup có kiểm tra worktree còn thay đổi chưa commit, nhưng bạn vẫn nên hiểu branch nào an toàn để xóa.

Khi nào không nên dùng skill này?

Không nên dùng nguyên trạng nếu repository của bạn có cách xử lý môi trường khác thường, có secret tuyệt đối không được sao chép, quy trình cài dependency không chuẩn, hoặc port service được quản lý bởi một nền tảng nội bộ. Trong các trường hợp đó, hãy dùng git-worktree-manager guide như một mẫu khởi đầu rồi tùy chỉnh script hoặc prompt trước khi áp dụng.

Cách cải thiện git-worktree-manager skill

Cung cấp thêm ngữ cảnh repository cho git-worktree-manager

Input càng tốt thì kế hoạch worktree càng an toàn. Hãy cung cấp:

• absolute repo path
• target branch và base branch
• tên thư mục worktree mong muốn
• package manager hoặc lockfile kỳ vọng
• các service cần port
• có được sao chép file .env* hay không
• có cho phép cài dependency hay không
• ngưỡng tuổi cleanup và base branch dùng để kiểm tra merge

Điều này giảm phỏng đoán và tránh việc agent tự áp dụng các mặc định không khớp với ứng dụng của bạn.

Tinh chỉnh quy ước port và Docker Compose cho git-worktree-manager

Chiến lược tham chiếu dùng các base mặc định như app 3000, Postgres 5432, Redis 6379, với stride 10 cho mỗi worktree. Nếu stack của bạn có nhiều service hơn, hãy dành một block liền mạch lớn hơn. Nếu bạn chạy hạ tầng cục bộ bên ngoài các worktree, hãy dịch chuyển base port để tránh xung đột toàn cục.

Với Docker Compose, nên ưu tiên override theo từng worktree, port điều khiển bằng .env, và project name riêng biệt, chẳng hạn:

docker compose -p myapp_wt_auth up -d

Cách này tránh xung đột container, network, volume và database giữa các branch.

Theo dõi các lỗi thường gặp

Các vấn đề phổ biến nhất là secret bị sao chép, dùng lại port database mặc định, chia sẻ Docker volume giữa các migration không tương thích, cài dependency sai runtime, và xóa worktree vẫn còn thay đổi chưa commit. Sau mỗi lần chạy, hãy yêu cầu agent báo cáo dirty status, các file env đã sao chép, port đã chọn và hành động cài đặt.

Với cleanup, hãy bắt đầu bằng output chỉ để rà soát. Chỉ bật xóa sau khi xác nhận worktree đã cũ, sạch và đã merge vào đúng base branch mong đợi.

Lặp lại sau kết quả đầu tiên

Sau kế hoạch hoặc lệnh đầu tiên, hãy yêu cầu chỉnh sửa có trọng tâm thay vì bắt đầu lại từ đầu:

Revise the git-worktree-manager command to skip dependency installation, use base branch develop, reserve ports for app, Postgres, Redis, and Mailhog, and output JSON for automation.

Cách này giữ skill bám sát các ràng buộc thật của repository, đồng thời cải thiện độ an toàn và khả năng tái lập.