git-factor splits one Git commit, or one contiguous commit span, into smaller
atomic commits while proving each emitted commit passes a deterministic gate.
Once installed, use it as a normal Git subcommand:
git factor -hUse the standalone binary for the full long help output:
git-factor --helpFor the agent-oriented workflow and operating rules, see SKILL.md.
git factor helps you:
- prove the current target state passes a gate before splitting starts
- stage one atomic slice at a time
- commit each slice only after the gate passes
- restore the remaining unstaged pool after each successful split
- finish with a final tree that matches the original gated tip tree
This makes it useful for turning a large commit, or a messy patch span, into a series of smaller reviewable commits.
cargo install --path . --forceThis installs both:
git-factorgit-sequence-editor
Make sure Cargo's bin directory is on your PATH:
export PATH="${HOME}/.cargo/bin:${PATH}"Then verify the install:
git factor -h
git-factor --version
git factor --version- Git 2.38 or newer
- Rust and Cargo
- a fully clean repository before
git factor --exec ... - a deterministic validation command for
--exec
The start gate must run on a clean repository and must leave the repository
clean. If git status --porcelain=v1 is not empty, fix that first by
committing, stashing, or removing local changes.
git factor --exec 'just ci' HEADThen:
git add --patch
git factor --continue --message 'feat: extract parser setup'
git add --patch
git factor --continue --message 'refactor: isolate validation'
git factor --finish --message 'feat: restore remaining workflow'git factor --message '…' also submits a staged slice; --continue remains
accepted with a message. Both forms use the same validation and split workflow.
git factor --exec 'just ci' HEAD~2 HEADThis does not preserve the original seams inside the range. Instead, it:
- proves the tip of the selected span is green
- records that tip tree as the target
- turns the whole span into one remaining pool
- lets you emit a new sequence of smaller commits
Documented forms:
<rev>: split one commit<start> <end>: split one inclusive span
Git-native forms also work:
<start>..<end>: exclusive-start range<start>^..<end>: inclusive-start range
Examples:
git factor --exec 'cargo test' HEAD
git factor --exec 'just ci' HEAD~3 HEAD
git factor --exec 'cargo test' HEAD~3..HEAD
git factor --exec 'cargo test' HEAD~3^..HEADRestrictions:
- the selected commits must resolve to one contiguous ancestry span
- merge commits in the span are rejected
- symmetric diff (
...) is not supported
Start:
git factor --exec 'just ci' HEADCommit the currently staged slice:
git factor --continue --message 'feat: add parser'Discard the current split attempt and restore the remaining pool:
git factor --retryFinish by committing the remaining pool:
git factor --finishAbort the active session and restore the repository:
git factor --abortInspect the current session:
git factor --statusThe --exec command is your quality gate.
- The start gate must pass before the factor session opens.
- The same gate runs before each
--continuecommit is created. git factorrestores the remaining unstaged pool after each successful--continue.--finishverifies the final tree matches the recorded gated tip tree.
Use the strictest deterministic gate you have. Typical choices:
git factor --exec 'just ci' HEAD
git factor --exec 'cargo test' HEAD
git factor --exec 'npm test' HEADIf the start gate fails, fix the target commit first.
Single-commit sessions:
- fix the files
- stage the intended changes
- amend the commit
- rerun
git factor --exec ...
Range sessions:
- fix the current tip commit
- stage the intended changes
- amend the commit
- run
git rebase --continue
If you stage the wrong slice during an active session:
git factor --retryThat keeps the session active and restores the remaining pool so you can try again.
- Start with the strictest passing gate.
- Split easy leaf nodes first.
- Prefer coarse splits before fine-grained ones.
- Finish a session once the next split stops being trivial, then factor the new top commit again if needed.
- Keep each commit review-sized and independently valid.
- SKILL.md: agent workflow and detailed operational guidance
git factor --status writes one JSON object followed by a newline. An inactive
session is {"operation":"status","session":null}. An active session exposes
phase, split_count, rebase.in_progress, rebase.required, and
target.commit, target.index, target.span_starts_at_root.
target.index is the zero-based position in the saved selected commit sequence;
target.commit is that position's current commit. The root flag describes the
selected span's original root boundary. Status observes the current session.
git factor --abort reports the existing cleanup result as one JSON object,
followed by a newline. rebase.in_progress is observed after factor state is
removed. When true, actions.abort_rebase contains ["git", "rebase", "--abort"];
otherwise actions is empty. Existing reset, cleanup and external-rebase
behavior is unchanged.
A successful final git factor --continue --message '…' or git factor --finish
reports {"operation":"continue","split_count":N} or the
same object with operation equal to finish, followed by a newline. N is the
existing positive count of commits created for the final selected commit. The
existing completion, cleanup and replay behavior is unchanged.
Only terminal completion results use this JSON form. Non-final --continue
results, start, retry, and failure output retain their existing human-readable
text. Gate output during terminal --continue is forwarded to stderr.
A terminal message-only submission (git factor --message '…') produces the
same completion object with operation equal to continue.