debian/git-merge-changelog.pod

   1 =head1 NAME
   2
   3 git-merge-changelog - git merge driver for GNU ChangeLog files
   4
   5 =head1 DESCRIPTION
   6
   7 The default merge driver of 'git' B<always> produces conflicts when
   8 pulling public modifications into a privately modified ChangeLog file.
   9 This is because ChangeLog files are always modified at the top; the
  10 default merge driver has no clue how to deal with this. Furthermore
  11 the conflicts are presented with more E<lt>E<lt>E<lt>E<lt> ==== E<gt>E<gt>E<gt>E<gt> markers than
  12 necessary; this is because the default merge driver makes pointless
  13 efforts to look at the individual line changes inside a ChangeLog entry.
  14
  15 This program serves as a 'git' merge driver that avoids these problems.
  16
  17 =over 4
  18
  19 =item Z<>1.
  20
  21 It produces no conflict when ChangeLog entries have been inserted
  22 at the top both in the public and in the private modification. It
  23 puts the privately added entries above the publicly added entries.
  24
  25 =item Z<>2.
  26
  27 It respects the structure of ChangeLog files: entries are not split
  28 into lines but kept together.
  29
  30 =item Z<>3.
  31
  32 It also handles the case of small modifications of past ChangeLog
  33 entries, or of removed ChangeLog entries: they are merged as one
  34 would expect it.
  35
  36 =item Z<>4.
  37
  38 Conflicts are presented at the top of the file, rather than where
  39 they occurred, so that the user will see them immediately. (Unlike
  40 for source code written in some programming language, conflict markers
  41 that are located several hundreds lines from the top will not cause
  42 any syntax error and therefore would be likely to remain unnoticed.)
  43
  44 =back
  45
  46 =head2 For git users:
  47
  48 =over 4
  49
  50 =item -
  51
  52 Add to .git/config of the checkout (or to your $HOME/.gitconfig) the
  53 lines
  54
  55  [merge "merge-changelog"]
  56      name = GNU-style ChangeLog merge driver
  57      driver = /usr/bin/git-merge-changelog %O %A %B
  58
  59 =item -
  60
  61 In every directory that contains a ChangeLog file, add a file
  62 '.gitattributes' with this line:
  63
  64  ChangeLog    merge=merge-changelog
  65
  66 (See "man 5 gitattributes" for more info.)
  67
  68 =back
  69
  70 =head2 For bzr users:
  71
  72 =over 4
  73
  74 =item -
  75
  76 Install the 'extmerge' bzr plug-in listed at
  77 L<http://doc.bazaar.canonical.com/plugins/en/index.html>
  78 L<http://wiki.bazaar.canonical.com/BzrPlugins>
  79
  80 =item -
  81
  82 Add to your $HOME/.bazaar/bazaar.conf the line
  83
  84  external_merge = git-merge-changelog %b %T %o
  85
  86 =item -
  87
  88 Then, to merge a conflict in a ChangeLog file, use
  89
  90  $ bzr extmerge ChangeLog
  91
  92 =back
  93
  94 =head2 For hg users:
  95
  96 =over 4
  97
  98 =item -
  99
 100 Add to your $HOME/.hgrc the lines
 101
 102  [merge-patterns]
 103     ChangeLog = git-merge-changelog
 104
 105  [merge-tools]
 106      git-merge-changelog.executable = /usr/bin/git-merge-changelog
 107      git-merge-changelog.args = $base $local $other
 108
 109 See L<http://www.selenic.com/mercurial/hgrc.5.html> section B<merge-tools>
 110 for reference.
 111
 112 =back
 113
 114 =head2 Use as an alternative to 'diff3':
 115
 116 git-merge-changelog performs the same role as "diff3 -m", just with
 117 reordered arguments:
 118
 119  $ git-merge-changelog %O %A %B
 120
 121 is comparable to
 122
 123  $ diff3 -m %A %O %B
 124
 125 =head2 Calling convention:
 126
 127 A merge driver is called with three filename arguments:
 128
 129 =over 4
 130
 131 =item Z<>1.
 132
 133 %O = The common ancestor of %A and %B.
 134
 135 =item Z<>2.
 136
 137 %A = The file's contents from the "current branch".
 138
 139 =item Z<>3.
 140
 141 %B = The file's contents from the "other branch"; this is the contents
 142 being merged in.
 143
 144 =back
 145
 146 In case of a "git stash apply" or of an upstream pull (e.g. from a subsystem
 147 maintainer to a central maintainer) or of a downstream pull with --rebase:
 148
 149 =over 4
 150
 151 =item Z<>2.
 152
 153 %A = The file's newest pulled contents; modified by other committers.
 154
 155 =item Z<>3.
 156
 157 %B = The user's newest copy of the file; modified by the user.
 158
 159 =back
 160
 161 In case of a downstream pull (e.g. from a central repository to the user)
 162 or of an upstream pull with --rebase:
 163
 164 =over 4
 165
 166 =item Z<>2.
 167
 168 %A = The user's newest copy of the file; modified by the user.
 169
 170 =item Z<>3.
 171
 172 %B = The file's newest pulled contents; modified by other committers.
 173
 174 =back
 175
 176 It should write its merged output into file %A. It can also echo some
 177 remarks to stdout.  It should exit with return code 0 if the merge could
 178 be resolved cleanly, or with non-zero return code if there were conflicts.
 179
 180 =head2 How it works:
 181
 182 The structure of a ChangeLog file: It consists of ChangeLog entries. A
 183 ChangeLog entry starts at a line following a blank line and that starts with
 184 a non-whitespace character, or at the beginning of a file.
 185 The merge driver works as follows: It reads the three files into memory and
 186 dissects them into ChangeLog entries. It then finds the differences between
 187 %O and %B. They are classified as:
 188
 189 =over 4
 190
 191 =item -
 192
 193 removals (some consecutive entries removed),
 194
 195 =item -
 196
 197 changes (some consecutive entries removed, some consecutive entries added),
 198
 199 =item -
 200
 201 additions (some consecutive entries added).
 202
 203 =back
 204
 205 The driver then attempts to apply the changes to %A.
 206 To this effect, it first computes a correspondence between the entries in %O
 207 and the entries in %A, using fuzzy string matching to still identify changed
 208 entries.
 209
 210 =over 4
 211
 212 =item -
 213
 214 Removals are applied one by one. If the entry is present in %A, at any
 215 position, it is removed. If not, the removal is marked as a conflict.
 216
 217 =item -
 218
 219 Additions at the top of %B are applied at the top of %A.
 220
 221 =item -
 222
 223 Additions between entry x and entry y (y may be the file end) in %B are
 224 applied between entry x and entry y in %A (if they still exist and are
 225 still consecutive in %A), otherwise the additions are marked as a
 226 conflict.
 227
 228 =item -
 229
 230 Changes are categorized into "simple changes":
 231  entry1 ... entryn
 232 are mapped to
 233  added_entry ... added_entry modified_entry1 ... modified_entryn,
 234 where the correspondence between entry_i and modified_entry_i is still
 235 clear; and "big changes": these are all the rest. Simple changes at the
 236 top of %B are applied by putting the added entries at the top of %A. The
 237 changes in simple changes are applied one by one; possibly leading to
 238 single-entry conflicts. Big changes are applied en bloc, possibly
 239 leading to conflicts spanning multiple entries.
 240
 241 =item -
 242
 243 Conflicts are output at the top of the file and cause an exit status of 1.
 244
 245 =back
 246
 247 =head1 SEE ALSO
 248
 249 git(1), git-merge(1)
 250
 251 =head1 AUTHOR
 252
 253 The git-merge-changelog author and maintainer is Bruno Haible.
 254
 255 This man page was adapted by Ian Beckwith from the comments at the top
 256 of git-merge-changelog.c.
 257
 258 =head1 AVAILABILITY
 259
 260 git-merge-changelog is part of the GNU gnulib project.
 261
 262 Gnulib home page: L<http://www.gnu.org/software/gnulib/>
 263
 264 =head1 COPYRIGHT
 265
 266 Copyright (C) 2008-2010 Bruno Haible E<lt>bruno@clisp.orgE<gt>
 267
 268 This program is free software: you can redistribute it and/or modify
 269 it under the terms of the GNU General Public License as published by
 270 the Free Software Foundation; either version 2 of the License, or
 271 (at your option) any later version.
 272
 273 This program is distributed in the hope that it will be useful,
 274 but WITHOUT ANY WARRANTY; without even the implied warranty of
 275 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 276 GNU General Public License for more details.
 277
 278 You should have received a copy of the GNU General Public License
 279 along with this program.  If not, see L<http://www.gnu.org/licenses/>
 280
 281 =cut