NAME

       git-merge-changelog - git merge driver for GNU ChangeLog files

DESCRIPTION

       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.

       1.  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.

       2.  It respects the structure of ChangeLog files: entries are not split into lines but
           kept together.

       3.  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.

       4.  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.)

   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.

SEE ALSO

       git(1), git-merge(1)

AUTHOR

       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.c.

AVAILABILITY

       git-merge-changelog is part of the GNU gnulib project.

       Gnulib home page: <http://www.gnu.org/software/gnulib/>

COPYRIGHT

       Copyright (C) 2008-2010 Bruno Haible <bruno@clisp.org>

       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 version.

       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/>