Graphite Reviewer is now Diamond

How to merge a Git branch into main

Kenny DuMez
Kenny DuMez
Graphite software engineer
Try Graphite


Note

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


Merging branches allows multiple developers to centralize changes into a single, unified project history. This guide focuses on merging any branch into the main branch, which is typically the stable, production branch in many projects. We'll cover how to merge from both feature branches into main and how to update a feature branch with the latest changes from main.

A merge in Git creates a single commit that brings together the histories of both branches, ideally maintaining the history of both and creating a new point where the combined work continues. This process is crucial for collaborative development and maintaining a coherent project history.

Before merging, make sure your local repository is up to date and ready. This involves several key steps:

Ensure you're on the branch you want to merge into main. If you're not, switch to it using:

Terminal
git checkout <branch-name>

Replace <branch-name> with the name of your branch.

Fetch the latest updates from your remote repository to make sure your local main branch is up to date:

Terminal
git fetch origin

Before merging, ensure your main branch has the latest changes. Switch to the main branch and pull any new changes:

Terminal
git checkout main
git pull origin main

With your main branch updated, you're ready to merge your feature branch:

Terminal
git merge <branch-name>

This command merges <branch-name> into the currently active main branch. If there are no conflicts, Git will automatically create a merge commit.

If there are conflicts during the merge, Git will stop and ask you to resolve them. Conflicts occur when changes in the two branches affect the same part of the same file differently. To resolve conflicts:

  1. Open the conflicting files and make the necessary changes.
  2. After resolving conflicts, add the resolved files to the staging area:
Terminal
git add <resolved-file>
  1. Once all conflicts are resolved and the files are added, complete the merge by creating a merge commit:
Terminal
git commit -m "Merge <branch-name> into main"

For more detailed instructions, see this guide on handling merge conflicts.

The Graphite CLI is designed to streamline Git workflows, especially when dealing with stacked branches. Here's how you can use Graphite to merge branches:

Before merging, synchronize your stack to ensure all branches are up to date:

Terminal
gt sync

This command pulls the latest changes into main, restacks (rebases) all your open pull requests on top of the new changes in main, and prompts you to delete any local merged or closed branches.

Once your stack is synchronized and all pull requests are approved and passing continuous integration (CI) checks, you can merge the stack:

  1. Navigate to the top pull request in your stack:

    Terminal
    gt top
  2. Open the pull request in Graphite's web interface:

    Terminal
    gt pr
  3. In the Graphite web interface, click the "Merge" button to merge the stack.

Graphite will handle the merging process, ensuring that each pull request is merged in the correct order, rebasing as necessary, and waiting for CI checks to pass before proceeding.

After merging, run gt sync again to update your local repository:

Terminal
gt sync

This command will fetch the latest changes, prompt you to delete any merged or closed branches, and rebase any remaining branches onto the newest changes.

  • Always pull the latest changes for main before starting the merge.
  • Regularly merge main into your feature branches to keep them up-to-date and reduce conflicts at the final merge.
  • Use descriptive commit messages to document the purpose of the merge.

Merging branches in Git allows you to combine changes from different development streams. By following the steps outlined above, you can effectively merge any branch into the main branch, ensuring your project's main line of development remains clean and up-to-date.

For further reading, see this guide explaining how Git merges work under the hood.

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

Built for the world's fastest engineering teams, now available for everyone