with some suitable options. Options and arguments after gbp-build
will be passed on to git-buildpackage.
+By default this uses \-\-quilt=gbp, so HEAD should be a
+git-buildpackage style branch, not a patches-applied branch.
+
Tagging, signing and actually uploading should be left to dgit push.
.TP
\fBdgit push\fR [\fIsuite\fP]
Valid with dgit fetch and dgit pull, only.
.TP
.BR --clean=git " | " -wg
-The source tree should be cleaned, before building a source package
-with one of the build options, using
-.BR "git clean -xdf" .
-This will delete all files which are not tracked by git. Also, -wg
-causes dgit to pass
-.B -nc
-to dpkg-buildpackage, which prevents the package's own clean target
-from being run.
-
---clean=git is useful when the package's clean target is troublesome;
-the downside is simply that git clean may delete files you forgot to
-git add. --clean=git can also avoid needing the build-dependencies.
+Use
+.BR "git clean -xdf"
+to clean the working tree,
+rather than running the package's rules clean target.
+
+This will delete all files which are not tracked by git.
+(Including any files you forgot to git add.)
+
+.BI --clean= ...
+options other than dpkg-source
+are useful when the package's clean target is troublesome, or
+to avoid needing the build-dependencies.
.TP
.BR --clean=git-ff " | " -wgf
-The source tree should be cleaned, before building a source package
-with one of the build options, using
-.BR "git clean -xdff" .
-This is like
-"git clean -xdf"
+Use
+.BR "git clean -xdff"
+to clean the working tree.
+Like
+git clean -xdf
but it also removes any subdirectories containing different git
trees (which only unusual packages are likely to create).
.TP
.BR --clean=check " | " -wc
Merely check that the tree is clean (does not contain uncommitted
-files), before building a source package.
+files).
+Avoids running rules clean,
+and can avoid needing the build-dependencies.
.TP
.BR --clean=none " | " -wn
-Do not clean the tree before building a source package. If there are
+Do not clean the tree, nor check that it is clean.
+Avoids running rules clean,
+and can avoid needing the build-dependencies.
+If there are
files which are not in git, or if the build creates such files, a
subsequent dgit push will fail.
.TP
.BR --clean=dpkg-source " | " -wd
Use dpkg-buildpackage to do the clean, so that the source package
is cleaned by dpkg-source running the package's clean target.
-This is the default. It requires the package's build dependencies.
+This is the default.
+Requires the package's build dependencies.
.TP
.BR --clean=dpkg-source-d " | " -wdd
Use
.B dpkg-buildpackage -d
-to do the clean, so that the source package
+to do the clean,
+so that the source package
is cleaned by dpkg-source running the package's clean target.
The build-dependencies are not checked (due to
.BR -d ),
.TP
.BR --quilt=linear
When fixing up source format `3.0 (quilt)' metadata, insist on
-generating a linear patch stack. If such a stack cannot be generated,
-fail. This is the default for Debian.
+generating a linear patch stack: one new patch for each relevant
+commit.
+If such a stack cannot be generated, fail.
+This is the default for Debian.
+
+HEAD should be a series of plain commits
+(not touching debian/patches/),
+and pseudomerges,
+with as ancestor a patches-applied branch.
.TP
.BR --quilt=auto
When fixing up source format `3.0 (quilt)' metadata, prefer to
-generate a linear patch stack, but if that doesn't seem possible,
-generate a single squashed patch for all the changes made in git.
+generate a linear patch stack
+(as with --quilt=auto)
+but if that doesn't seem possible,
+try to generate a single squashed patch for all the changes made in git
+(as with --quilt=smash).
This is not a good idea for an NMU in Debian.
.TP
.BR --quilt=smash
When fixing up source format `3.0 (quilt)' metadata,
-generate a single squashed patch for all the changes made in git.
+generate a single additional patch for all the changes made in git.
This is not a good idea for an NMU in Debian.
+
+(If HEAD has any in-tree patches already, they must apply cleanly.
+This will be the case for any trees produced by dgit fetch or clone;
+if you do not change the upstream version
+nor make changes in debian/patches,
+it will remain true.)
.TP
.BR --quilt=nofix
Check whether source format `3.0 (quilt)' metadata would need fixing
fixing up. If you use this option and the metadata did in fact need
fixing up, dgit push will fail.
.TP
+.BR --quilt=gbp " | " --quilt=dpm " | " --quilt=unapplied
+Tell dgit that you are using a nearly-dgit-compatible git branch,
+aka a
+.BR "maintainer view" ,
+and
+do not want your branch changed by dgit.
+
+.B --quilt=gbp
+is for use with git-buildpackage.
+Your HEAD is expected to be
+a patches-unapplied git branch, except that it might contain changes
+to upstream .gitignore files. This is the default for dgit gbp-build.
+
+.B --quilt=dpm
+is for use with git-dpm.
+Your HEAD is expected to be
+a patches-applied git branch,
+except that it might contain changes to upstream .gitignore files.
+
+.B --quilt=unapplied
+specifies that your HEAD is a patches-unapplied git branch (and
+that any changes to upstream .gitignore files are represented as
+patches in debian/patches).
+
+With --quilt=gbp|dpm|unapplied,
+dgit push (or precursors like quilt-fixup and build) will automatically
+generate a conversion of your git branch into the right form.
+dgit push will push the
+dgit-compatible form (the
+.BR "dgit view" )
+to the dgit git server.
+The dgit view will be visible to you
+in the dgit remote tracking branches, but your own branch will
+not be modified.
+dgit push will create a tag
+.BI debian/ version
+for the maintainer view, and the dgit tag
+.BI archive/debian/ version
+for the dgit view.
+dgit quilt-fixup will merely do some checks,
+and cache the maintainer view.
+
+.B If you have a branch like this it is essential to specify the appropriate --quilt= option!
+This is because it is not always possible to tell: a patches-unapplied
+git branch of a package with one patch, for example, looks very like
+a patches-applied branch where the user has used git revert to
+undo the patch, expecting to actually revert it.
+However, if you fail to specify the right \-\-quilt option,
+and you aren't too lucky, dgit will notice the problem and stop,
+with a useful hint.
+.TP
.BI -D
Prints debugging information to stderr. Repeating the option produces
more output (currently, up to -DDDD is meaningfully different).
Specifies a single additional option to pass, eventually, to
dpkg-genchanges.
.TP
+.RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
+Specifies a single additional option to pass to
+.BR curl ,
+.BR dput ,
+.BR debsign ,
+.BR dpkg-source ,
+.BR dpkg-buildpackage ,
+.BR dpkg-genchanges ,
+.BR sbuild ,
+.BR ssh ,
+.BR dgit ,
+.BR gbp-pq ,
+.BR gbp-build ,
+or
+.BR mergechanges .
+Can be repeated as necessary.
+
+Use of this ability should not normally be necessary.
+It is provided for working around bugs,
+or other unusual situations.
+If you use these options,
+you may violate dgit's assumptions
+about the behaviour of its subprograms
+and cause lossage.
+
+For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
+the option applies only when the program is invoked directly by dgit.
+Usually, for passing options to dpkg-genchanges, you should use
+.BR --ch: \fIoption\fR.
+
+Specifying --git is not effective for some lower-level read-only git
+operations performed by dgit, and also not when git is invoked by
+another program run by dgit.
+
+See notes below regarding ssh and dgit.
+
+NB that --gpg:option is not supported (because debsign does not
+have that facility).
+But see
+.B -k
+and the
+.B keyid
+distro config setting.
+.TP
.RI \fB--curl=\fR program " | \fB--dput=\fR" program " |..."
Specifies alternative programs to use instead of
.BR curl ,
.BR GIT_SSH )
is relevant.
.TP
-.RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
-Specifies a single additional option to pass to
-.BR curl ,
-.BR dput ,
-.BR debsign ,
-.BR dpkg-source ,
-.BR dpkg-buildpackage ,
-.BR dpkg-genchanges ,
-.BR sbuild ,
-.BR ssh ,
-.BR dgit ,
-.BR gbp-pq ,
-.BR gbp-build ,
-or
-.BR mergechanges .
-Can be repeated as necessary.
-
-For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
-this applies only when the program is invoked directly by dgit.
-Usually, for passing options to dpkg-genchanges, you should use
-.BR --ch: \fIoption\fR.
-
-Specifying --git not effective for some lower-level read-only git
-operations performed by dgit, and also not when git is invoked by
-another program run by dgit.
-
-See notes above regarding ssh and dgit.
-
-NB that --gpg:option is not supported (because debsign does not
-have that facility).
-But see
-.B -k
-and the
-.B keyid
-distro config setting.
-.TP
.BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
Specifies that the suite to be operated on is part of distro
.IR distro .
~ianmdlvl / dgit.git / blobdiff