--- /dev/null
+=head1 NAME
+
+git-merge-changelog - git merge driver for GNU ChangeLog files
+
+=head1 DESCRIPTION
+
+The default merge driver of 'git' B<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 E<lt>E<lt>E<lt>E<lt> ==== E<gt>E<gt>E<gt>E<gt> 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.
+
+=over 4
+
+=item Z<>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.
+
+=item Z<>2.
+
+It respects the structure of ChangeLog files: entries are not split
+into lines but kept together.
+
+=item Z<>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.
+
+=item Z<>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.)
+
+=back
+
+=head2 For git users:
+
+=over 4
+
+=item -
+
+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
+
+=item -
+
+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.)
+
+=back
+
+=head2 For bzr users:
+
+=over 4
+
+=item -
+
+Install the 'extmerge' bzr plug-in listed at
+L<http://doc.bazaar.canonical.com/plugins/en/index.html>
+L<http://wiki.bazaar.canonical.com/BzrPlugins>
+
+=item -
+
+Add to your $HOME/.bazaar/bazaar.conf the line
+
+ external_merge = git-merge-changelog %b %T %o
+
+=item -
+
+Then, to merge a conflict in a ChangeLog file, use
+
+ $ bzr extmerge ChangeLog
+
+=back
+
+=head2 For hg users:
+
+=over 4
+
+=item -
+
+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 L<http://www.selenic.com/mercurial/hgrc.5.html> section B<merge-tools>
+for reference.
+
+=back
+
+=head2 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
+
+=head2 Calling convention:
+
+A merge driver is called with three filename arguments:
+
+=over 4
+
+=item Z<>1.
+
+%O = The common ancestor of %A and %B.
+
+=item Z<>2.
+
+%A = The file's contents from the "current branch".
+
+=item Z<>3.
+
+%B = The file's contents from the "other branch"; this is the contents
+being merged in.
+
+=back
+
+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:
+
+=over 4
+
+=item Z<>2.
+
+%A = The file's newest pulled contents; modified by other committers.
+
+=item Z<>3.
+
+%B = The user's newest copy of the file; modified by the user.
+
+=back
+
+In case of a downstream pull (e.g. from a central repository to the user)
+or of an upstream pull with --rebase:
+
+=over 4
+
+=item Z<>2.
+
+%A = The user's newest copy of the file; modified by the user.
+
+=item Z<>3.
+
+%B = The file's newest pulled contents; modified by other committers.
+
+=back
+
+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.
+
+=head2 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:
+
+=over 4
+
+=item -
+
+removals (some consecutive entries removed),
+
+=item -
+
+changes (some consecutive entries removed, some consecutive entries added),
+
+=item -
+
+additions (some consecutive entries added).
+
+=back
+
+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.
+
+=over 4
+
+=item -
+
+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.
+
+=item -
+
+Additions at the top of %B are applied at the top of %A.
+
+=item -
+
+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.
+
+=item -
+
+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.
+
+=item -
+
+Conflicts are output at the top of the file and cause an exit status of 1.
+
+=back
+
+=head1 SEE ALSO
+
+git(1), git-merge(1)
+
+=head1 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.
+
+=head1 AVAILABILITY
+
+git-merge-changelog is part of the GNU gnulib project.
+
+Gnulib home page: L<http://www.gnu.org/software/gnulib/>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2008-2010 Bruno Haible E<lt>bruno@clisp.orgE<gt>
+
+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 L<http://www.gnu.org/licenses/>
+
+=cut
projects / gnulib.git / blobdiff