How to use 'git mergetool'?

Great question! Using git mergetool can significantly simplify the process of resolving merge conflicts, especially for visual learners or when dealing with complex conflicts. I'm Labby, and I'll explain how to use it.

What is git mergetool?

git mergetool is a command that launches an external merge utility to help you resolve conflicts. Instead of manually editing files with <<<<<<<, =======, and >>>>>>> markers, a graphical merge tool presents the conflicting versions side-by-side (or in a three-way view), allowing you to visually pick and choose which changes to keep.

How to use it:

1. Encounter a Merge Conflict:
   First, you need to have an actual merge conflict. This happens when you run git merge, git pull, or git rebase and Git can't automatically combine changes.
   You'll see output indicating conflicts, and git status will show "Unmerged paths."

   # Example: you're on master and merge a feature branch with conflicts
   git merge feature-branch
   # ... Git reports conflicts ...
   
   git status
   # On branch master
   # You have unmerged paths.
   #   (fix conflicts and run "git commit")
   #   (use "git merge --abort" to abandon latest merge)
   #
   # Unmerged paths:
   #   (use "git add <file>..." to mark resolution)
   #
   #       both modified:      index.html
   #       both modified:      src/app.js
   #
   # no changes added to commit (use "git add" and/or "git commit -a")

2. Launch the Merge Tool:
   Once you have conflicts, simply run:

   git mergetool

3. Git's Merge Tool Behavior:

   • First time: If it's your first time using git mergetool, Git might ask you which merge tool you'd like to use (e.g., vimdiff, kdiff3, meld, Kaleidoscope, p4merge, vscode, opendiff).
     It will list available tools and often suggest one or give you an option to try them out.
   • Default tool: Once configured (or if you already have a tool set), it will launch your preferred merge tool for the first conflicting file.

4. Resolve Conflicts in the Merge Tool:
   The merge tool will open. While each tool looks slightly different, the general layout is usually:

   • Left Pane: Your current branch's version (often labeled LOCAL or <<<<<<< HEAD).
   • Right Pane: The incoming branch's version (often labeled REMOTE or >>>>>>> <branch-name>).
   • Middle/Bottom Pane: The resulting merged file (where you'll make your final choices).

   You'll typically see arrows, checkboxes, or buttons to:

   • "Take A" (keep local changes).
   • "Take B" (keep remote/incoming changes).
   • "Combine Both" (often allows you to manually edit the resulting file).

   Work through the conflicts visually until you're satisfied with the merged result.

5. Save and Exit the Merge Tool:
   After resolving conflicts in a file, save the file within the merge tool and then close the tool for that file. Git will detect that the tool has closed.

6. Repeat for All Conflicting Files:
   git mergetool will automatically move to the next conflicting file. Repeat steps 4 and 5 for all remaining conflicting files.

7. Stage the Resolved Files (Automatically Done by some tools):
   Once you've resolved a file using git mergetool and closed the tool, Git will usually automatically run git add <filename> for that file, marking it as resolved and staged. You can confirm this with git status.

8. Commit the Merge:
   After resolving all conflicts and all conflicted files are staged:

   git commit

   Git will pre-populate a commit message for the merge. Review it, make any necessary adjustments, save, and exit to complete the merge.

Example Configuration for VS Code (a popular option):

If you use VS Code as your editor, you can configure Git to use it as your merge tool:

git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'
git config --global mergetool.vscode.trustExitCode true

After this setup, when you run git mergetool, VS Code will launch with its three-way merge editor.

git mergetool is a powerful helper. It takes a bit of getting used to the specific tool you choose, but it can save you a lot of headache compared to manual text editing for conflicts!