From a55d42df5abe271c8c0ba88d1238120df7b4ba72 Mon Sep 17 00:00:00 2001 From: Ian Beckwith Date: Sun, 2 Mar 2014 11:13:34 +0000 Subject: [PATCH] add README header from git-merge-changelog.c as README file --- debian/README.git-merge-changelog | 139 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 debian/README.git-merge-changelog diff --git a/debian/README.git-merge-changelog b/debian/README.git-merge-changelog new file mode 100644 index 000000000..61ce6eb8f --- /dev/null +++ b/debian/README.git-merge-changelog @@ -0,0 +1,139 @@ + +/* 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: + + $ gnulib-tool --create-testdir --dir=/tmp/testdir123 git-merge-changelog + $ cd /tmp/testdir123 + $ ./configure + $ make + $ make install + + Additionally, 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/local/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.) + + Additionally, 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 + + Additionally, for hg users: + - Add to your $HOME/.hgrc the lines + + [merge-patterns] + ChangeLog = git-merge-changelog + + [merge-tools] + git-merge-changelog.executable = /usr/local/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. + */ -- 2.11.0