squash-commits

Reorganize the commits on the current branch into a small number of logical commits. Do NOT change any file content — only the commit structure changes.

Instructions

1. Safety check

git status --short

If there are uncommitted changes, stop and tell the user to commit or stash them first.

2. Inspect the branch

git log main..HEAD --oneline
git diff main..HEAD --name-only

List every file changed vs main and every commit on the branch (excluding merge commits from main).

3. Create a backup branch

git branch backup/<current-branch-name>

Tell the user the backup exists so they can recover if needed.

4. Soft-reset to main and unstage everything

git reset --soft main
git restore --staged .

All branch changes are now in the working tree, unstaged. No content has changed.

5. Plan the logical groups

Read the changed files and the original commit messages to understand what the work covers. Group related files into logical commits. Typical groups:

• Core feature or fix (new source files + modified core files)
• Secondary features or fixes (each as its own commit if distinct)
• Refactoring or renames
• Tests
• Changelogs / docs

Use the changelog files (if any) as a strong hint — each changelog entry often maps to one commit.

Present the proposed grouping to the user and ask for confirmation before committing.

6. Commit in logical groups

For each group, stage only the relevant files and commit with a clear message following the project's conventions:

git add <file1> <file2> ...
git commit -m "..."

Use conventional commit prefixes if the project uses them (feat:, fix:, refactor:, test:, chore:).

7. Verify

git log main..HEAD --oneline
git diff main..HEAD --name-only
git status --short

Confirm:

• Commit count is small and each message is meaningful
• The set of changed files vs main is identical to before
• Working tree is clean

8. Remind about force-push

The branch history has been rewritten. Tell the user they will need to git push --force-with-lease when they are ready to update the remote. Do NOT push automatically.

Rules

• Never change file contents. If you find yourself editing a file, stop.
• Never skip the backup branch step.
• Never force-push without explicit user instruction.
• If any step fails or the result looks wrong, tell the user and suggest restoring from the backup: git reset --hard backup/<branch-name>.