Git Rebase to Manage History Meaningfully

Introduction

Developers often neglect the importance of maintaining meaningful git history, resulting in messy commit history that makes it difficult to follow how a project evolved. If you're not taking git history seriously, this is essential reading on best practices for managing it. If you do take it seriously, this article provides an opportunity to validate whether you're following best practices in your current projects.

Typical Development Workflow

In routine development work, it is recommended to work in feature branches forked from master/production to keep the main branch unaffected by ongoing development. Production releases are made from the main branch, so unfinished work should not be merged into it.

Multiple Developers on Same Branch

When multiple developers work on the same feature branch, the branch tends to accumulate various types of commits:

Work in Progress Commits:

• "bug fix", "more work", "minor changes", "formatted code"
• "incorporated review comments"
• "Fixed JIRA-5934"
• Long commit messages with 100+ words and excessive characters

Ugly Merge Commits:

• "Merge branch '' of "

These commits are acceptable in feature branches as they aid tracking and development. However, once merged to master, they clutter the master branch history and make it difficult to follow the project's evolution.

Solution: Git Rebase Strategies

Scenario 1: Local Feature Branch Behind Remote

Situation: Other developers have pushed commits while your local commits remain unpushed. Local branch is behind its remote version.

Before Pull: Your local commits (c2, c3) haven't been pushed yet.

Standard Approach (Creates Merge Commit):

git pull

This creates a merge commit when new commits from remote are integrated.

Recommended Approach:

git pull --rebase

This pulls new commits from remote and applies your local commits on top without creating a merge commit. The result is a clean, linear history with commits in correct order.

Scenario 2: Diverged Work Between Master and Feature Branches

Situation: You've made commits on both master and feature branches. Other developers have added commits or merged other feature branches to master.

Standard Approach (Creates Merge Commit):

git merge master

This creates an additional merge commit when integrating master into your feature branch.

Recommended Approach - Alternative 1:

git rebase master

This makes the feature branch hang off the latest master commit, ensuring all master commits are pulled first. Then your feature branch commits are applied on top without a merge commit.

Recommended Approach - Alternative 2:

git rebase -i master

Interactive rebase allows you to pick commits and squash/fixup unwanted commits. Use this when your feature is reviewed and approved for merging into production, ensuring only meaningful commits are in history.

Scenario 3: Merging Approved Feature Branch into Master

Situation: Feature branch changes are approved and need to be merged into master.

Recommended Steps:

1. Check out master
2. Execute the squash merge:

   git merge --squash origin/demo-feature

   (Or if the feature branch is local and not yet pushed to remote:)

   git merge --squash feature

3. Commit with a meaningful message:

   git commit -m "My custom commit message for feature"

4. All changes are reflected in local master branch

This approach results in a professional commit history similar to well-known open source projects, with meaningful, well-organized commits representing logical units of work.

Best Practices Summary

• Use feature branches for ongoing development
• Use git pull --rebase when pulling updates to avoid merge commits
• Use git rebase master to keep feature branches up-to-date with master
• Use git rebase -i master to clean up commits before merging to master
• Use git merge --squash when merging approved features to keep master history clean
• Keep commit messages clear and meaningful
• Avoid mixing "work in progress" commits with final code in master

Conclusion

Managing meaningful git history is a sign of professional development practices. The strategies outlined enable teams to maintain clean, readable commit histories that clearly tell the story of how a project evolved. Test these approaches on a test repository and refine your workflow based on your team's needs.