git-debrebase: merge: Do not sometimes drop the first patch!

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index f0d637df00ba6ca29cac5fb3bfffa4256b099a48..a21f212dc94382ae528a028254122585a7b15937 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -17,6 +17,10 @@ dgit \- git integration with the Debian archive
 [\fIbuild\-opts\fP]
 .br
 .B dgit
 [\fIbuild\-opts\fP]
 .br
 .B dgit

+[\fIdgit\-opts\fP] \fBpbuilder\fP|\fBcowbuilder\fP
+[\fIdebbuildopts\fP]
+.br
+.B dgit

 [\fIdgit\-opts\fP] \fBpush\fP|\fBpush-source\fP [\fIdgit\-opts\fP]
 [\fIsuite\fP]
 .br
 [\fIdgit\-opts\fP] \fBpush\fP|\fBpush-source\fP [\fIdgit\-opts\fP]
 [\fIsuite\fP]
 .br


@@ -194,6 +198,35 @@ You probably want to pass -A, to request those.
 .IP
 Tagging, signing and actually uploading should be left to dgit push.
 .TP
 .IP
 Tagging, signing and actually uploading should be left to dgit push.
 .TP

+\fBdgit pbuilder\fR [\fIdebbuildopts\fP]
+Constructs the source package, uses
+.B  pbuilder
+to do a binary build, and uses mergechanges to merge the source and
+binary changes files.
+The output is left in
+.IR package \fB_\fR version \fB_multi.changes\fR.
+
+You should ensure that your dgit --build-products-dir setting matches
+your pbuilder --buildresult.
+
+The \fIdebbuildopts\fP are passed to pbuilder using its --debbuildopts
+option.  If you want to pass other options to pbuilder, use the
+\fB--pbuilder:\fR dgit option as described below
+(remember that dgit options should appear between \fBdgit\fR and
+\fBpbuilder\fR).
+
+You should ensure that in your pbuilderrc you do
+.B not
+have the setting
+.B SOURCE_ONLY_CHANGES=yes
+as this may cause trouble.
+.TP
+\fBdgit cowbuilder\fR [\fIdebbuildopts\fP]
+Like \fBdgit pbuilder\fR, but uses
+.B cowbuilder
+instead of
+.B pbuilder.
+.TP

 \fBdgit gbp-build\fR ...
 Runs
 .B git-buildpackage
 \fBdgit gbp-build\fR ...
 Runs
 .B git-buildpackage


@@ -438,6 +471,26 @@ to cause it to exclude exactly the .git diredcory
 and nothing else.
 The separate arguments are unquoted, separated by spaces,
 and do not contain spaces.
 and nothing else.
 The separate arguments are unquoted, separated by spaces,
 and do not contain spaces.

+.TP
+.B dgit print-unapplied-treeish
+Constructs a tree-ish approximating the patches-unapplied state
+of your 3.0 (quilt) package,
+and prints the git object name to stdout.
+This requires appropriate .orig tarballs.
+This tree object is identical to your .origs
+as regards upstream files.
+The contents of the debian subdirectory is not interesting
+and should not be inspected;
+except that debian/patches will be identical to your HEAD.
+
+To make this operate off-line,
+the access configuration key
+which is used to determine the build-products-dir
+is the uncanonicalised version of the suite name from the changelog,
+or (of course) dgit.default.build-products-dir.
+See ACCESS CONFIGURATION, below.
+
+This function is primarily provided for the benefit of git-debrebase.

 .SH OPTIONS
 .TP
 .BR --dry-run " | " -n
 .SH OPTIONS
 .TP
 .BR --dry-run " | " -n


@@ -628,7 +681,7 @@ Also,
 it can mean that
 dgit fails to find necessary git commits.
 .TP
 it can mean that
 dgit fails to find necessary git commits.
 .TP

-.BR --dgit-view-save= \fIbranch\fR|\fIref\fR
+.BR --save-dgit-view= \fIbranch\fR|\fIref\fR

 Specifies that when a split view quilt mode is in operation,
 and dgit calculates
 (or looks up in its cache)
 Specifies that when a split view quilt mode is in operation,
 and dgit calculates
 (or looks up in its cache)


@@ -648,6 +701,10 @@ And it is only effective with
 If ref does not start with refs/
 it is taken to to be a branch -
 i.e. refs/heads/ is prepended.
 If ref does not start with refs/
 it is taken to to be a branch -
 i.e. refs/heads/ is prepended.

+
+.B --dgit-view-save
+is a deprecated alias for
+--save-dgit-view.

 .TP
 .BI --deliberately- something
 Declare that you are deliberately doing
 .TP
 .BI --deliberately- something
 Declare that you are deliberately doing


@@ -844,14 +901,20 @@ Note that \fBdgit push-source\fR will always find the right .changes,
 regardless of this option.
 .TP
 .BI --build-products-dir= directory
 regardless of this option.
 .TP
 .BI --build-products-dir= directory

-Specifies where to find the built files to be uploaded.
-By default, dgit looks in the parent directory
+Specifies where to find and create tarballs, binry packages,
+source packages, .changes files, and so on.
+
+By default, dgit uses the parent directory

 .RB ( .. ).
 
 .RB ( .. ).
 

-Also see the
+Changing this setting may necessitate
+moving .orig tarballs to the new directory,
+so it is probably best to
+use the

 .BI dgit.default.build-products-dir
 .BI dgit.default.build-products-dir

-configuration option
-(which this command line option overrides).
+configuration setting
+(see CONFIGURATION, below)
+which this command line option overrides).

 .TP
 .BI --no-rm-on-error
 Do not delete the destination directory if clone fails.
 .TP
 .BI --no-rm-on-error
 Do not delete the destination directory if clone fails.


@@ -922,6 +985,8 @@ Specifies a single additional option to pass to
 .BR dpkg-buildpackage ,
 .BR dpkg-genchanges ,
 .BR sbuild ,
 .BR dpkg-buildpackage ,
 .BR dpkg-genchanges ,
 .BR sbuild ,

+.BR pbuilder ,
+.BR cowbuilder ,

 .BR ssh ,
 .BR dgit ,
 .BR git-debrebase ,
 .BR ssh ,
 .BR dgit ,
 .BR git-debrebase ,


@@ -969,6 +1034,8 @@ Specifies alternative programs to use instead of
 .BR dpkg-buildpackage ,
 .BR dpkg-genchanges ,
 .BR sbuild ,
 .BR dpkg-buildpackage ,
 .BR dpkg-genchanges ,
 .BR sbuild ,

+.BR pbuilder ,
+.BR cowbuilder ,

 .BR gpg ,
 .BR ssh ,
 .BR dgit ,
 .BR gpg ,
 .BR ssh ,
 .BR dgit ,


@@ -1007,6 +1074,14 @@ In both cases,
 unusually, the specified value is split on whitespace
 to produce a command and possibly some options and/or arguments.
 
 unusually, the specified value is split on whitespace
 to produce a command and possibly some options and/or arguments.
 

+For pbuilder and cowbuilder, the defaults are
+.BR "sudo -E pbuilder"
+and
+.BR "sudo -E cowbuilder"
+respectively.
+Like with gbp-build and gbp pq,
+the specified value is split on whitespace.
+

 For
 .BR ssh ,
 the default value is taken from the
 For
 .BR ssh ,
 the default value is taken from the