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 -h

Use the standalone binary for the full long help output:

git-factor --help

For 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 . --force

This installs both:

• git-factor
• git-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
• 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' HEAD

Then:

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 --exec 'just ci' HEAD~2 HEAD

This does not preserve the original seams inside the range. Instead, it:

1. proves the tip of the selected span is green
2. records that tip tree as the target
3. turns the whole span into one remaining pool
4. 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^..HEAD

Restrictions:

• 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' HEAD

Commit the currently staged slice:

git factor --continue --message 'feat: add parser'

Discard the current split attempt and restore the remaining pool:

git factor --retry

Finish by committing the remaining pool:

git factor --finish

Abort the active session and restore the repository:

git factor --abort

Inspect the current session:

git factor --status

The --exec command is your quality gate.

• The start gate must pass before the factor session opens.
• The same gate runs before each --continue commit is created.
• git factor restores the remaining unstaged pool after each successful --continue.
• --finish verifies 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' HEAD

If the start gate fails, fix the target commit first.

Single-commit sessions:

1. fix the files
2. stage the intended changes
3. amend the commit
4. rerun git factor --exec ...

Range sessions:

1. fix the current tip commit
2. stage the intended changes
3. amend the commit
4. run git rebase --continue

If you stage the wrong slice during an active session:

git factor --retry

That 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