gfix
- Repo stars 2,380
- License MIT
- Author repo dotfiles
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @ryanb · MIT
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# gfix — Amend a Past Commit
Use the `gfix` shell command to fold staged changes into a commit that is not the most recent. This is the preferred way to amend historical commits in this repo.
## How gfix works
Source: `~/code/dotfiles/plugins/git.zsh` (the `gfix` function)
`gfix [-m <message>] <commit-sha>` does the following:
1. Guards against running during an in-progress git operation (rebase, merge, cherry-pick, etc.)
2. Stashes any unstaged changes (preserving the index)
3. Creates a fixup commit from whatever is currently staged:
- With no `-m`: `git commit --fixup <commit-sha>` (content-only fixup)
- With `-m <message>`: creates a manual `amend!` commit with subject `amend! <original-subject>` and body `<message>`, which autosquash then folds into the target (replacing its message, and including any staged changes; `--allow-empty` is used if nothing is staged)
4. Runs `GIT_SEQUENCE_EDITOR=true git rebase -i --autosquash <commit-sha>^` to automatically squash the fixup into the target commit
5. Restores any stashed unstaged changes
## When to use gfix
Use gfix when you need to amend a commit that is **not** the HEAD commit. For example:
- A review comment asks for a change to code introduced 3 commits ago
- You notice a typo or bug in an earlier commit while working on something else
- You want to keep a clean, logical commit history where each commit is self-contained
If you only need to amend the most recent commit, use `git commit --amend` instead.
## Steps
1. **Determine the safe range** — The target commit must be within the current branch's own commits, not on or before the base branch. Use `detect_base_branch` to find the base branch. As a last resort, ask the user.
The target commit **must** appear in `git log --oneline <base-branch>..HEAD`. If it does not, **stop and tell the user** — rewriting shared history would cause problems.
2. **Identify the target commit** — Use `$ARGUMENTS` to understand what the user wants fixed. List the safe commits with `git log --oneline <base-branch>..HEAD` and examine their diffs to find the commit that introduced the code the user wants changed.
3. **Make and stage the changes** — Edit the files, then `git add` only the files that belong to the target commit.
4. **Run gfix** — Pass the target commit SHA. Add `-m <message>` to also rewrite the target commit's message:
```bash
gfix <commit-sha>
gfix -m "new commit message" <commit-sha>
```
5. **Handle rebase conflicts** — If the rebase hits conflicts:
- Read the conflicting files and resolve them
- `git add` the resolved files
- `git rebase --continue`
- Repeat until the rebase finishes
6. **Verify** — Run `git log --oneline -10` to confirm the history looks correct. If relevant tests exist, run them.
Sections and files
Listed in source order.
sections -> How gfix works → When to use gfix → Steps
terms -> not · Determine the safe range · must · stop and tell the user · Identify the target commit · Make and stage the changes · Run gfix · Handle rebase conflicts
files/cmd -> gfix · ~/code/dotfiles/plugins/git.zsh · gfix [-m <message>] <commit-sha> · git commit --fixup <commit-sha> · -m <message> · amend! · amend! <original-subject> · <message>
body sha256 -> 61a1eecc2a41
How gfix works
Source:
~/code/dotfiles/plugins/git.zsh(thegfixfunction)gfix [-m <message>] <commit-sha>does the following: Guards against running during an in-progress git operation (rebase, merge, cherry-pick, etc.) Stashes any unstaged changes (preserving the index) Creates a fixup commit from whatever is currently staged:When to use gfix
Use gfix when you need to amend a commit that is not the HEAD commit. For example: A review comment asks for a change to code introduced 3 commits ago You notice a typo or bug in an earlier commit while working on something else You want to keep a clean, logical commit history where each commit is self-contained If you only need to amend the most recent commit, use
git commit --amendinstead.Steps
Determine the safe range — The target commit must be within the current branch's own commits, not on or before the base branch. Use
detect_base_branchto find the base branch. As a last resort, ask the user. The target commit must appear ingit log --oneline <base-branch>..HEAD. If it does not, stop and tell the user — rewriting shared history would cause problems. Identify the target commit — Use$ARGUMENTSto understand what the user wants fixed. List the safe commits withgit log --oneline <base-branch>..HEADand examine their diffs to find the commit that introduced the code the user wants changed.