Introduction

Git 2.54 brings a fresh experimental command, git history, designed for making focused, non-interactive changes to your repository's past. Unlike the full-featured but sometimes overwhelming git rebase -i, git history lets you fix a typo in an old commit message or split a single commit into two without touching your working tree or index. This guide will walk you through everything you need to get started with git history reword and git history split—the two operations currently supported.

What You Need

• Git 2.54 or later – This command is experimental in this release. Upgrade from earlier versions if necessary.
• A Git repository – Can be a bare repository (no working tree) or a regular one. The command works in both.
• Commit history without merge commits – git history refuses to operate on merge commits or histories containing them.
• No existing merge conflicts – The tool will reject any operation that could cause a conflict.
• Basic command-line familiarity – Comfort with terminal/Git commands is assumed.

Step-by-Step Guide

Step 1: Verify Your Git Version

First, confirm you have Git 2.54 or newer installed. Open your terminal and run:

git --version

If the output shows a version lower than 2.54, update Git using your system's package manager or download the latest from git-scm.com.

Step 2: Understand the git history Command

The command is built on the git replay machinery, which has been extracted into a library for this purpose. It is not a replacement for interactive rebase; rather, it fills a gap for simple, targeted edits that don’t require the full rebase workflow. Key points:

• Reword: Change a commit message without touching your working tree or index.
• Split: Divide one commit into two by selecting which hunks go into the new parent commit.
• Limitations: No merge commits, no conflict handling, and no open-ended editing.

Step 3: Rewriting a Commit Message with git history reword

Suppose you need to fix a typo in a commit from three steps back (e.g., commit abc123). With git rebase -i you’d mark that commit for editing, then amend and continue. With git history reword, it’s much simpler:

1. Run the command with the target commit reference:
   git history reword abc123
2. Your default text editor will open with the current commit message. Make your changes and save.
3. Git automatically rewrites the commit and updates all descendant branches (if any) to point to the new version. No need to touch your working directory or index.

This operation works even in a bare repository, making it ideal for server-side scripts or CI pipelines.

Step 4: Splitting a Commit into Two with git history split

Sometimes a single commit contains unrelated changes that should be separated. The split subcommand lets you interactively choose which hunks (diff chunks) to move into a new parent commit. Here’s how:

1. Identify the commit you want to split (e.g., HEAD) and run:
   git history split HEAD
2. Git will present each hunk from the commit’s diff, one by one, asking whether to include it in the new parent commit. The prompt looks like:
   (1/1) Stage addition [y,n,q,a,d,p,?]?
3. Answer y to move the hunk into a new commit that will become the parent of the original commit. Answer n to keep it in the original commit.
4. After you’ve made selections, Git creates a new commit containing the chosen hunks. The original commit retains the remaining hunks. All branches that descend from the original commit are automatically rewritten to point to the updated history (new parent + original commit).

Note that the interface is familiar if you’ve ever used git add -p (interactive staging). The same options apply: y for yes, n for no, q to quit, a for all, d for none, etc.

Step 5: Verify the Rewritten History

After using either reword or split, check your history with:

git log --oneline --graph

For a split, you’ll see two commits in place of one. For a reword, the commit message will reflect your changes. The command updates all branch references, so git log --all will show the new structure.

Step 6: Recover If Something Goes Wrong

Because git history rewrites history, it’s wise to have a backup. If you haven’t pushed the changes yet, use git reflog to find the original state and reset:

git reflog
# find the commit before the rewrite
git reset --hard HEAD@{1}

If you’ve already pushed, coordinate with your team and force-push with care.

Tips and Best Practices

• Use git history for simple, targeted edits only. For complex rewrites (reordering, squashing, dropping, or editing multiple commits), stick with git rebase -i.
• Avoid merge commits in the range you rewrite. The command explicitly refuses to handle merge commits. If your history has merges, consider rebasing them away first.
• Test on a clone or backup. Since git history is experimental, make a copy of your repository before using it on critical work.
• Remember that rewriting published history affects collaborators. Force-pushing rewritten branches requires team coordination.
• Leverage the bare repository capability. You can use git history reword on a bare clone, which is great for server-side scripts or CI jobs that need to update commit messages automatically.
• Combine with git diff before splitting. Review the commit’s changes with git show <commit> to decide how you want to divide the hunks.

With git history, Git 2.54 offers a more surgical approach to history rewriting. Start using it for quick fixes and watch your productivity improve.