Read Anthropic’s case study about Graphite Reviewer

How to rebase main git branch into a feature branch

Greg Foster
Greg Foster
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


Rebasing in Git means transferring the base of one branch onto another. When you rebase the feature branch with the main branch, you're moving the entire feature branch to begin on the tip of the main branch, incorporating all the new commits in the main. This can help resolve conflicts early and makes the history of your project linear and easier to follow.

Join 20,000+ developers at top companies
Stop wrestling with Git commands
The Graphite CLI takes all the pain out of Git, allowing you to ship faster and stop googling Git commands.
main
diff1
diff2

Before rebasing, ensure you have a clean working directory. This means that you don't have any files either untracked by Git (meaning that they exist locally but aren't tracked by Git), or have any uncommitted changes to existing files (meaning that you have changes to files locally but they haven't been added to the staging area, or pushed to the remote repository yet). Check this by running git status. If there are uncommitted changes, either commit them or stash them using git stash.

This command will temporarily stash these files for later use. Once you've rebased successfully and are satisfied with the changes, you can restore these stashed files back to the working directory by running git stash pop.

Now that we have a clean working directory, let's start the rebase.

Purpose The goal here is to ensure that your local main branch is synchronized with the remote main branch. This is important because it ensures that any changes you're integrating into your feature branch are based on the latest version of your project, avoiding conflicts and simplifying the integration of new features.

Commands

Terminal
git checkout main
git pull origin main

git checkout main

  • What it does: This command switches your current working directory to the main branch. It updates your project files to reflect the state of the main branch, setting the stage for you to sync it with the remote repository.
  • Under the hood: The checkout command adjusts the HEAD pointer to point to the main branch and updates the working directory to match the snapshot of the project at the latest commit on that branch.

git pull origin main

  • What it does: This command fetches the latest changes from the main branch of the remote repository (typically called origin) and merges them into your local main branch.
  • Under the hood: git pull is a compound command that first executes git fetch with the given branch (fetching updated data from your remote repository), followed by git merge, which integrates the remote main branch into your local main branch.

Purpose Switching to your feature branch prepares you to rebase it onto the updated main branch. This is where you're developing new features or changes, isolated from the main branch until they're ready.

Commands

Terminal
git checkout feature-branch

git checkout feature-branch

  • What It Does: Moves you from the main branch (or any other branch you might be on) to your feature branch.
  • Under the Hood: Similar to the checkout to main, this changes your working directory and updates the files to reflect the state of feature-branch at its latest commit. It also adjusts the HEAD pointer to reference the feature-branch.
Join 20,000+ developers at top companies
The best engineers use Graphite to simplify Git
Engineers at Vercel, Snowflake & The Browser Company are shipping faster and staying unblocked with Graphite.
main
diff1
diff2

Purpose Rebasing is a powerful tool for maintaining a clean project history. It allows you to take all the changes that were committed on one branch and replay them on another branch.

Commands

Terminal
git rebase main

git rebase main

  • What it does: This repositions the feature-branch to begin at the tip of the main branch. Essentially, it moves the starting point of feature-branch to the end of main, then applies each change made on the feature-branch one by one.
  • Under the hood: git rebase changes the base of your feature branch from its current base to whatever main is now. This operation can be complex if there are conflicting changes between main and feature-branch. Git will pause the rebase and ask you to resolve any conflicts manually. Once all conflicts are resolved and all changes are applied, the feature branch will appear as if it was created based on the current end of the main branch.

During rebase, you may encounter conflicts. Git will stop at the first commit that causes conflict and give you the chance to resolve it. You can identify the files with conflicts using git status.

  • Open the conflicted files and make the necessary changes.

  • After resolving conflicts in a file, add it to the index using:

    Terminal
    git add <filename>
  • Once all conflicts are resolved, continue the rebase process with:

    Terminal
    git rebase --continue

Repeat this process until all conflicts are resolved and the rebase is complete.

  1. If needed, abort the rebase: If you find that the rebase is too complex or not going as planned, you can abort and return your branch to the state it was in before rebasing started:

    Terminal
    git rebase --abort
  2. Push the changes: After the rebase is completed successfully, you'll need to push your changes to the remote feature branch. Since rebase changes the branch's history, you might need to use force push:

    Terminal
    git push origin feature-branch --force

    Caution: Be careful with force pushing, as it can overwrite changes in the remote branch. Ensure that no one else is working on the feature branch or that all team members are aware of the rebase.

  • Simplified history: Rebasing creates a linear project history, which makes it easier to understand changes without the complexities of merge commits.
  • Early conflict detection: By regularly rebasing the main branch into your feature branch, conflicts are detected and resolved sooner rather than later.

For further reading on git rebase see the official Git documentation.

Git inspired
Graphite's CLI and VS Code extension make working with Git effortless.
Learn more

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2