SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsgit-batch-commit

git-batch-commit

Office & productivity

View repository

Updated 10-15 20:10

About this skill

Git batch commit tool

Overview

Automatically split mixed changes into multiple focused, logically clear commits. Instead of creating a large commit containing "update various files", create multiple clear commits, such as "docs: update README", "chore: update dependencies", "license: update license file".

Responsibility boundaries with git-workflow

git-batch-commit is a commit splitting tool, not a full Git workflow controller.

Scenario Which Skill to use Description
Split staged mixed changes into multiple commits git-batch-commit Core responsibility of this Skill
Determine whether merge / push / close PR is possible git-workflow This Skill does not perform merge gating
Whether the commit title of a PR merged into main includes (#N) git-workflow This Skill only preserves Issue/Task references when generating ordinary commits
Whether directly resolving a GitHub Issue should write Closes #N git-workflow This Skill only writes Refs #N, and does not close the Issue
Project local task reference cross-agent-collab determines the task source,git-batch-commit writes the reference Use --local-ref "project-task Issue #13"

When the user only says "commit these changes / split commits", use this Skill; when the user says "merge PR / pull PR to main / push / close issue", also follow git-workflow。

Privacy pre-check and dependencies

Running the script requires Python 3.10+, Git, PyYAML (if missing, run python3 -m pip install PyYAML), and also install the sibling git-workflow skill at the same time. The shared checker uses only the Python standard library; if missing, fail closed.

Before previewing, confirming, or creating the first commit, check the final complete commit message of all groups (including Markdown heading/list extraction, Issue and local task references), staged change paths, full blobs, and patches.--yes only skips interactive confirmation,--dry-run must also be checked, and neither can skip the privacy gate. If any group fails, do not create any commit, and do not output sensitive original text.

Group-by-group commits use a temporary index of the original staged tree, without unstaging and then re- git add the workspace; unstaged changes in partially staged files will not be mixed in. An existing HEAD is required; if HEAD/index changes during pre-check or execution, stop. Failures during execution retain already successful local commits and do not automatically roll back; before publishing, git-workflow a full-range check is still required.

Case numbers are markers to be verified; public judgments/fictional tests must undergo precise review with a basis, and it is not allowed to ignore an entire directory or use --no-verify to replace review. For rules, local blacklists within the Git directory, precise exceptions, and binary handling restrictions, see shared privacy pre-check。

Use cases

  • The files staged by the user come from multiple categories (documentation + code + configuration)
  • The user wants to maintain a clear, standardized commit history
  • The user mentions "batch commit", "split commit", or "organize commits"
  • The user modified many files and wants to group them logically

Quick start

Method 1: Use the interactive script

# 首先暂存你的文件
git add file1.py file2.md package.json

# 运行交互式批量提交工具（需要确认）
python3 skills/git-batch-commit/scripts/interactive_commit.py

# 或使用 --yes 参数自动确认（适用于非交互式环境）
python3 skills/git-batch-commit/scripts/interactive_commit.py --yes

# 使用 --dry-run 仅查看分组，不实际提交
python3 skills/git-batch-commit/scripts/interactive_commit.py --dry-run

# 这组提交关联 GitHub Issue #13：每个标题追加 (#13)，正文写 Refs #13
python3 skills/git-batch-commit/scripts/interactive_commit.py --issue 13

# 这组提交关联项目本地任务，不误关 GitHub Issue
python3 skills/git-batch-commit/scripts/interactive_commit.py --local-ref "project-task Issue #13"

Command-line arguments：

  • --yes, -y: Skip interactive confirmation and create the commit automatically
  • --dry-run: Only show grouping suggestions, do not actually create a commit
  • --issue N: Associate a GitHub Issue, append to the commit title (#N), and write in the body Refs #N
  • --local-ref "...": Associate a local project task, such as project-task Issue #13, write only Refs: ..., and will not close the GitHub Issue

Method 2: Manual classification

python3 skills/git-batch-commit/scripts/categorize_changes.py
python3 skills/git-batch-commit/scripts/categorize_changes.py --json

Commit classification

Supported types:docs, feat, fix, refactor, style, chore, license, config, test

For the complete definition and detection logic, see references/commit-types.md

Special handling of the skill core file

Important rule：SKILL.md Although it is in Markdown format, it is thecore functionality file of the skill, and should not be classified as docs type.

File type Correct classification Reason
SKILL.md feat/style/fix Skill core file; modifying it is equivalent to modifying functionality/code
AGENTS.md docs Project collaboration specification, belongs to documentation
DECISIONS.md docs Decision record, belongs to documentation
CHANGELOG.md docs Changelog, belongs to documentation
TASKS.md docs Task list, belongs to documentation

Basis for judgment：

  • If what is modified isdefines behavior/functionalityfiles (such as SKILL.md、.py、.ts), treat as code changes
  • If what is modified isrecords/descriptionsfiles (such as README.md、CHANGELOG.md), treat as documentation changes

Merging rules for accompanying changes within the same Skill

Core principle: Functional changes within the same Skill and their directly related accompanying file updates should be merged into one commit, and should not be split by file type.

Specific rules:

  • When SKILL.md has functional changes (feat/fix/style), the CHANGELOG.md updates under the same Skill shouldbe merged into the same commit, and should not be split out into a separate docs commit
  • Similarly, accompanying small changes such as version number changes and minor configuration adjustments (such as deleting .clawhubignore) should also be merged together
  • Judgment criterion: Are these file changes caused bythe same functional change? If yes, they are one commit
  • Only when the CHANGELOG is updated independently (such as backfilling historical versions) and there is no corresponding functional change should the docs type be used separately

Commit message format

All commits follow the format:

<类型>: <标题>

<正文描述>

Important rule: Every commit must include a body and cannot have only a title. The body is used to supplement the specific content and reason for the change, making later tracing easier.

Use an English prefix plus Chinese content to ensure GitHub can recognize it and display colored labels. For a complete example, see references/conventional-commits.md

Multi-Module/Multi-Skill repository rules：

  • The description should include the module name:docs: course-generator 更新 CHANGELOG
  • If one modification involves multiple modules,commits must be made separately by module
  • The module name in the description uses the original English name; do not translate it

Issue / Task reference rules：

  • If a batch of commits is associated with a GitHub Issue, use --issue N. Each commit title will include (#N), and the body will write Refs #N。
  • This Skill does not generate Closes #N. Whether to close a GitHub Issue falls within the judgment scope of git-workflow .
  • If the number comes from a project-local task source rather than a GitHub Issue, use --local-ref "project-task Issue #N" or the project's agreed equivalent reference; do not write Closes #N。
  • The rules for the (#PR编号) of a PR merge commit are not decided by this Skill; follow git-workflow。

Workflow

  1. Stage files - use git add for normal staging
  2. Run interactive script - after all grouping and staging content pre-checks pass, view the classification results
  3. Review - check the proposed commit grouping
  4. Confirm - create the commit or cancel to adjust
  5. ClawHub sync check - execute only when skills/skill-publish-sync/ exists; see references/skill-publish-sync-check.md. Silently skip if it does not exist
  6. Subtree push check - first check whether this skill's config/subtree-repos.yaml has registered the current repository (per-repository customization of config path/prefix/trigger timing/push command; for PR workflow repositories register trigger: after-merge-to-main, and only prompt after merging into main); if not registered, fall back to the default detection skills/subtree-publish/config/subtree-skills.json. If neither matches, silently skip; see references/subtree-push-check.md
  7. Complete - focused commits with a clear history

Required permissions and capability boundaries

The core responsibility of this skill is splitting Git commits, but after a commit is completed the followingoptional follow-up actionsmay be triggered. These actions allexceed the minimal responsibility of "commit only", and they occur only when trigger conditions are met, andmust be explicitly confirmed by the user：

Publish to external platforms (ClawHub / SkillHub)

  • Only when skills/skill-publish-sync/exists in the repository, and this commit involves a version update/new skill under skills/<skill-name>/ , and that skill is in the sync-allowlist.yaml whitelist, will the user be prompted whether to sync.
  • The user is asked to confirm before each publishing action (是否将其加入白名单并同步？, option y/n/s); nothing is executed without confirmation clawhub publish / skillhub publish。
  • Publishing uploads the skill content to the ClawHub/SkillHub platform; before publishing, check that the temporary directory contains no .env, keys, or other sensitive files.
  • After the user chooses to sync, skills/skill-publish-sync/config/sync-allowlist.yaml and sync-records.yamlwill be modified (repository state change).

Push subtree independent repository

  • Trigger detection supports two sources: ① this skill's config/subtree-repos.yaml per-repository registration (config_path custom registration list path,prefix custom subdirectory prefix,trigger custom trigger timing,push_command custom push command); ② unregistered repositories use the default path skills/subtree-publish/config/subtree-skills.json(prompt immediately after commit).
  • trigger: after-merge-to-main(PR workflow repositories, such as dsh-plugins): batch commits occurring on a feature branch do not prompt; prompt only after the PR is merged into main — this prevents dispatching unmerged branch content to an independent mirror.
  • Prompt only when detection hits a registered subdirectory and the corresponding remote is available (default <name>-standalone, the registration list can override per item).
  • The push action requires user confirmation and will not be executed automatically.

Local command execution

  • This skill invokes subprocess through git(staging/commit/viewing diff) and clawhub/skillhub(only after user confirmation) and other external commands. Commands are assembled as argument arrays, without shell string concatenation.

File access

  • Read git diff/git status output,skills/*/SKILL.md frontmatter、skill-publish-sync/config/sync-allowlist.yaml and sync-records.yaml。
  • Modify the above allowlist/records files (only after user confirmation).

If you only want "pure commits, never triggering any publish/push prompts", first remove or rename the skills/skill-publish-sync/、skills/subtree-publish/config/subtree-skills.jsonin the repository, and delete this skill's config/subtree-repos.yaml registration of that repository—these two steps will be silently skipped.

Resource files

scripts/

  • categorize_changes.py - Analyze git diff and group files by category
  • generate_commit_message.py - Generate conventional commit messages
  • interactive_commit.py - Main interactive tool for batch commits

references/

  • commit-types.md - Detailed category definitions and detection logic
  • conventional-commits.md - Commit message conventions
  • skill-publish-sync-check.md - Detailed ClawHub sync check process (workflow step 5)
  • subtree-push-check.md - Detailed Subtree push check process (workflow step 6)