debian/README.git-merge-changelog

   1
   2 /* README:
   3    The default merge driver of 'git' *always* produces conflicts when
   4    pulling public modifications into a privately modified ChangeLog file.
   5    This is because ChangeLog files are always modified at the top; the
   6    default merge driver has no clue how to deal with this. Furthermore
   7    the conflicts are presented with more <<<< ==== >>>> markers than
   8    necessary; this is because the default merge driver makes pointless
   9    efforts to look at the individual line changes inside a ChangeLog entry.
  10
  11    This program serves as a 'git' merge driver that avoids these problems.
  12    1. It produces no conflict when ChangeLog entries have been inserted
  13       at the top both in the public and in the private modification. It
  14       puts the privately added entries above the publicly added entries.
  15    2. It respects the structure of ChangeLog files: entries are not split
  16       into lines but kept together.
  17    3. It also handles the case of small modifications of past ChangeLog
  18       entries, or of removed ChangeLog entries: they are merged as one
  19       would expect it.
  20    4. Conflicts are presented at the top of the file, rather than where
  21       they occurred, so that the user will see them immediately. (Unlike
  22       for source code written in some programming language, conflict markers
  23       that are located several hundreds lines from the top will not cause
  24       any syntax error and therefore would be likely to remain unnoticed.)
  25  */
  26
  27 /* Installation:
  28
  29    $ gnulib-tool --create-testdir --dir=/tmp/testdir123 git-merge-changelog
  30    $ cd /tmp/testdir123
  31    $ ./configure
  32    $ make
  33    $ make install
  34
  35    Additionally, for git users:
  36      - Add to .git/config of the checkout (or to your $HOME/.gitconfig) the
  37        lines
  38
  39           [merge "merge-changelog"]
  40                   name = GNU-style ChangeLog merge driver
  41                   driver = /usr/local/bin/git-merge-changelog %O %A %B
  42
  43      - In every directory that contains a ChangeLog file, add a file
  44        '.gitattributes' with this line:
  45
  46           ChangeLog    merge=merge-changelog
  47
  48        (See "man 5 gitattributes" for more info.)
  49
  50    Additionally, for bzr users:
  51      - Install the 'extmerge' bzr plug-in listed at
  52          <http://doc.bazaar.canonical.com/plugins/en/index.html>
  53          <http://wiki.bazaar.canonical.com/BzrPlugins>
  54      - Add to your $HOME/.bazaar/bazaar.conf the line
  55
  56           external_merge = git-merge-changelog %b %T %o
  57
  58      - Then, to merge a conflict in a ChangeLog file, use
  59
  60           $ bzr extmerge ChangeLog
  61
  62    Additionally, for hg users:
  63      - Add to your $HOME/.hgrc the lines
  64
  65         [merge-patterns]
  66         ChangeLog = git-merge-changelog
  67
  68         [merge-tools]
  69         git-merge-changelog.executable = /usr/local/bin/git-merge-changelog
  70         git-merge-changelog.args = $base $local $other
  71
  72        See <http://www.selenic.com/mercurial/hgrc.5.html> section merge-tools
  73        for reference.
  74  */
  75
  76 /* Use as an alternative to 'diff3':
  77    git-merge-changelog performs the same role as "diff3 -m", just with
  78    reordered arguments:
  79      $ git-merge-changelog %O %A %B
  80    is comparable to
  81      $ diff3 -m %A %O %B
  82  */
  83
  84 /* Calling convention:
  85    A merge driver is called with three filename arguments:
  86      1. %O = The common ancestor of %A and %B.
  87      2. %A = The file's contents from the "current branch".
  88      3. %B = The file's contents from the "other branch"; this is the contents
  89         being merged in.
  90
  91    In case of a "git stash apply" or of an upstream pull (e.g. from a subsystem
  92    maintainer to a central maintainer) or of a downstream pull with --rebase:
  93      2. %A = The file's newest pulled contents; modified by other committers.
  94      3. %B = The user's newest copy of the file; modified by the user.
  95    In case of a downstream pull (e.g. from a central repository to the user)
  96    or of an upstream pull with --rebase:
  97      2. %A = The user's newest copy of the file; modified by the user.
  98      3. %B = The file's newest pulled contents; modified by other committers.
  99
 100    It should write its merged output into file %A. It can also echo some
 101    remarks to stdout.  It should exit with return code 0 if the merge could
 102    be resolved cleanly, or with non-zero return code if there were conflicts.
 103  */
 104
 105 /* How it works:
 106    The structure of a ChangeLog file: It consists of ChangeLog entries. A
 107    ChangeLog entry starts at a line following a blank line and that starts with
 108    a non-whitespace character, or at the beginning of a file.
 109    The merge driver works as follows: It reads the three files into memory and
 110    dissects them into ChangeLog entries. It then finds the differences between
 111    %O and %B. They are classified as:
 112      - removals (some consecutive entries removed),
 113      - changes (some consecutive entries removed, some consecutive entries
 114        added),
 115      - additions (some consecutive entries added).
 116    The driver then attempts to apply the changes to %A.
 117    To this effect, it first computes a correspondence between the entries in %O
 118    and the entries in %A, using fuzzy string matching to still identify changed
 119    entries.
 120      - Removals are applied one by one. If the entry is present in %A, at any
 121        position, it is removed. If not, the removal is marked as a conflict.
 122      - Additions at the top of %B are applied at the top of %A.
 123      - Additions between entry x and entry y (y may be the file end) in %B are
 124        applied between entry x and entry y in %A (if they still exist and are
 125        still consecutive in %A), otherwise the additions are marked as a
 126        conflict.
 127      - Changes are categorized into "simple changes":
 128          entry1 ... entryn
 129        are mapped to
 130          added_entry ... added_entry modified_entry1 ... modified_entryn,
 131        where the correspondence between entry_i and modified_entry_i is still
 132        clear; and "big changes": these are all the rest. Simple changes at the
 133        top of %B are applied by putting the added entries at the top of %A. The
 134        changes in simple changes are applied one by one; possibly leading to
 135        single-entry conflicts. Big changes are applied en bloc, possibly
 136        leading to conflicts spanning multiple entries.
 137      - Conflicts are output at the top of the file and cause an exit status of
 138        1.
 139  */