debian config; actually make split brain mode work. Closes:#841085.

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index b3a4f9392be39fac79845503c5295aa5eda7c4d7..42973a400380b6cfdee9ee4723293e2e86d8b553 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -139,6 +139,9 @@ Runs
 with some suitable options.  Options and arguments after gbp-build
 will be passed on to git-buildpackage.
 
 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]
 Tagging, signing and actually uploading should be left to dgit push.
 .TP
 \fBdgit push\fR [\fIsuite\fP]


@@ -273,46 +276,53 @@ rather than looking in debian/control or debian/changelog.
 Valid with dgit fetch and dgit pull, only.
 .TP
 .BR --clean=git " | " -wg
 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
 .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
 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
 .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.
 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
 .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 ),
 is cleaned by dpkg-source running the package's clean target.
 The build-dependencies are not checked (due to
 .BR -d ),


@@ -392,19 +402,35 @@ as the Debian server will do this automatically when necessary.
 .TP
 .BR --quilt=linear
 When fixing up source format `3.0 (quilt)' metadata, insist on
 .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
 .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,
 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.
 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
 .TP
 .BR --quilt=nofix
 Check whether source format `3.0 (quilt)' metadata would need fixing


@@ -430,7 +456,7 @@ do not want your branch changed by dgit.
 is for use with git-buildpackage.
 Your HEAD is expected to be
 a patches-unapplied git branch, except that it might contain changes
 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.
+to upstream .gitignore files.  This is the default for dgit gbp-build.

 
 .B --quilt=dpm
 is for use with git-dpm.
 
 .B --quilt=dpm
 is for use with git-dpm.


@@ -443,27 +469,30 @@ 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).
 
 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
+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-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
+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.
 .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
 
 .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
+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.
 undo the patch, expecting to actually revert it.

-If you fail to specify the right \-\-quilt option,
+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
 and you aren't too lucky, dgit will notice the problem and stop,
 with a useful hint. 
 .TP


@@ -497,6 +526,50 @@ Passed to dpkg-genchanges (eventually).
 Specifies a single additional option to pass, eventually, to
 dpkg-genchanges.
 .TP
 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 ,
 .RI \fB--curl=\fR program " | \fB--dput=\fR" program  " |..."
 Specifies alternative programs to use instead of
 .BR curl ,


@@ -558,42 +631,6 @@ git to access dgit-repos, only git's idea of what ssh to use (eg,
 .BR GIT_SSH )
 is relevant.
 .TP
 .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 .
 .BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
 Specifies that the suite to be operated on is part of distro
 .IR distro .