Base ref, hotfix base, port block

Tổng quan

Mỗi repo trong workspace có một branch tích hợp riêng (staging, develop, main, ...) và một cách resolve base riêng cho hotfix. Nếu một skill hardcode tên branch, nó đúng ở repo này và sai âm thầm ở repo kế bên.

.claude/worktree.json khai báo base như một fact của repo. Kit đọc file này khi cần thay vì đoán. Cùng file đó cấp cho mỗi repo một khối port riêng, để nhiều worktree ở nhiều repo chạy song song không trùng port.

Cách hoạt động

Ví dụ thật, .claude/worktree.json của chính repo zenify-kit:

json

{
  "abbrev": "kit",
  "baseRef": "origin/main",
  "worktreeDir": ".worktrees/",
  "copy": [".claude/settings.local.json"],
  "deps": "none",
  "portEnv": "PORT",
  "portRange": [3750, 3799]
}

Trường	Ý nghĩa
`baseRef`	branch gốc mặc định cho `zenify wt new --type feat/fix`
`portRange`	khối 50 port riêng của repo này (3750–3799)
`portEnv`	tên biến môi trường worktree đọc port từ đó
`deps`	`none` ở đây vì kit không có `node_modules` để seed

Hotfix có một hàm resolve base, dùng chung cho zenify wt new --type hotfix và zenify hotfix baseref <repoPath>, nên hai lệnh luôn ra cùng một ref.

Có hotfixBaseRef thì dùng nó. custom bắt buộc có, thiếu thì lỗi.
staging, standalone hoặc không khai mà không có hotfixBaseRef thì dùng baseRef. wt new cảnh báo wt: no hotfixBaseRef declared — branching this hotfix from <base>.
release-latest báo lỗi. Chiến lược này đoán nhánh release<N> lớn nhất, và khi team thôi cắt nhánh release thì nhánh đó trông như mới nhất dù đã cũ.
Cờ --base của wt new luôn thắng.

Thứ tự ưu tiên khi resolve base cho hotfix

Repo không khai báo gì vẫn nhận branch tích hợp làm base mà không báo lỗi. Vì vậy /znf:hotfix đối chiếu base với tag release: base không chứa tag release mới nhất thì skill hỏi bạn trước khi tạo worktree. zenify wt url <slug> in port đã cấp cho worktree.

Base thật của worktree: `zenify wt base`

baseRef là base mặc định của repo, còn một worktree có thể được cắt từ branch khác (ví dụ chồng PR lên một feature branch). Skill cần merge-base đúng với base thật, không phải trunk của repo, nên kit có lệnh in nó ra:

zenify wt base

Lệnh in đúng một dòng, là ref đầu tiên có giá trị theo thứ tự: wt.base (git config của worktree, do wt new ghi lúc tạo), rồi baseRef trong .claude/worktree.json, rồi origin/main. Vì stdout chỉ có ref và xuống dòng nên dùng được trong $(zenify wt base). Khi phải lùi về origin/main (không có wt.base lẫn baseRef), lệnh vẫn thoát 0 nhưng in thêm một dòng cảnh báo ra stderr wt base: no wt.base or baseRef found; using origin/main, để bạn biết merge-base đang tính với trunk mặc định. Ví dụ thật trong một repo tạm, đặt wt.base rồi bỏ nó đi:

text

$ git config --worktree wt.base origin/staging
$ zenify wt base
origin/staging
$ git config --worktree --unset wt.base
$ zenify wt base
origin/main
wt base: no wt.base or baseRef found; using origin/main      # dòng này ra stderr

Các skill ship và subagent-driven-development tính merge-base bằng lệnh này.

Liên quan

Worktree theo slug: nơi --base được dùng.
Tham chiếu lệnh: zenify wt config, zenify wt base.

Lưu ý

Fetch trước, resolve sau. Thứ tự này không đảo được. Resolve base hotfix trước khi fetch thì ref local có thể đứng sau remote, và hotfix tách từ bản cũ. Lỗi này chỉ lộ khi merge. zenify wt new bản hiện tại tự fetch trước khi resolve, nhưng bản cũ có thể chưa, nên bạn vẫn fetch tay trước khi gọi.
Hai repo trùng port block làm hai worktree ở hai repo tranh nhau một port khi chạy song song. Khi thêm repo mới, đọc portRange của các repo lân cận trước khi chọn khối tiếp theo.

Base ref, hotfix base, port block ​

Tổng quan ​

Cách hoạt động ​

Base thật của worktree: zenify wt base ​

Liên quan ​