X-Git-Url: http://erislabs.net/gitweb/?p=gnulib.git;a=blobdiff_plain;f=debian%2FREADME.git-merge-changelog;fp=debian%2FREADME.git-merge-changelog;h=0000000000000000000000000000000000000000;hp=e68b69fe1bd481fc9b91cf9153a3bf1ded0bc4ee;hb=5c082dc2ec8dfe6922b327f134785f24783def7b;hpb=f2c702d3b25bc74dd2867efb82f9b6bb75509d93 diff --git a/debian/README.git-merge-changelog b/debian/README.git-merge-changelog deleted file mode 100644 index e68b69fe1..000000000 --- a/debian/README.git-merge-changelog +++ /dev/null @@ -1,133 +0,0 @@ - -/* README: - 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.) - */ - -/* Installation: - - 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 - - - - 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 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. - */