Interactive rebase

Basic Concepts of Interactive Rebase

Interactive Rebase is a powerful feature in Git that allows developers to modify commit history interactively. Unlike regular rebasing, interactive rebase provides finer control, enabling you to reorder commits, merge commits, edit commit messages, or even delete commits. This feature is particularly useful for cleaning up the commit history of a local branch, especially before pushing code to a remote repository.

The core command for interactive rebase is git rebase -i, where the -i flag stands for interactive mode. When this command is executed, Git opens an editor displaying a list of commits to be rebased, each prefixed with a command keyword (e.g., pick, reword, edit, etc.). Developers can modify these keywords to alter the rebase behavior.

Initiating Interactive Rebase

To start an interactive rebase, you need to specify a base point, which determines which commits will be included in the rebase operation. The base point is typically a commit hash or branch name, representing "all commits starting from this point."

# Perform interactive rebase on the last 3 commits
git rebase -i HEAD~3

# Perform interactive rebase on commits after a specific branch (e.g., develop)
git rebase -i develop

After executing the command, Git opens the default editor (usually Vim or another configured editor) with content similar to the following:

pick a1b2c3d Add user login feature
pick e4f5g6h Fix login page styling issue
pick i7j8k9l Optimize user authentication flow

Common Commands in Interactive Rebase

In the interactive rebase editor, the command keyword before each commit determines how Git processes that commit. Here are the commonly used commands:

1. pick (p): Keep the commit unchanged (default action)
2. reword (r): Keep the commit content but modify the commit message
3. edit (e): Keep the commit but pause the rebase process to allow modifying the commit content
4. squash (s): Merge the commit into the previous one, preserving changes from both commits
5. fixup (f): Similar to squash but discards the current commit's log message
6. drop (d): Completely remove the commit
7. exec (x): Execute a shell command

For example, to merge the last two commits into one and modify the message of the first commit:

reword a1b2c3d Add user login feature
squash e4f5g6h Fix login page styling issue
pick i7j8k9l Optimize user authentication flow

Modifying Commit History

One of the most common uses of interactive rebase is cleaning up commit history. Suppose we have the following commits:

* 3a4b5c6 - (HEAD -> feature) Temporary debug code
* 1b2c3d4 - Implement core functionality
* a1b2c3d - Initialize project

The "Temporary debug code" commit should not appear in the final history, while the "Implement core functionality" commit message needs more detail. Here's how to do it:

git rebase -i HEAD~2

In the editor, modify the content to:

edit 1b2c3d4 Implement core functionality
drop 3a4b5c6 Temporary debug code

After saving and exiting, Git pauses at the 1b2c3d4 commit, allowing modifications:

# After modifying files
git add .
git commit --amend -m "Implement core logic for user authentication module\n\n- Add JWT token generation\n- Implement permission validation middleware\n- Improve error handling"
git rebase --continue

Merging Multiple Commits

During development, we often make multiple small commits that we later want to merge into a single logical commit. For example:

* 5d6e7f8 - Fix test failures
* 4c5d6e7 - Fix typos
* 3b4c5d6 - Add user model tests
* 2a3b4c5 - Implement user deletion feature
* 1a2b3c4 - Implement user update feature

To merge the last three commits into one "User management feature" commit:

git rebase -i HEAD~5

Modify the content to:

pick 1a2b3c4 Implement user update feature
squash 2a3b4c5 Implement user deletion feature
squash 3b4c5d6 Add user model tests
pick 4c5d6e7 Fix typos
pick 5d6e7f8 Fix test failures

After saving, Git opens another editor for editing the merged commit message.

Splitting Commits

Sometimes, we need to split a large commit into smaller ones. This requires the edit command:

1. In the interactive rebase editor, mark the commit to be split as edit.
2. Git pauses at that commit. Use git reset HEAD~ to reset to the state before the commit.
3. Stage files incrementally and create new commits.

For example, to split a large "Implement user system" commit:

git rebase -i HEAD~3

After marking the target commit as edit:

git reset HEAD~
git add src/models/user.js
git commit -m "Create user model"
git add src/controllers/userController.js
git commit -m "Implement user controller"
git add test/user.test.js
git commit -m "Add user tests"
git rebase --continue

Handling Rebase Conflicts

Conflicts may arise during interactive rebase. When a conflict occurs, Git pauses the rebase process and prompts you to resolve it. Steps to resolve:

1. Edit the conflicting files (Git marks conflicts with <<<<<<<, =======, and >>>>>>>).
2. Use git add to mark the conflict as resolved.
3. Continue the rebase process.

# After encountering a conflict
# Manually resolve conflicts in the files
git add conflicted-file.js
git rebase --continue

# If resolution is impossible, abort the rebase
git rebase --abort

Advanced Usage of Interactive Rebase

Modifying Multiple Commit Messages

To modify messages for a series of commits, use the reword command:

reword a1b2c3d Old message 1
reword b2c3d4e Old message 2
reword c3d4e5f Old message 3

Git will sequentially open an editor for you to modify each commit message.

Reordering Commits

Simply reorder the commit lines in the interactive rebase editor to change the commit sequence:

pick c3d4e5f Third feature
pick a1b2c3d First feature
pick b2c3d4e Second feature

Using exec to Run Commands

You can automatically run commands during rebase, such as running tests after each commit:

pick a1b2c3d First feature
exec npm test
pick b2c3d4e Second feature
exec npm test

If a test fails, the rebase pauses, allowing you to fix the issue before continuing with git rebase --continue.

Best Practices for Interactive Rebase

1. Use only on local branches: Avoid rebasing commits already pushed to a remote repository unless you're certain no one else is working on them.
2. Backup branches: Before major rebase operations, create a backup branch: git branch backup/feature-branch.
3. Small steps: Don't rebase too many commits at once; aim for 5-10 commits per operation.
4. Understand workflow: Team members should agree on rebase usage to avoid history confusion.
5. Clean test commits: Use rebase to clean up debug or WIP commits before merging into the main branch.

Interactive Rebase and Team Collaboration

When using interactive rebase in a team environment, pay special attention to:

• Avoid rebasing if the branch has already been pulled by others.
• Use git push --force-with-lease (safer than --force) when pushing rebased branches.
• Consider using git merge --no-ff to preserve feature branch history instead of rebasing.

For example, to clean up commits before merging a feature branch into develop:

git checkout feature/auth
git fetch origin
git rebase -i origin/develop
# Resolve any conflicts
git push --force-with-lease origin feature/auth

Graphical Tools for Interactive Rebase

While the command line is powerful, some developers prefer graphical interfaces. Many Git clients support interactive rebase:

• GitKraken: Right-click a commit and select "Interactive Rebase."
• SourceTree: Access via the "Actions" menu.
• VS Code Git Plugin: Offers partial interactive rebase functionality.

Graphical tools often provide a more intuitive way to select commits and apply commands, but understanding the underlying commands remains important.

Common Issues and Solutions

Issue 1: Lost commits after rebase

• Solution: Use git reflog to find the lost commit hash, then git cherry-pick or create a new branch.

Issue 2: Complex conflicts during rebase

• Solution: Consider git rebase --abort and use git merge instead, or perform smaller rebases incrementally.

Issue 3: Accidental operations leading to messy history

• Solution: If a backup branch exists, switch back to it; otherwise, recover from reflog.

Issue 4: Test failures after rebase

• Solution: Use git bisect to locate the problematic commit, fix it, and use git commit --amend.

Workflow Example for Interactive Rebase

Suppose we're developing a React application with a feature branch feature/todo-list:

1. First, check the commit history:

git log --oneline -5
# Output:
# e1f2g3h (HEAD -> feature/todo-list) Temporary console.log
# d4e5f6g Add TodoItem component tests
# c3d4e5f Implement TodoItem component
# b2c3d4e Implement TodoList component
# a1b2c3d Initialize Todo feature module

2. Perform interactive rebase to clean up:

git rebase -i HEAD~5

Edit the content to:

reword a1b2c3d Initialize Todo feature module
pick b2c3d4e Implement TodoList component
pick c3d4e5f Implement TodoItem component
squash d4e5f6g Add TodoItem component tests
drop e1f2g3h Temporary console.log

3. Modify the initial commit message to: "feat: Initialize Todo module\n\n- Create basic file structure\n- Add Redux store configuration."

4. When merging the component implementation and test commits, edit the merged message: "feat: Implement Todo list and item components\n\n- Create interactive TodoList component\n- Implement TodoItem display and interaction\n- Add component unit tests."

5. The result is a clean commit history ready to merge into the main branch.