AgentSkillsCN

git-hex-branch-cleanup

当用户希望通过 git-hex 清理功能分支的历史记录（如压缩/修正提交、重新排序/删除/拆分提交，或将分支变基至 main 分支），而无需使用交互式终端时，应使用此技能。触发短语包括：“清理我的分支”、“精简历史”、“压缩这些提交”、“修正提交”、“变基至 main”、“重写提交”。

SKILL.md
--- frontmatter
name: git-hex-branch-cleanup
description: >
  This skill should be used when the user wants to clean up a feature branch's
  history using git-hex (squash/fixup commits, reorder/drop/split commits, or
  rebase a branch onto main) without using an interactive terminal. Trigger
  phrases include: "clean up my branch", "polish history", "squash these commits",
  "fixup commits", "rebase onto main", "rewrite commits".

Git-hex Branch Cleanup

When to use this Skill

This skill should be used when:

  • •The user says they want to "clean up", "rewrite", "polish", or "squash" a git history or feature branch.
  • •The user wants to rebase a branch onto another branch (e.g. main) and present a clean, reviewable set of commits.
  • •The user wants to split, squash, or reword commits using git-hex tools instead of manual interactive rebase.

Trigger phrases include: "clean up my commits", "squash fixups", "polish history", "rewrite commits", "rebase onto main", "make this branch reviewable".

Workflow

  1. •

    Plan first

    • •Call git-hex-getRebasePlan to inspect the commit range you would modify.
    • •Optionally call git-hex-checkRebaseConflicts to estimate whether the rebase is likely to conflict.
  2. •

    Prepare changes

    • •For small edits to the last commit, prefer git-hex-amendLastCommit.
    • •For fixes to older commits, guide the user to edit and stage changes, then use git-hex-createFixup targeting the original commit.
    • •For large or mixed commits, consider git-hex-splitCommit to separate files into focused commits.
  3. •

    Apply the rewrite

    • •Use git-hex-rebaseWithPlan to reorder, drop, squash, or reword commits.
    • •Prefer autoStash: true and autosquash: true when the working tree is dirty, following git-hex documentation.
    • •Never use git-hex on shared or protected branches; operate on feature branches the user controls.
  4. •

    Safety and recovery

    • •If the result is not what the user wanted, call git-hex-undoLast to restore the previous state using git-hex backup refs.
    • •If a rebase pauses with conflicts, hand off to the conflict resolution Skill.

Tools to prefer

  • •Planning: git-hex-getRebasePlan, git-hex-checkRebaseConflicts
  • •History rewrite: git-hex-rebaseWithPlan, git-hex-createFixup, git-hex-amendLastCommit, git-hex-splitCommit, git-hex-cherryPickSingle
  • •Recovery: git-hex-undoLast

Key constraints

  • •reword action requires message field (without it, git opens an editor → hang).
  • •Messages must be single-line (no TAB/newline characters).
  • •For reordering commits, set requireComplete: true in the plan.
  • •Prefer fixup over squash unless you need to combine commit messages.
  • •Tools that perform their own auto-stash (amendLastCommit, splitCommit, cherryPickSingle) expose stashNotRestored when stash pop failed; rebaseWithPlan uses Git's native --autostash and does not emit this flag.