# Git History Cleaner

> Git History Cleaner is an Agent Skill for development published in the nixified-ai/flake repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Cleans up git commit history by rebasing and combining commits that edit the same files or logical units, ensuring each logical change is isolated to a single commit.

- Skill name: `git-history-cleaner`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/nixified-ai/flake/blob/HEAD/.agents/skills/git-history-cleaner/SKILL.md
- Repository: nixified-ai/flake (833 GitHub stars when collected)

## SKILL.md

# Git History Cleaner

This skill provides a procedural workflow and strategies for cleaning up git commit history. It details how to reorganize, reorder, and combine (squash or fixup) commits to achieve a clean history where each file, feature, or logical unit is introduced/modified in a single self-contained commit.

## Workflow

1. **Analyze Commit History**:
   - Identify the base commit (e.g., `origin/main`, `master`, or a specific hash where the branch diverged) and the current branch HEAD.
   - View the commit messages in reverse chronological order: `git log <base>..HEAD --oneline`
   - List files modified in each commit: `git log <base>..HEAD --name-status`

2. **Group Changes by Logical Units**:
   - Map files to their logical units (e.g., a specific module, script, library, or config).
   - Identify "fixup" commits (commits fixing errors or formatting in files that were introduced or modified in earlier commits on the branch).
   - Plan the squashing order: each logical unit or file set should be introduced in a single commit, incorporating all subsequent fixes to those same files.

3. **Rebase and Combine Commits**:

   - **Method A: Interactive Rebase (For straightforward rebases)**:
     - Run `git rebase -i <base>`.
     - In the todo list, reorder commits so that any fixup/update commits are positioned immediately below the commit that originally introduced those changes.
     - Change the action of the fixup commits from `pick` to `fixup` (or `f`) to merge them into the parent commit without changing the original commit message, or `squash` (or `s`) to combine their commit messages.

   - **Method B: Programmatic Rebase Script (For complex histories or index files)**:
     - If commits frequently modify shared index files (e.g., JSON registries, lockfiles) that cause heavy conflicts during a standard interactive rebase, write a temporary helper script (Bash or Python) to rebuild the history.
     - Create a temporary branch starting at the base commit: `git checkout -b rebase-temp <base>`
     - For each planned clean commit:
       1. Check out the final state of the relevant files from the target HEAD: `git checkout <target_head> -- <files>`
       2. If a shared index file needs to be built incrementally, extract the specific changes using command-line tools (such as `jq` for JSON files) and apply them.
       3. Commit the staged changes, preserving the original author metadata and dates using environment variables:
          ```bash
          GIT_AUTHOR_DATE="<date>" GIT_COMMITTER_DATE="<date>" git commit -m "<message>"
          ```
       4. Repeat for all logical units in the planned order.

4. **Verify the Rebased History**:
   - Verify that the file state at the new rebased HEAD is identical to the target HEAD:
     ```bash
     git diff <target_head> HEAD
     ```
     *The diff must be completely empty.*
   - Review the final commit history to ensure it contains exactly one logical commit per feature/file group:
     ```bash
     git log <base>..HEAD --oneline
     ```

5. **Update Branch Pointer**:
   - Switch back to the main feature branch and hard-reset it to the rebased HEAD:
     ```bash
     git checkout <feature-branch>
     git reset --hard rebase-temp
     git branch -D rebase-temp
     ```

---

Source: https://www.openparable.com/skill/development/git-history-cleaner (OpenParable). Cite the canonical URL above.
