Read Anthropic’s case study about Graphite Reviewer

Using merge tools in Git

Kenny DuMez
Kenny DuMez
Graphite software engineer


Note

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


Merge conflicts are a common challenge in collaborative software development projects. Git, a powerful version control system, provides several tools to help developers resolve these conflicts efficiently. This guide will explore how to use Git merge tools, providing insights into their functionality and practical examples to enhance your workflow.

A Git merge tool is a utility that allows developers to visually address and resolve conflicts that arise during merges. When multiple developers make edits to the same lines of a file or when structural changes overlap, Git requires user intervention to resolve these conflicts manually. Using a graphical or text-based merge tool can simplify this process, allowing developers to choose which changes to keep.

Before you can use a merge tool with Git, you need to configure it. Git supports several popular merge tools out of the box, such as KDiff3, Meld, Beyond Compare, and P4Merge.

  1. Selecting a merge tool:

    • You can check which merge tools are supported on your system by running:
      Terminal
      git mergetool --tool-help
  2. Configuring Git to use a specific merge tool:

    • To set up a merge tool as the default, use the git config command. For example, to set Meld as your default merge tool, you would run:
      Terminal
      git config --global merge.tool meld

When a merge conflict occurs, Git will pause the merging process, allowing you to resolve the conflicts. To launch your configured merge tool, you can use the git mergetool command:

Terminal
git mergetool

This command will open the merge tool interface, where conflicts are highlighted and editable. Each tool may have a slightly different interface, but generally, you will see a three-way comparison:

  • Base: The common ancestor version of the file.
  • Local: Your branch's version of the file.
  • Remote: The version of the file from the branch you are merging.

Let's walk through a common scenario where you are merging changes from a feature branch into the main branch and encounter conflicts.

  1. Start the merge:

    • First, initiate the merge:
      Terminal
      git checkout main
      git merge feature-branch
    • If there are conflicts, Git will list the files that need manual resolution.
  2. Launch the merge tool:

    • Run git mergetool. It will open each conflicted file in the selected merge tool.
    • Navigate through the conflicts. Each tool will allow you to choose between 'local', 'remote', or manually edited content.
  3. Save and exit:

    • Once you resolve all conflicts, save your changes in the merge tool. Git will then apply these resolutions to the files.
    • Close the merge tool, and Git will automatically mark the conflicts as resolved.
  4. Complete the merge:

    • After all conflicts are resolved, continue the merge by committing the changes:
      Terminal
      git commit

Semantic merge conflicts can significantly slow down the development process, especially in active repositories where changes from multiple developers frequently intersect. The Graphite Merge Queue offers a powerful solution to manage these conflicts efficiently by automating the rebase process and ensuring the main branch remains stable and 'green.'

The Graphite merge queue differs from traditional merge tools by providing a more sophisticated handling of stacked pull requests (PRs). It integrates seamlessly with GitHub, enhancing the standard merge process through the following features:

  1. Automated rebasing:

    • When PRs are queued for merging, Graphite automatically rebases them onto the main branch. This step ensures that each PR is tested against the latest version of the main branch before merging, reducing the chances of semantic conflicts that occur when the PRs are out of sync with the main branch.
  2. Batch and parallel processing:

    • Graphite's merge queue is stack-aware, meaning it can process and validate PR stacks in parallel rather than sequentially. This approach not only speeds up the merging process but also minimizes the need for CI re-runs, as the CI has already validated the changes against the exact state of the branch.
  3. Fast-forward merging:

    • An optional feature in Graphite’s merge strategy is the fast-forward merge, which allows stacked PRs to be merged in parallel without waiting for individual CI validations if they've already been validated together. This method is particularly useful for rapid iterations in a development cycle.

Setting up the Graphite merge queue requires enabling it through the Graphite settings for your repository. Once enabled, the queue automatically handles PRs according to the specified merge strategies—either through rebasing or squashing—and integrates these options with GitHub’s branch protection rules to ensure compliance and security.

  • Reduced merge conflicts: By keeping each PR rebased onto the most current state of the main branch, the likelihood of conflicts due to out-of-date branches decreases significantly.
  • Increased development speed: The ability to process PRs in parallel and batch them for merging allows faster integration of changes, keeping the project's momentum.
  • Enhanced stability of the main branch: The automated testing and rebasing ensure that only thoroughly tested and compatible changes are merged, maintaining the stability and reliability of the main branch.

Incorporating Graphite's merge queue into your Git workflow can significantly streamline the process of integrating changes from multiple developers, particularly in fast-paced development environments where reducing downtime and avoiding disruptions is crucial.

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