git-merge-changelog - git merge driver for GNU ChangeLog files
The default merge driver of 'git' always
produces conflicts when pulling
public modifications into a privately modified ChangeLog file. This is because
ChangeLog files are always modified at the top; the default merge driver has
no clue how to deal with this. Furthermore the conflicts are presented with
more <<<< ==== >>>> markers than necessary; this is
because the default merge driver makes pointless efforts to look at the
individual line changes inside a ChangeLog entry.
This program serves as a 'git' merge driver that avoids these problems.
- It produces no conflict when ChangeLog entries have been
inserted at the top both in the public and in the private modification. It
puts the privately added entries above the publicly added entries.
- It respects the structure of ChangeLog files: entries are
not split into lines but kept together.
- It also handles the case of small modifications of past
ChangeLog entries, or of removed ChangeLog entries: they are merged as one
would expect it.
- Conflicts are presented at the top of the file, rather than
where they occurred, so that the user will see them immediately. (Unlike
for source code written in some programming language, conflict markers
that are located several hundreds lines from the top will not cause any
syntax error and therefore would be likely to remain unnoticed.)
- Add to .git/config of the checkout (or to your
$HOME/.gitconfig) the lines
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:
(See "man 5 gitattributes" for more info.)
- Install the 'extmerge' bzr plug-in listed at
- 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
- Add to your $HOME/.hgrc the lines
ChangeLog = git-merge-changelog
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.
git-merge-changelog performs the same role as "diff3 -m", just with
$ git-merge-changelog %O %A %B
is comparable to
$ diff3 -m %A %O %B
A merge driver is called with three filename arguments:
- %O = The common ancestor of %A and %B.
- %A = The file's contents from the "current
- %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
- %A = The file's newest pulled contents; modified by other
- %B = The user's newest copy of the file; modified by the
In case of a downstream pull (e.g. from a central repository to the user) or of
an upstream pull with --rebase:
- %A = The user's newest copy of the file; modified by the
- %B = The file's newest pulled contents; modified by other
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.
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
- removals (some consecutive entries removed),
- changes (some consecutive entries removed, some consecutive
- 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
- Additions at the top of %B are applied at the top of
- 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.
The git-merge-changelog author and maintainer is Bruno Haible.
This man page was adapted by Ian Beckwith from the comments at the top of
git-merge-changelog is part of the GNU gnulib project.
Gnulib home page: <http://www.gnu.org/software/gnulib/>
Copyright (C) 2008-2010 Bruno Haible <email@example.com>
This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
this program. If not, see <http://www.gnu.org/licenses/>