Git protip: speed up conflicts management with mergetool

By Maxime Bréhin • Published on 6 February 2023 • 2 min

Whether you’re in the terminal or in your editor, when you have to handle many conflicting files after a merge that went wrong, it can be a pain! You have to open each file one by one, then you have to validate your resolutions by adding the files to the stage. You might as well say that, apart from the fact that you don’t enjoy it, it’s tedious and you might forget to add files to the stage if you’re not careful.

Ideally we’d like these files to be opened one after the other by Git, and once our resolutions are done (file modified, saved and closed), they would be automatically validated / added to the stage.

Guess what? Git does have that feature! It’s the mergetool command. Instead of opening conflicting files yourself, you run this command and Git will open them for you! 🪄

git mergetool
# You can also list specific paths you want to process
# git mergetool file1.txt dir1/ *.js

Before you run off headlong into your terminal with this command, take the time to read on, as there are a few tricks and subtleties.

For starters, you need to define the default tool that you want to use. There is already a list of tools available on your computer and a list of suggested tools to install. To see all this, invoke the command with the --tool-help option:

> git mergetool --tool-help

'git mergetool --tool=<tool>' may be set to one of the following:
                araxis           Use Araxis Merge (requires a graphical session)
                vimdiff          Use Vim with a custom layout (see `git help mergetool`'s `BACKEND SPECIFIC HINTS` section)
                vimdiff1         Use Vim with a 2 panes layout (LOCAL and REMOTE)
                vimdiff2         Use Vim with a 3 panes layout (LOCAL, MERGED and REMOTE)
                vimdiff3         Use Vim where only the MERGED file is shown

        user-defined:
                vscode.cmd code --wait $MERGED

The following tools are valid, but not currently available:
                bc               Use Beyond Compare (requires a graphical session)
                bc3              Use Beyond Compare (requires a graphical session)
                bc4              Use Beyond Compare (requires a graphical session)
                codecompare      Use Code Compare (requires a graphical session)
                …

By default, Git will look at the tools already installed and open the first one it finds. These tools are usually good enough, but you need to know how to use them (or exit them when it comes to vim 😅: ZZ or :q!). If you occasionally want to use one of the listed tools, then you can invoke the command with the --tool option:

git mergetool --tool=araxis

You’ll probably want to define it once and for all as your default tool. This is what Git configuration is for:

git config --global merge.tool araxis

Note that if you want to use an editor that is not in the list, you have to set it up as a custom Git mergetool (what you see above in the user-defined list). This is done with the following command:

# git config --global mergetool.<the-name-you-want>.cmd '<the-command-to-launch-the-tool>'
git config --global mergetool.vscode.cmd 'code --wait $MERGED'
# Then don't forget to set it as the default tool
git config --global merge.tool vscode

That’s it! Next time you have a conflict, you don’t have to go and open your files manually, you just have to run git mergetool.

Want more tips and tricks?

We’ve got a whole bunch of existing articles and more to come. Also check out our 🔥 killer Git training course: 360° Git!