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 ),
push will still ensure that the .dsc you upload and the git tree
you push are identical, so this option won't make broken pushes.)
.TP
-.BI --overwrite= previous-version
-Declare that even though your git branch is not a descendant of
-.IR previous-version
-according to the revision history, in fact, it really does contain
+.BR --overwrite =\fIprevious-version\fR
+Declare that even though your git branch is not a descendant
+of the version in the archive
+according to the revision history,
+it really does contain
all the (wanted) changes from that version.
-.I previous-version
-ought to be the version currently in the archive.
-dgit push will make a
+This option is useful if you are the maintainer, and you have
+incorporated NMU changes into your own git workflow in a way that
+doesn't make your branch a fast forward from the NMU.
+
+.I previous-version
+ought to be the version currently in the archive. If
+.I previous-version
+is not
+specified, dgit will check that the version in the archive is
+mentioned in your debian/changelog.
+(This will avoid losing
+changes unless someone committed to git a finalised changelog
+entry, and then made later changes to that version.)
+
+dgit push --overwrite
+will make a
pseudo-merge (that is, something that looks like the result
of git merge -s ours) to stitch the archive's version into your own
git history, so that your push is a fast forward from the archive.
-This option is useful if you are the maintainer, and you have
-incorporated NMU changes into your own git workflow in way that
-doesn't make your branch a fast forward from the NMU.
-
(In quilt mode
.BR gbp ", " dpm " or " unpatched ,
implying a split between the dgit view and the
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).
+
+Instead, dgit quilt-fixup and dgit-push will automatically
+convert your git branch into the right form,
+and 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 will create a tag
+.BI debian/ version
+for the maintainer view, and the dgit tag
+.BI archive/debian/ version
+for the dgit 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 just the
+same as a patches-applied branch where the user has used git revert to
+undo the patch, expecting to actually revert it.
+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).
.BR ssh ,
.BR dgit ,
.BR git ,
+.BR gbp-pq ,
+.BR gbp-build ,
or
.BR mergechanges .
-For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
+For
+.BR dpkg-buildpackage ,
+.BR dpkg-genchanges ,
+.B mergechanges
+and
+.BR sbuild ,
this applies only when the program is invoked directly by dgit.
-For dgit, specifies the command to run on the remote host when dgit
+For
+.BR dgit ,
+specifies the command to run on the remote host when dgit
rpush needs to invoke a remote copy of itself. (dgit also reinvokes
itself as the EDITOR for dpkg-source --commit; this is done using
argv[0], and is not affected by --dgit=).
-For ssh, the default value is taken from the
+.BR gbp-build 's
+value
+is used instead of gbp build or git-buildpackage. (The default is
+the latter unless the former exists on PATH.)
+.BR gbp-pq 's
+value
+is used instead of gbp pq.
+In both cases,
+unusually, the specified value is split on whitespace
+to produce a command and possibly some options and/or arguments.
+
+For
+.BR ssh ,
+the default value is taken from the
.B DGIT_SSH
or
.B GIT_SSH
.BR sbuild ,
.BR ssh ,
.BR dgit ,
+.BR gbp-pq ,
+.BR gbp-build ,
or
.BR mergechanges .
Can be repeated as necessary.
~ianmdlvl / dgit.git / blobdiff