.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH GIT\-DEBCHERRY 1 "April 27, 2014"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
git\-debcherry \- export commits touching upstream source as patches
.SH SYNOPSIS
.B git\-debcherry
.RI [ options "] " upstream " [" integration ]

.SH DESCRIPTION
This program will analyze git history and try to create a set of patches
meeting the following conditions:

.RS 4
1. Is guaranteed to apply to
.I upstream

2. Produces the same work tree as \fIintegration\fP, outside \fI./debian\fP

3. Does not touch \fI./debian\fP

4. As much as possible, matches the git history from
.I upstream
to
.I integration
.RE

.SH BRANCH PARAMETERS

.TP
.I upstream

This ref should be suitable for export as a
.I .orig.tar.gz.
In particular note that quilt has no way of deleting files that does
not include the material to be deleted in the patch, so your
.I upstream
branch should include any necessary file deletions.

.TP
.I integration

This branch contains all debian packaging, plus any changes introduced to
upstream source by the debian packager.
This argument is optional.
If
.I integration
is not passed
.B git\-debcherry
will use \fIHEAD\fP.
.RE

.SH OPTIONS
The following options are available:

.TP
.BI "\-o, \-\-output\-directory " directory

Place output (patches and series file) in \fIdirectory\fP.
If unspecified, output patches (in mbox format) to stdout.
.TP
.B \-s, \-\-stat

Only output diffstat of patches
.TP
.B \-d, \-\-debug
Output some debugging information. Probably only useful to developers
or those reporting bugs.

.SH EXAMPLE

To export the patches between tag \fIv3.0+dfsg1\fP and the current branch
into \fI./debian/patches\fP:

.nf
 $ git\-debcherry \-o debian/patches v3.0+dfsg1
.fi

.SH NOTES

.SS PERFORMANCE
\fBgit\-debcherry\fP currently uses
.BR git\-filter\-branch (1)
to rewrite all commits on the integration branch not present
upstream. Depending on the number of such commits, this can be
noticeably slow.

.SS DELETED FILES
\fBgit\-debcherry\fP currently follows
.BR dpkg\-source (1)
in ignoring file deletions. This has the positive side effect of not
bloating the patches, but if you really need the files deleted for the
build and/or licensing reasons, you should delete them in
\fIupstream\fP.

.SH SEE ALSO
.BR gitpkg (1)

.SH AUTHOR
\fBgit\-debcherry\fP was written by David Bremner <bremner@debian.org>.