[prev in list] [next in list] [prev in thread] [next in thread] 

List:       gnulib-bug
Subject:    git-merge-changelog in debian
From:       Ian Beckwith <ianb () erislabs ! net>
Date:       2014-03-09 18:06:14
Message-ID: 20140309180614.GB21289 () jezebel ! angsthaus ! erislabs ! net
[Download RAW message or body]

[Attachment #2 (multipart/mixed)]


Hi,

Per user request, git-merge-changelog is now a package in debian.

The binary package is generated from the gnulib source package, along
with the gnulib binary package.

Debian mandates man pages for all binaries, so I adapted the comments at
the top of git-merge-changelog.c into a man page. My *roff is a bit
ropy, so I used perl's pod format. I've attached it, along with the
pod2man output, feel free to include it if it's any use.

cheers,

Ian.

--=20
Ian Beckwith - ianb@erislabs.net - http://erislabs.net/ianb/
GPG fingerprint: AF6C C0F1 1E74 424B BCD5  4814 40EC C154 A8BA C1EA

["git-merge-changelog.pod" (text/plain)]

=head1 NAME

git-merge-changelog - git merge driver for GNU ChangeLog files

=head1 DESCRIPTION

The default merge driver of 'git' B<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 E<lt>E<lt>E<lt>E<lt> ==== E<gt>E<gt>E<gt>E<gt> 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.

=over 4

=item Z<>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.

=item Z<>2.

It respects the structure of ChangeLog files: entries are not split
into lines but kept together.

=item Z<>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.

=item Z<>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.)

=back

=head2 For git users:

=over 4

=item -

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

=item -

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.)

=back

=head2 For bzr users:

=over 4

=item -

Install the 'extmerge' bzr plug-in listed at
L<http://doc.bazaar.canonical.com/plugins/en/index.html>
L<http://wiki.bazaar.canonical.com/BzrPlugins>

=item -

Add to your $HOME/.bazaar/bazaar.conf the line

 external_merge = git-merge-changelog %b %T %o

=item -

Then, to merge a conflict in a ChangeLog file, use

 $ bzr extmerge ChangeLog

=back

=head2 For hg users:

=over 4

=item -

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 L<http://www.selenic.com/mercurial/hgrc.5.html> section B<merge-tools>
for reference.

=back

=head2 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

=head2 Calling convention:

A merge driver is called with three filename arguments:

=over 4

=item Z<>1.

%O = The common ancestor of %A and %B.

=item Z<>2.

%A = The file's contents from the "current branch".

=item Z<>3.

%B = The file's contents from the "other branch"; this is the contents
being merged in.

=back

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:

=over 4

=item Z<>2.

%A = The file's newest pulled contents; modified by other committers.

=item Z<>3.

%B = The user's newest copy of the file; modified by the user.

=back

In case of a downstream pull (e.g. from a central repository to the user)
or of an upstream pull with --rebase:

=over 4

=item Z<>2.

%A = The user's newest copy of the file; modified by the user.

=item Z<>3.

%B = The file's newest pulled contents; modified by other committers.

=back

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.

=head2 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:

=over 4

=item -

removals (some consecutive entries removed),

=item -

changes (some consecutive entries removed, some consecutive entries added),

=item -

additions (some consecutive entries added).

=back

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.

=over 4

=item -

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.

=item -

Additions at the top of %B are applied at the top of %A.

=item -

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.

=item -

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.

=item -

Conflicts are output at the top of the file and cause an exit status of 1.

=back

=head1 SEE ALSO

git(1), git-merge(1)

=head1 AUTHOR

The git-merge-changelog author and maintainer is Bruno Haible.

This man page was adapted by Ian Beckwith from the comments at the top
of git-merge-changelog.c.

=head1 AVAILABILITY

git-merge-changelog is part of the GNU gnulib project.

Gnulib home page: L<http://www.gnu.org/software/gnulib/>

=head1 COPYRIGHT

Copyright (C) 2008-2010 Bruno Haible E<lt>bruno@clisp.orgE<gt>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see L<http://www.gnu.org/licenses/>

=cut

["git-merge-changelog.1" (text/plain)]

.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "GIT-MERGE-CHANGELOG 1"
.TH GIT-MERGE-CHANGELOG 1 "2014-03-03" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
git\-merge\-changelog \- git merge driver for GNU ChangeLog files
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The default merge driver of 'git' \fBalways\fR 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.
.PP
This program serves as a 'git' merge driver that avoids these problems.
.IP "1." 4
.IX Item "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.
.IP "2." 4
.IX Item "2."
It respects the structure of ChangeLog files: entries are not split
into lines but kept together.
.IP "3." 4
.IX Item "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.
.IP "4." 4
.IX Item "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.)
.SS "For git users:"
.IX Subsection "For git users:"
.IP "\-" 4
Add to .git/config of the checkout (or to your \f(CW$HOME\fR/.gitconfig) the
lines
.Sp
.Vb 3
\& [merge "merge\-changelog"]
\&     name = GNU\-style ChangeLog merge driver
\&     driver = /usr/bin/git\-merge\-changelog %O %A %B
.Ve
.IP "\-" 4
In every directory that contains a ChangeLog file, add a file
\&'.gitattributes' with this line:
.Sp
.Vb 1
\& ChangeLog    merge=merge\-changelog
.Ve
.Sp
(See \*(L"man 5 gitattributes\*(R" for more info.)
.SS "For bzr users:"
.IX Subsection "For bzr users:"
.IP "\-" 4
Install the 'extmerge' bzr plug-in listed at
<http://doc.bazaar.canonical.com/plugins/en/index.html>
<http://wiki.bazaar.canonical.com/BzrPlugins>
.IP "\-" 4
Add to your \f(CW$HOME\fR/.bazaar/bazaar.conf the line
.Sp
.Vb 1
\& external_merge = git\-merge\-changelog %b %T %o
.Ve
.IP "\-" 4
Then, to merge a conflict in a ChangeLog file, use
.Sp
.Vb 1
\& $ bzr extmerge ChangeLog
.Ve
.SS "For hg users:"
.IX Subsection "For hg users:"
.IP "\-" 4
Add to your \f(CW$HOME\fR/.hgrc the lines
.Sp
.Vb 2
\& [merge\-patterns]
\&    ChangeLog = git\-merge\-changelog
\&
\& [merge\-tools]
\&     git\-merge\-changelog.executable = /usr/bin/git\-merge\-changelog
\&     git\-merge\-changelog.args = $base $local $other
.Ve
.Sp
See <http://www.selenic.com/mercurial/hgrc.5.html> section \fBmerge-tools\fR
for reference.
.SS "Use as an alternative to 'diff3':"
.IX Subsection "Use as an alternative to 'diff3':"
git-merge-changelog performs the same role as \*(L"diff3 \-m\*(R", just with
reordered arguments:
.PP
.Vb 1
\& $ git\-merge\-changelog %O %A %B
.Ve
.PP
is comparable to
.PP
.Vb 1
\& $ diff3 \-m %A %O %B
.Ve
.SS "Calling convention:"
.IX Subsection "Calling convention:"
A merge driver is called with three filename arguments:
.IP "1." 4
.IX Item "1."
\&\f(CW%O\fR = The common ancestor of \f(CW%A\fR and \f(CW%B\fR.
.IP "2." 4
.IX Item "2."
\&\f(CW%A\fR = The file's contents from the \*(L"current branch\*(R".
.IP "3." 4
.IX Item "3."
\&\f(CW%B\fR = The file's contents from the \*(L"other branch\*(R"; this is the contents
being merged in.
.PP
In case of a \*(L"git stash apply\*(R" or of an upstream pull (e.g. from a subsystem
maintainer to a central maintainer) or of a downstream pull with \-\-rebase:
.IP "2." 4
.IX Item "2."
\&\f(CW%A\fR = The file's newest pulled contents; modified by other committers.
.IP "3." 4
.IX Item "3."
\&\f(CW%B\fR = The user's newest copy of the file; modified by the user.
.PP
In case of a downstream pull (e.g. from a central repository to the user)
or of an upstream pull with \-\-rebase:
.IP "2." 4
.IX Item "2."
\&\f(CW%A\fR = The user's newest copy of the file; modified by the user.
.IP "3." 4
.IX Item "3."
\&\f(CW%B\fR = The file's newest pulled contents; modified by other committers.
.PP
It should write its merged output into file \f(CW%A\fR. 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.
.SS "How it works:"
.IX Subsection "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
\&\f(CW%O\fR and \f(CW%B\fR. They are classified as:
.IP "\-" 4
removals (some consecutive entries removed),
.IP "\-" 4
changes (some consecutive entries removed, some consecutive entries added),
.IP "\-" 4
additions (some consecutive entries added).
.PP
The driver then attempts to apply the changes to \f(CW%A\fR.
To this effect, it first computes a correspondence between the entries in \f(CW%O\fR
and the entries in \f(CW%A\fR, using fuzzy string matching to still identify changed
entries.
.IP "\-" 4
Removals are applied one by one. If the entry is present in \f(CW%A\fR, at any
position, it is removed. If not, the removal is marked as a conflict.
.IP "\-" 4
Additions at the top of \f(CW%B\fR are applied at the top of \f(CW%A\fR.
.IP "\-" 4
Additions between entry x and entry y (y may be the file end) in \f(CW%B\fR are
applied between entry x and entry y in \f(CW%A\fR (if they still exist and are
still consecutive in \f(CW%A\fR), otherwise the additions are marked as a
conflict.
.IP "\-" 4
Changes are categorized into \*(L"simple changes\*(R":
 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 \*(L"big changes\*(R": these are all the rest. Simple changes at the
top of \f(CW%B\fR are applied by putting the added entries at the top of \f(CW%A\fR. 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.
.IP "\-" 4
Conflicts are output at the top of the file and cause an exit status of 1.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIgit\fR\|(1), \fIgit\-merge\fR\|(1)
.SH "AUTHOR"
.IX Header "AUTHOR"
The git-merge-changelog author and maintainer is Bruno Haible.
.PP
This man page was adapted by Ian Beckwith from the comments at the top
of git\-merge\-changelog.c.
.SH "AVAILABILITY"
.IX Header "AVAILABILITY"
git-merge-changelog is part of the \s-1GNU\s0 gnulib project.
.PP
Gnulib home page: <http://www.gnu.org/software/gnulib/>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2008\-2010 Bruno Haible <bruno@clisp.org>
.PP
This program is free software: you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>

["signature.asc" (application/pgp-signature)]

[prev in list] [next in list] [prev in thread] [next in thread]