Use vimdiff to resolve git/subversion/mercurial merge conflicts effectively

The vimdiff as a merge tool will display several buffers to show YOURS/THEIRS/ORIGINAL code.

First, add following code into your ~/.vimrc,

set laststatus=2 "show the status line
set statusline=%-10.3n  "buffer number

The purpose of above two lines is to display buffer number at the status line of vim. It's OPTIONAL. You don't need see the buffer number if you are familiar with the all the buffer's position. The left top is buffer number 2. The middle top is buffer number 3. The right top is buffer number 4.

Second, if you know the buffer number, you can use hot key like ",2" (press comma first, then press two key as quickly as possible) to pull change from buffer number 2. Add below code into your ~/.vimrc to set up hot keys:

map <silent> <leader>2 :diffget 2<CR>
map <silent> <leader>3 :diffget 3<CR>
map <silent> <leader>4 :diffget 4<CR>

Run below commands in shell,

git config --global merge.tool vimdiff
git config --global mergetool.prompt false

I setup a "hello world" project at https://github.com/redguardtoo/test-git-mergetool for your practice.

It has three branches "master", "bob", and "chen",

git clone https://github.com/redguardtoo/test-git-mergetool.git
cd test-git-mergetool
git checkout -b bob origin/bob # create local mirror of bob branch
git checkout -b chen origin/chen # create local mirror of chen branch

Bob and Chen has edited same files. So please merge branch "bob" into "master" at first. Then merge from "chen". The merge conflicts will be created.

git branch # double check that we got three local branches: master, bob, chen
git checkout master # set master branch as main branch
git merge bob #this is ok, because bob is the first one to merge changes
git merge chen # now some conflicts created because Bob has already edited and merged same files

Now start merge tool,

git mergetool

Git will invoke vimdiff with the following window layout. There are four buffers in this layout:

Here is the explanation of each buffer:

Some people name THEIRS and YOURS buffer to LOCAL and REMOTE buffer. That's fine because names are just names. The point is that the top middle buffer is the BASE one which contains the original code before Bob and Chen committing any code. And the bottom buffer is the mess which contains resolved/unresolved conflicts where you actual editing work happens.

You could press hot key ,2, Then you pick the content from THEIRS buffer (the top left buffer). It means you will use the Bob's code and discard Chen's code in MERGED buffer.

You could press hot key ",3", Then you pick the content from BASE buffer (the top middle buffer). It means you will discard either Bob's code or Chen's code in MERGED buffer.

You could press hot key ",4", Then you pick the content from YOURS buffer (the top right buffer). It means you will use Chen's code and discard Bob code in MERGED buffer.

Or you can edit the content directly in MERGED buffer. Anyway, git only care about the file binding to MERGED buffer. Any other buffer will be ignored by git.

You can use hot key [c and ]c to navigate to previous/next conflict (including the conflict resolved by git automatically) in current file which is binding to MERGED buffer.

After finishing editing of the conflicting file in MERGED buffer, you can use hot key :xa to exit vimdiff. Git will open next conflicting file vimdiff automatically.

When you have resolved all the conflicts, follow the hint of git to commit your changes.

Insert below code into ~/.subversion/config:

[helpers]
merge-tool-cmd = vimdiff.sh

Content of vimdiff.sh

#!/bin/sh
#

# Step 1:
# When you get following options during svn merge command, select option 'l'. This is to launch external tool to resolve conflicts.
#
# Conflict discovered in 'main.h'.
# Select: (p) postpone, (df) diff-full, (e) edit,
#        (mc) mine-conflict, (tc) theirs-conflict,
#        (s) show all options: l

# Step 2: Now vim will be opened in diff mode with 3 files - mine, theirs and merged. Make the required changes in the merged file, and do save and exit (:xa).

# Step 3:
# Now below options will appear again, select 'r' (to accept the merged version) now.

BASE=${1}
LOCAL=${2}
REMOTE=${3}
MERGED=${4}
WCPATH=${5}

# copied from from git's vimdiff script
# @see https://github.com/git/git/blob/master/mergetools/vimdiff
vimdiff -f -d -c 'wincmd J' "$MERGED" "$LOCAL" "$BASE" "$REMOTE"