How to merge a Git branch into main

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.

Understanding Git merge

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.

Preparing to merge a branch into main

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

Step 1: Switch to your branch

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

git checkout <branch-name>

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

Step 2: Fetch the latest changes

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

git fetch origin

Step 3: Update your main branch

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

git checkout main
git pull origin main

Step 4: Merge the branch into main

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

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.

Handling merge conflicts

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:

git add <resolved-file>

3. Once all conflicts are resolved and the files are added, complete the merge by creating a merge commit:

git commit -m "Merge <branch-name> into main"

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

Using the Graphite CLI for merging

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:

Step 1: Ensure your stack is synchronized

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

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.

Step 2: Merge the stack

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.

Step 3: Clean up local branches

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

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.

Best practices for a smooth merge

• 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.