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

This can be simplified by using a tool like Graphite to automatically rebase and merge your local branch on top of latest changes from the remote.

gt sync

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.

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.