SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsworktree-rebase-merge

worktree-rebase-merge

Coding & development

View repository

Updated 10-16 08:49

About this skill

Worktree Rebase/Merge workflow

Use this skill to complete a worktree branch: commit the source branch, rebase it onto the target branch, then merge from the worktree checked out onto that target branch. When the current branch is already the resolved target branch, skip the rebase/merge path and commit directly via the git-commit skill. All source branch and direct commit mechanisms are delegated to git-commit。

Default rules

  • When the user provides a target branch, use that branch; otherwise resolve the repository remote default branch.
  • When resolving the remote default branch, prefer origin; if origin does not exist and there is exactly one remote, use that remote. Query the live remote HEAD via git ls-remote --symref <remote> HEAD , read the ref: refs/heads/<branch> HEAD line, then remove the refs/heads/ prefix. This read-only query is not a fetch or pull.
  • If the live remote HEAD query fails or there is no branch ref, do not silently trust the cached refs/remotes/<remote>/HEAD. Only read that symbolic ref to report a candidate fallback value, then stop and ask the user to specify or confirm the target branch.
  • Treat the current checkout as the source branch. If in a detached state, create the source branch before continuing.
  • Unless the user explicitly requests it, do not fetch, pull, or push.
  • Only stage user-selected files, already staged commit files,git-commit the single time git add .when the index is empty, or conflict resolution files.

Preflight

  • Resolve the target branch before branch checks. If remote selection is ambiguous, the live remote HEAD is unavailable or cannot be resolved, or the resolved local target branch does not exist, stop and ask the user to specify or confirm the target branch.
  • Run git branch --show-current、git branch --list <target-branch> and git status --short。
  • For a detached HEAD, before choosing direct commit or normal rebase/merge mode, first follow Attach Detached HEAD。
  • If the source branch and target branch resolve to the same branch, enter direct commit mode.
  • Normal rebase/merge mode runs git worktree list。
  • From git worktree list , find an existing target worktree whose branch is exactly <target-branch> . When present, use that path to complete the final merge.
  • Do not require the user's main checkout to currently be on <target-branch>. If no worktree is checked out to the target branch, plan to create a temporary target worktree for the merge step; do not switch the branch of any other checkout.
  • If multiple worktrees are checked out to <target-branch>, use the first clean worktree. If all target worktrees have changes, record each dirty target path and its git status --short output. For now, do not touch the target worktree or stop; first complete source branch creation and source commits, then use the dirty target pause flow below.

Attach Detached HEAD

When git branch --show-current is empty, automatically create the source branch without staging files and without changing the current commit:

  1. Record git rev-parse HEAD and the full git status --short output.
  2. Infer the main intent of the work from the first useful source below. Only check subsequent sources if the previous source is empty or ambiguous:
    • staged diff；
    • the contents of the unstaged diff and related untracked files;
    • git log <target-branch>..HEAD commits in .
  3. If all three sources are empty, report that there is nothing to commit or merge, and stop without creating a branch.
  4. Use git-commit skill's Branch Name Guidance to derive candidate names based on the above evidence. Derive names only here; do not enter that skill's staging or commit workflow for now.
  5. Use git check-ref-format --branch <branch-name> to validate the candidate name.
  6. Resolve local name conflicts without overwriting branches:
    • If the candidate branch does not exist, run git switch -c <branch-name>。
    • If it points to a recorded detached commit, and is not checked out in another worktree, run git switch <branch-name> and reuse it.
    • Otherwise append -2、-3in sequence until an unused valid name is found, then run git switch -c <numbered-branch-name>. Use git show-ref --verify and git worktree list --porcelain to distinguish these cases. Never reset or move an existing branch.
  7. Validate the selected source branch, confirm that git rev-parse HEAD still matches the recorded commit, and require git status --short to remain in exactly the same staged, unstaged, and untracked state. If attaching changes the contents, then stop.

Do not stage files just to generate a branch name. After attaching, continue the normal commit, rebase, and merge workflow.

Commit directly on the target branch

  • Use direct commit mode only when the current source branch is the same branch as the resolved target branch.
  • In direct commit mode, fully delegate to the git-commit skill: staging scope, the single git add .when the index is empty, commit message drafting, commit execution, permission retries, and cleanup all follow git-commit。
  • Do not create a temporary source branch, do not run git rebase or git merge, do not look for the target worktree, do not create a temporary target worktree, and do not fetch, pull, or push.
  • After the commit step, use git-commit 's Post-Commit Report, and state that no rebase, merge, or push was performed.

Commit the source branch

  • For the already staged source changes, use the git-commit mechanism. Staging scope, the only allowed single git add .when the index is empty, commit message drafting, commit execution, permission retries, and cleanup are all the responsibility of that skill. In normal rebase/merge mode, this workflow overrides git-commit 's default mode report order; in direct commit mode follow git-commit report.
  • Before the commit step, record the source HEAD. Only when the commit step changes HEAD , classify the source result as created-this-run; otherwise, if the source is already committed and clean, classify it as preexisting-source-commit。
  • Create commit_message.txt or run git commit -F commit_message.txt Before, send a normal assistant message, use the fixed title 提交信息预览, and in the text code fence include the complete actual proposed commit message.
  • Except for the Markdown code fence, the preview text must be exactly the same as the subsequent commit_message.txt content. It must not appear only in tool output, terminal output, hidden reasoning, log files,commit_message.txt or final Git command output.
  • Continue automatically once the body preview is visible, unless the user explicitly requests confirmation, preview only, draft only, no submission, or modification of the submission information.
  • If git-commit report has no content to submit, continue only when the source worktree contains no uncommitted changes, and mark the result as preexisting-source-commit; otherwise stop and report the uncommitted status.
  • After the commit step, rerun git status --short. Unless the user explicitly decides otherwise, perform the rebase only from a clean source worktree.

Dirty target pause

  • If the precheck finds that <target-branch> only has a dirty worktree, complete the source commit via git-commit and require the source worktree to be clean, then stop before the scope check, rebase, merge, or push.
  • In this recovery path, never perform staging, committing, stash, restore, clean, or other modifications on the dirty target worktree.
  • Report the source branch and commit hash, each dirty target path and dirty file, and explain that the source changes have been committed while the target worktree remains unchanged. Explicitly state that rebase, merge, and push have not yet been run.
  • Ask the user to clean the target worktree and reply 继续. When continuing, rerun target resolution, git worktree list , and the target clean state check. Unless new changes appear on the source branch, reuse the existing clean source commit; if there are new changes, commit via git-commit before the rebase.
  • If all target worktrees still have changes when continuing, report the remaining dirty state and pause again without creating a new source commit.

Rebase

  • Before the rebase, use git log --oneline <target-branch>..<source-branch> and git diff --stat <target-branch>...<source-branch> to check the full integration scope.
  • Compare this scope with the current request and the source commits handled by this workflow. If the target was inferred and the scope contains unrelated or unusually broad existing history, stop and ask the user to confirm the target branch. A successful rebase or a no-op does not mean scope validation passed.
  • Run from the source worktree git rebase <target-branch>。
  • When conflicts occur, check git status --short, resolve them semantically, stage only the resolved files, and run git rebase --continue. Stop when encountering product decisions or unsafe conflicts.
  • After the rebase, require the source worktree to be clean, run git diff --check <target-branch>...HEAD; run broader validation only when repository rules or the code involved require it.

Merge and final report

  • Confirm that the source worktree is clean after the rebase.
  • If an existing target worktree was found during the precheck, confirm it is clean and perform the merge from that path.
  • If there is no existing target worktree, create a temporary target worktree outside the repository, for example /tmp/worktree-rebase-merge-<repo>-<target>-<pid>, and run git worktree add <temporary-path> <target-branch>. Before merging, confirm that the temporary worktree is located at <target-branch> and remains clean.
  • Do not switch the user's main checkout just to enter <target-branch> .
  • Do not use git update-ref、git branch -f or other low-level ref commands that bypass the worktree to update the target branch. Use a real target worktree so that Git keeps the branch, index, and files in an understandable state.
  • Run with default Git behavior git merge <source-branch>. Unless the user explicitly requests it, do not force --no-ff, squash, rebase again, or push.
  • When merge conflicts occur, use the same semantic resolution rules as for rebase, then stage only the resolved files and run git merge --continue. If the conflict occurs in a temporary target worktree, keep that worktree and report its path for later resolution; do not delete it.
  • After a successful merge in a temporary target worktree, use git worktree remove <temporary-path> to delete it.
  • Report the source branch, target branch, target checkout path, number of source commits, target merge mode (existing-target-worktree or temporary-target-worktree), the path when the temporary target worktree was created, the merge result, and the final clean state. For an attached checkout, also report the original detached commit, and whether the source branch was created or reused. Unless the user requests a push, state that none was performed.
  • If the integration contains exactly one source commit, finish with that commit's git-commit Post-Commit Report . For created-this-run use 已创建提交; for preexisting-source-commit use 本次未创建新提交；合并的是源分支已有提交。
  • If the integration contains multiple source commits, list each full hash and subject, then use the statistics script's --range <target-commit>...<source-commit> to report totals, code, and documentation text changes. Do not treat any single commit message as the commit message for the entire range.