X-Git-Url: http://erislabs.net/gitweb/?p=gnulib.git;a=blobdiff_plain;f=debian%2Fgit-merge-changelog.pod;fp=debian%2Fgit-merge-changelog.pod;h=8ef1bbda4994a1c9645672ab83394d81b31f6c7e;hp=0000000000000000000000000000000000000000;hb=5c082dc2ec8dfe6922b327f134785f24783def7b;hpb=f2c702d3b25bc74dd2867efb82f9b6bb75509d93 diff --git a/debian/git-merge-changelog.pod b/debian/git-merge-changelog.pod new file mode 100644 index 000000000..8ef1bbda4 --- /dev/null +++ b/debian/git-merge-changelog.pod @@ -0,0 +1,281 @@ +=head1 NAME + +git-merge-changelog - git merge driver for GNU ChangeLog files + +=head1 DESCRIPTION + +The default merge driver of 'git' B 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 EEEE ==== EEEE 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 +L + +=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 section B +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 + +=head1 COPYRIGHT + +Copyright (C) 2008-2010 Bruno Haible Ebruno@clisp.orgE + +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 + +=cut