For git users:¶

• Add to .git/config of the checkout (or to your $HOME/.gitconfig) the lines

   [merge "merge-changelog"]
       name = GNU-style ChangeLog merge driver
       driver = /usr/bin/git-merge-changelog %O %A %B
      

• In every directory that contains a ChangeLog file, add a file '.gitattributes' with this line:

   ChangeLog    merge=merge-changelog
      

  (See "man 5 gitattributes" for more info.)

For bzr users:¶

• Install the 'extmerge' bzr plug-in listed at <http://doc.bazaar.canonical.com/plugins/en/index.html> <http://wiki.bazaar.canonical.com/BzrPlugins>
• Add to your $HOME/.bazaar/bazaar.conf the line

   external_merge = git-merge-changelog %b %T %o
      

• Then, to merge a conflict in a ChangeLog file, use

   $ bzr extmerge ChangeLog
      

For hg users:¶

-

Add to your $HOME/.hgrc the lines

 [merge-patterns]
    ChangeLog = git-merge-changelog
 [merge-tools]
     git-merge-changelog.executable = /usr/bin/git-merge-changelog
     git-merge-changelog.args = $base $local $other
    

See <http://www.selenic.com/mercurial/hgrc.5.html> section merge-tools for reference.

Use as an alternative to 'diff3':¶

git-merge-changelog performs the same role as "diff3 -m", just with reordered arguments:

 $ git-merge-changelog %O %A %B

is comparable to

 $ diff3 -m %A %O %B

Calling convention:¶

A merge driver is called with three filename arguments:

1.

%O = The common ancestor of %A and %B.

2.

%A = The file's contents from the "current branch".

3.

%B = The file's contents from the "other branch"; this is the contents being merged in.

In case of a "git stash apply" or of an upstream pull (e.g. from a subsystem maintainer to a central maintainer) or of a downstream pull with --rebase:

2.

%A = The file's newest pulled contents; modified by other committers.

3.

%B = The user's newest copy of the file; modified by the user.

In case of a downstream pull (e.g. from a central repository to the user) or of an upstream pull with --rebase:

2.

%A = The user's newest copy of the file; modified by the user.

3.

%B = The file's newest pulled contents; modified by other committers.

It should write its merged output into file %A. It can also echo some remarks to stdout. It should exit with return code 0 if the merge could be resolved cleanly, or with non-zero return code if there were conflicts.

How it works:¶

The structure of a ChangeLog file: It consists of ChangeLog entries. A ChangeLog entry starts at a line following a blank line and that starts with a non-whitespace character, or at the beginning of a file. The merge driver works as follows: It reads the three files into memory and dissects them into ChangeLog entries. It then finds the differences between %O and %B. They are classified as:

• removals (some consecutive entries removed),
• changes (some consecutive entries removed, some consecutive entries added),
• additions (some consecutive entries added).

The driver then attempts to apply the changes to %A. To this effect, it first computes a correspondence between the entries in %O and the entries in %A, using fuzzy string matching to still identify changed entries.

• Removals are applied one by one. If the entry is present in %A, at any position, it is removed. If not, the removal is marked as a conflict.
• Additions at the top of %B are applied at the top of %A.
• Additions between entry x and entry y (y may be the file end) in %B are applied between entry x and entry y in %A (if they still exist and are still consecutive in %A), otherwise the additions are marked as a conflict.
• Changes are categorized into "simple changes":
  entry1 ... entryn are mapped to
  added_entry ... added_entry modified_entry1 ... modified_entryn, where the correspondence between entry_i and modified_entry_i is still clear; and "big changes": these are all the rest. Simple changes at the top of %B are applied by putting the added entries at the top of %A. The changes in simple changes are applied one by one; possibly leading to single-entry conflicts. Big changes are applied en bloc, possibly leading to conflicts spanning multiple entries.
• Conflicts are output at the top of the file and cause an exit status of 1.