git-step-commit

Git Step Commit

Organize the current Git changes into clear, reviewable, revertible commits; push only when the user requests it.

Preferences and Priorities

Commit mode is resolved according to the following priorities:

1. The user's most recent explicit specification in the current conversation
2. Current repository configuration
3. Global Git configuration
4. Personalized memory for the current project
5. Built-in default

Message language does not use personalized memory; the priorities remain current conversation, current repository configuration, global Git configuration, built-in default.

Conversation preferences remain in effect for subsequent requests, but are not written to Git configuration; they are overridden when the user specifies anew. They are not carried over only when the user explicitly says "just this once." Do not mistakenly record a one-time confirmation of a plan as a long-term preference.

Configuration keys:

• git-step-commit.mode：default、review、direct
• git-step-commit.language：auto or a valid BCP 47 identifier, such as zh-CN、en、ja

Mode meanings:

• review: first output a review report and wait for confirmation
• direct: commit directly according to the recommended plan
• default: ordinary commits follow review; when the user says "commit as recommended," "commit directly," or "no confirmation needed," follow direct

"Commit and push" itself does not count as the user explicitly specifying a mode, nor does it form a conversation preference; only when the effective mode obtained according to the above priorities is default is this instance executed as direct(recommended mode).

Before each commit, resolve layer by layer according to priority, and stop immediately once a hit is found, without reading lower-priority sources: first use the current conversation preference; otherwise read the current repository configuration; when the repository configuration is missing, read the global configuration; only when both layers of configuration are missing, read personalized memory. Project-level or global default/auto is an explicit value and will prevent further fallback. Invalid configuration is not executed, and the problem and source are reported.

When the user requests to set, view, or delete persistent preferences, only operate on Git configuration, and do not inspect or commit the working tree:

• Current repository:git config --local
• Global:git config --global
• Use --replace-allfor writing, use --unset-all or --remove-section

Before modification, the scope must be known; modify only the field specified by the user, and after completion read back to verify. When reading preferences without a specified scope, display the effective value and its source.

Personalized Memory

Personalized memory is project-level inferred state that the user chooses to enable; it learns only the commit mode direct, and is not written to Git configuration. Use scripts/ to manage the commit-memory-* binary matching the current operating system and CPU architecture; on Linux/macOS, ensure the binary is executable before first run. State is written to ${XDG_STATE_HOME:-$HOME/.local/state}/git-step-commit; if GIT_STEP_COMMIT_STATE_DIRis set, use that directory. Do not manually concatenate, rewrite, or read the state JSON.

Binary correspondences:

• Windows amd64：commit-memory-windows-amd64.exe
• Linux amd64：commit-memory-linux-amd64
• Linux arm64：commit-memory-linux-arm64
• macOS amd64：commit-memory-darwin-amd64
• macOS arm64：commit-memory-darwin-arm64

When the user requests to enable, disable, view, or forget personalized memory, only execute the corresponding script command, and do not inspect or commit the working tree:

<memory-bin> enable
<memory-bin> disable
<memory-bin> status --repo <repo>
<memory-bin> record-direct --repo <repo>
<memory-bin> forget --repo <repo>

Memory is disabled by default.disable retains existing project state but stops reading and learning;forget deletes only the current project's state. When state is missing, disabled, or the threshold has not yet been reached, no mode preference is produced. After the threshold is reached, the mode is direct, and the source is displayed as "personalized memory for this project."

After a commit request ends, run record-directonly when all of the following conditions are met simultaneously, and record at most once per request:

• The user explicitly says "commit as recommended," "commit directly," or "no confirmation needed" in this request
• At least one commit actually succeeds
• The user did not say "only this time"

Do not record confirmation of a review plan, directthat merely continues a prior conversation preference, directobtained from Git configuration, directobtained from the "commit and push" special rule, or failed and unexecuted commits. The script learns directonly after three qualifying successes; after the threshold is reached, record-direct is an idempotent operation with no writes and returns recorded: false. Reuse state already read within the same request; do not read it repeatedly. A write failure does not change the already completed Git result and should be reported separately and accurately.

Analysis and review report

First check the repository root, working tree/staging area, commit history, author history, current branch and upstream, and both levels of configuration in one pass. If there are no changes, state so directly.

Read diffs and untracked files as needed; do not overwrite or casually commit unrelated changes. Divide into batches by a single intent so that each commit can be independently reviewed and rolled back. Reuse verification already done in this round; otherwise run tests proportionate to the risk of the change.

The message language and format follow the user's explicit requirements for this round. When the language is auto , first follow the history of the current Git author; next follow the repository's main history; if there is still no basis, use a concise Conventional Commit, with the summary language following the current conversation. Do not mix languages and formats from different historical levels, and do not guess identity or nationality.

Whenever outputting a review/plan, you must first show the currently effective mode and its source, for example:

当前模式：推荐直提（来源：当前对话）
消息配置：中文 Conventional Commit（来源：作者历史）
验证：<结果或未运行原因>

建议提交：
1. <message>
   - 文件：...
   - 目的：...

If the effective mode is review, wait for user confirmation; if it is direct, the report may be brief and execution continues. When the user only asks for suggestions or review, do not commit regardless of the mode.

Execute commit

When each file as a whole belongs to one batch, stage and commit using precise pathspecs, and multiple batch operations may be placed in a single command chain connected by && . When the same file needs to be split, existing staged content needs to be preserved, or the intent is unclear, inspect batch by batch and use interactive staging or a temporary index. After using git add -p ,git commit must not carry a pathspec or --only, otherwise it will bypass hunk selection and commit the file's complete working tree state.

Before committing, prevent credentials, local caches, editor files, and accidental build artifacts from entering the commit. By default, do not add AI attribution or Co-authored-by。

Only when the user explicitly provides an Issue number, add Closes #123to the relevant commit body; do not guess from the diff or branch name. Do not claim that a local commit has closed an Issue.

Stop and explain when encountering suspected credentials, inability to determine ownership, failure of necessary tests, conflicts, or abnormal hooks. Do not use commands that lose content or rewrite history, and do not amend, force push, or interactively rebase unless the user explicitly requests it.

Sync and push

Push the current branch only when the user explicitly requests a push. For the target, prefer the user-specified value, then the upstream; when there is no upstream, use it only if origin/<当前分支> can be uniquely determined, otherwise ask.

Before pushing a normal branch, check for in-progress Git operations, conflicts, and the working tree. When the user only asks to push, do not automatically stage, commit, or stash uncommitted changes; stop and explain if they prevent safe synchronization. If a remote branch already exists, first git pull --rebase and then a normal git push; if the remote does not yet have a branch with the same name, use git push -u to establish the upstream. If it is still rejected after one retry, stop. Never force push by default.

When a rebase conflict occurs, preserve the scene and inspect the commit being replayed and the semantics of the conflict. Only merge both sides' content, verify, and continue when the intent is clear; otherwise let the user choose. Do not bypass conflicts with abort, hard reset, checkout, or clean.

Result

Report success only based on the command results. List each commit's short hash, message, verification, and remaining uncommitted changes; after pushing, also state the remote, branch, and synchronization result.

If the repository homepage can be reliably derived from the remote address actually used, additionally output a clickable Markdown link, for example 仓库主页：[owner/repo](https://github.com/owner/repo)：

• Remove the trailing .git
• Convert common SSH addresses (such as git@github.com:owner/repo.git) to the corresponding HTTPS homepage
• Never output credentials in the URL
• Omit the link for local paths, when reliable conversion is not possible, or when the source is uncertain

When a commit or push fails, do not print a success link, and do not assume the operation has completed.