split-commit

Git 拆分提交

作者：Bruno Balderrama ([email protected])。经作者许可，收录于此合集。

目标：将当前本地更改拆分为多个逻辑提交，并生成一个由用户自行运行的 PowerShell 脚本。

约束（必须遵守）

• 不要替用户运行 git add、git commit 或 git push。只能运行下方的只读检查命令（以及你需要的其他不修改仓库的 git 查询命令）。
• 不要代替用户暂存、提交或推送。
• 最终回复只能包含一个代码块：一段可直接复制粘贴的 PowerShell 命令序列（注释 + 命令）。

第 1 步——检查（仓库根目录）

在仓库根目录运行以下命令，并根据输出进行分组和确定提交消息风格：

git branch --show-current
git status --short
git log -12 --oneline
git diff

如果更改较多，也可以使用 git diff --stat 或按路径限制的 git diff -- path 来分析批次；仍然不得运行 git add / git commit / git push。

提交消息——.githooks/commit-msg（必须遵守）

权威依据： .githooks/commit-msg。每条拟议的 git commit -m 都必须通过当前分支（由 git branch --show-current 获取）上的该钩子。

分支	允许的首行（非空，去除首尾空白后）
main	合并风格的行（Merge branch…、Merge remote-tracking branch…、Merge commit…、Merge pull request…）或 hotfix(scope): 主题
develop	仅限合并风格的行（同上）。develop 上不允许使用 feat: / fix: 等格式
其他	Conventional Commits：type(scope): subject 或 type: subject——冒号后有空格；主题不能为空；类型：feat、fix、hotfix、chore、test、docs、style、ci；首行不超过 120 个字符

如果用户在 develop 分支上且需要多个提交，必须明确告知用户应使用功能分支（或接受使用 --no-verify，但不推荐）。除非提交消息符合合并格式，否则不要为 develop 输出 Conventional Commits 格式的 git commit -m 行。

使用 Conventional Commits 时，仍须使用祈使语气，并与 git log -12 --oneline 的风格保持一致。

第 2 步——规划批次

1. 将更改路径分组为逻辑提交（按功能、修复、文档、测试、杂项，或按子系统分组）。
2. 起草符合当前分支 .githooks/commit-msg 要求的提交消息（见上表）。

第 3 步——输出 PowerShell 命令序列

钩子合规性（仅限 Agent 侧）：阅读 .githooks/commit-msg 和上方的提交消息表格。输出的每条 git commit -m "…" 命令都必须符合当前分支上的钩子要求（功能分支允许的类型仅限：feat、fix、hotfix、chore、test、docs、style、ci——例如，refactor 会被拒绝）。不要输出辅助函数、临时文件或 Assert-*；用户会通过正常运行提交命令进行验证。

输出格式（始终使用此布局）：

• 假设用户已经位于仓库根目录。
• 开头几行：先写清理工作区的注释，然后写 git reset HEAD（如果仓库尚无提交，则省略 git reset HEAD，并在注释中说明）。
• 对于每个批次，按顺序：
  • 一条注释：# <n>) <简短标题>（n 递增）。
  • 该批次中的每个文件分别写一条 git add "path"（路径加引号；每行一条 git add）。
  • git commit -m "准确的首行"——使用字面的双引号字符串；采用祈使语气；格式为 type(scope): subject 或 type: subject；不超过 120 个字符。
• 所有批次结束后，始终以以下内容结尾：

git status --short
git log -12 --oneline

示例结构（结构必须匹配；根据钩子使用 feat / fix / chore / …，不要使用 refactor）：

# Start clean (omit if repo has no commits yet)
git reset HEAD
# 1) Shared route URL helper
git add "src/lib/navigation/route-params.ts"
git commit -m "chore(lib): add replaceRouteSearchParams for list route queries"
# 2) System components: single pattern for updating search params
git add "src/components/system/search/index.tsx"
git add "src/components/system/search/ui.tsx"
git add "src/components/system/filters/dropdown/index.tsx"
git add "src/components/system/filters/search-button/index.tsx"
git add "src/components/system/sorts/dropdown/index.tsx"
git commit -m "chore(system): use shared route param updates in search and filters"
# 3) Header + client list-filter hooks (param naming)
git add "src/components/layouts/header/index.tsx"
git add "src/components/layouts/header/hooks/use-list-filters.tsx"
git add "src/components/layouts/header/hooks/use-assistants-filters.tsx"
git commit -m "chore(layouts): align list header and filter hooks with route param names"
# 4) Spaces list: URL-driven filters, parse-url, tests
git add "src/lib/spaces/parse-url.ts"
git add "src/app/(authenticated)/spaces/hooks/filters.tsx"
git add "src/app/(authenticated)/spaces/partials/list.tsx"
git add "__tests__/spaces-list-filters.test.tsx"
git commit -m "chore(spaces): route-based list filters and simplify URL parse"
git status --short
git log -12 --oneline

助手的最终回复除了这一个 PowerShell 代码块外，不应包含任何其他内容（如有必要，可选一行引言；最好只输出代码块）。

边缘情况

• 没有变更：生成一个最简脚本，仅运行 git status --short 和 git log -12 --oneline，并添加一条注释说明没有内容需要拆分。
• 未跟踪的文件：在合适的批次中加入 git add "path"，且仅在由用户运行的脚本中加入（你仍然不能自行运行 git add）。
• 单个逻辑提交：一个批次即可；仍须遵循相同的脚本结构。