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.
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
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.)
30 - Add to .git/config of the checkout (or to your $HOME/.gitconfig) the
33 [merge "merge-changelog"]
34 name = GNU-style ChangeLog merge driver
35 driver = /usr/bin/git-merge-changelog %O %A %B
37 - In every directory that contains a ChangeLog file, add a file
38 '.gitattributes' with this line:
40 ChangeLog merge=merge-changelog
42 (See "man 5 gitattributes" for more info.)
45 - Install the 'extmerge' bzr plug-in listed at
46 <http://doc.bazaar.canonical.com/plugins/en/index.html>
47 <http://wiki.bazaar.canonical.com/BzrPlugins>
48 - Add to your $HOME/.bazaar/bazaar.conf the line
50 external_merge = git-merge-changelog %b %T %o
52 - Then, to merge a conflict in a ChangeLog file, use
54 $ bzr extmerge ChangeLog
57 - Add to your $HOME/.hgrc the lines
60 ChangeLog = git-merge-changelog
63 git-merge-changelog.executable = /usr/bin/git-merge-changelog
64 git-merge-changelog.args = $base $local $other
66 See <http://www.selenic.com/mercurial/hgrc.5.html> section merge-tools
70 /* Use as an alternative to 'diff3':
71 git-merge-changelog performs the same role as "diff3 -m", just with
73 $ git-merge-changelog %O %A %B
78 /* Calling convention:
79 A merge driver is called with three filename arguments:
80 1. %O = The common ancestor of %A and %B.
81 2. %A = The file's contents from the "current branch".
82 3. %B = The file's contents from the "other branch"; this is the contents
85 In case of a "git stash apply" or of an upstream pull (e.g. from a subsystem
86 maintainer to a central maintainer) or of a downstream pull with --rebase:
87 2. %A = The file's newest pulled contents; modified by other committers.
88 3. %B = The user's newest copy of the file; modified by the user.
89 In case of a downstream pull (e.g. from a central repository to the user)
90 or of an upstream pull with --rebase:
91 2. %A = The user's newest copy of the file; modified by the user.
92 3. %B = The file's newest pulled contents; modified by other committers.
94 It should write its merged output into file %A. It can also echo some
95 remarks to stdout. It should exit with return code 0 if the merge could
96 be resolved cleanly, or with non-zero return code if there were conflicts.
100 The structure of a ChangeLog file: It consists of ChangeLog entries. A
101 ChangeLog entry starts at a line following a blank line and that starts with
102 a non-whitespace character, or at the beginning of a file.
103 The merge driver works as follows: It reads the three files into memory and
104 dissects them into ChangeLog entries. It then finds the differences between
105 %O and %B. They are classified as:
106 - removals (some consecutive entries removed),
107 - changes (some consecutive entries removed, some consecutive entries
109 - additions (some consecutive entries added).
110 The driver then attempts to apply the changes to %A.
111 To this effect, it first computes a correspondence between the entries in %O
112 and the entries in %A, using fuzzy string matching to still identify changed
114 - Removals are applied one by one. If the entry is present in %A, at any
115 position, it is removed. If not, the removal is marked as a conflict.
116 - Additions at the top of %B are applied at the top of %A.
117 - Additions between entry x and entry y (y may be the file end) in %B are
118 applied between entry x and entry y in %A (if they still exist and are
119 still consecutive in %A), otherwise the additions are marked as a
121 - Changes are categorized into "simple changes":
124 added_entry ... added_entry modified_entry1 ... modified_entryn,
125 where the correspondence between entry_i and modified_entry_i is still
126 clear; and "big changes": these are all the rest. Simple changes at the
127 top of %B are applied by putting the added entries at the top of %A. The
128 changes in simple changes are applied one by one; possibly leading to
129 single-entry conflicts. Big changes are applied en bloc, possibly
130 leading to conflicts spanning multiple entries.
131 - Conflicts are output at the top of the file and cause an exit status of