changelog: Finalise 2.8

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index 677da279e0d58e2da4ba6f437a89063478ec4115..cc10695a636897e045ad2fc1cbd376187cca989d 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -376,7 +376,13 @@ maintainer view, the pseudo-merge will appear only in the dgit view.)
 Declare that you are deliberately doing
 .IR something .
 This can be used to override safety catches, including safety catches
 Declare that you are deliberately doing
 .IR something .
 This can be used to override safety catches, including safety catches

-which relate to distro-specific policies.  The meanings of
+which relate to distro-specific policies.
+The use of --deliberately is declared and published in the signed tags
+generated for you by dgit,
+so that the archive software can give effect to your intent,
+and
+for the benefit humans looking at the history.
+The meanings of

 .IR something s
 understood in the context of Debian are discussed below:
 .TP
 .IR something s
 understood in the context of Debian are discussed below:
 .TP


@@ -445,20 +451,24 @@ Do not check whether up source format `3.0 (quilt)' metadata needs
 fixing up.  If you use this option and the metadata did in fact need
 fixing up, dgit push will fail.
 .TP
 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
+.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.
 
 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
+.B --gbp
+(short for
+.BR --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.
 
 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
+.B --dpm
+(short for
+.BR --quilt=dpm )

 is for use with git-dpm.
 Your HEAD is expected to be
 a patches-applied git branch,
 is for use with git-dpm.
 Your HEAD is expected to be
 a patches-applied git branch,


@@ -470,9 +480,9 @@ that any changes to upstream .gitignore files are represented as
 patches in debian/patches).
 
 With --quilt=gbp|dpm|unapplied,
 patches in debian/patches).
 
 With --quilt=gbp|dpm|unapplied,

-dgit quilt-fixup and dgit-push will automatically
-convert your git branch into the right form,
-and dgit push will push the
+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.
 dgit-compatible form (the
 .BR "dgit view" )
 to the dgit git server.


@@ -484,16 +494,72 @@ dgit push will create a tag
 for the maintainer view, and the dgit tag
 .BI archive/debian/ version
 for the dgit view.
 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

+.BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
+Specifies that the suite to be operated on is part of distro
+.IR distro .
+This overrides the default value found from the git config option
+.BR dgit-suite. \fIsuite\fR .distro .
+The only effect is that other configuration variables (used
+for accessing the archive and dgit-repos) used are
+.BR dgit-distro. \fIdistro\fR .* .
+
+If your suite is part of a distro that dgit already knows about, you
+can use this option to make dgit work even if your dgit doesn't know
+about the suite.  For example, specifying
+.B -ddebian
+will work when the suite is an unknown suite in the Debian archive.
+
+To define a new distro it is necessary to define methods and URLs
+for fetching (and, for dgit push, altering) a variety of information both
+in the archive and in dgit-repos.
+How to set this up is not yet documented.
+.TP
+.BI -C changesfile
+Specifies the .changes file which is to be uploaded.  By default
+dgit push looks for single .changes file in the parent directory whose
+filename suggests it is for the right package and version.
+
+If the specified
+.I changesfile
+pathname contains slashes, the directory part is also used as
+the value for
+.BR --build-products-dir ;
+otherwise, the changes file is expected in that directory (by
+default, in
+.BR .. ).
+.TP
+.B --rm-old-changes
+When doing a build, delete any changes files matching
+.IB package _ version _*.changes
+before starting.  This ensures that
+dgit push (and dgit sbuild) will be able to unambigously
+identify the relevant changes files from the most recent build, even
+if there have been previous builds with different tools or options.
+The default is not to remove, but
+.B \-\-no-rm-old-changes
+can be used to override a previous \-\-rm-old-changes
+or the .rm-old-changes configuration setting.
+.TP
+.BI --build-products-dir= directory
+Specifies where to find the built files to be uploaded.
+By default, dgit looks in the parent directory
+.RB ( .. ).
+.TP
+.BI --no-rm-on-error
+Do not delete the destination directory if clone fails.
+.TP

 .BI -D
 Prints debugging information to stderr.  Repeating the option produces
 more output (currently, up to -DDDD is meaningfully different).
 .BI -D
 Prints debugging information to stderr.  Repeating the option produces
 more output (currently, up to -DDDD is meaningfully different).


@@ -523,6 +589,11 @@ Passed to dpkg-genchanges (eventually).
 .RI \fB--ch:\fR option
 Specifies a single additional option to pass, eventually, to
 dpkg-genchanges.
 .RI \fB--ch:\fR option
 Specifies a single additional option to pass, eventually, to
 dpkg-genchanges.

+
+Options which are safe to pass include
+.BR "-si -sa -sd -C" .
+
+For other options the caveat below applies.

 .TP
 .RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
 Specifies a single additional option to pass to
 .TP
 .RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
 Specifies a single additional option to pass to


@@ -558,7 +629,7 @@ 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.
 
 operations performed by dgit, and also not when git is invoked by
 another program run by dgit.
 

-See notes above regarding ssh and dgit.
+See notes below regarding ssh and dgit.

 
 NB that --gpg:option is not supported (because debsign does not
 have that facility).
 
 NB that --gpg:option is not supported (because debsign does not
 have that facility).


@@ -629,57 +700,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

-.BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
-Specifies that the suite to be operated on is part of distro
-.IR distro .
-This overrides the default value found from the git config option
-.BR dgit-suite. \fIsuite\fR .distro .
-The only effect is that other configuration variables (used
-for accessing the archive and dgit-repos) used are
-.BR dgit-distro. \fIdistro\fR .* .
-
-If your suite is part of a distro that dgit already knows about, you
-can use this option to make dgit work even if your dgit doesn't know
-about the suite.  For example, specifying
-.B -ddebian
-will work when the suite is an unknown suite in the Debian archive.
-
-To define a new distro it is necessary to define methods and URLs
-for fetching (and, for dgit push, altering) a variety of information both
-in the archive and in dgit-repos.
-How to set this up is not yet documented.
-.TP
-.BI -C changesfile
-Specifies the .changes file which is to be uploaded.  By default
-dgit push looks for single .changes file in the parent directory whose
-filename suggests it is for the right package and version.
-
-If the specified
-.I changesfile
-pathname contains slashes, the directory part is also used as
-the value for
-.BR --build-products-dir ;
-otherwise, the changes file is expected in that directory (by
-default, in
-.BR .. ).
-.TP
-.B --rm-old-changes
-When doing a build, delete any changes files matching
-.IB package _ version _*.changes
-before starting.  This ensures that
-dgit push (and dgit sbuild) will be able to unambigously
-identify the relevant changes files from the most recent build, even
-if there have been previous builds with different tools or options.
-The default is not to remove, but
-.B \-\-no-rm-old-changes
-can be used to override a previous \-\-rm-old-changes
-or the .rm-old-changes configuration setting.
-.TP
-.BI --build-products-dir= directory
-Specifies where to find the built files to be uploaded.
-By default, dgit looks in the parent directory
-.RB ( .. ).
-.TP

 .BI --existing-package= package
 dgit push needs to canonicalise the suite name.  Sometimes, dgit
 lacks a way to ask the archive to do this without knowing the
 .BI --existing-package= package
 dgit push needs to canonicalise the suite name.  Sometimes, dgit
 lacks a way to ask the archive to do this without knowing the


@@ -702,8 +722,34 @@ removed and recreated before dgit starts, rather than removed
 after dgit finishes.  The directory specified must be an absolute
 pathname.
 .TP
 after dgit finishes.  The directory specified must be an absolute
 pathname.
 .TP

-.BI --no-rm-on-error
-Do not delete the destination directory if clone fails.
+.BI --force- something
+Instructs dgit to try to proceed despite detecting
+what it thinks is going to be a fatal problem.
+.B This is probably not going to work.
+These options are provided as an escape hatch,
+in case dgit is confused.
+(They might also be useful for testing error cases.)
+.TP
+.B --force-unrepresentable
+Carry on even if
+dgit thinks that your git tree contains changes
+(relative to your .orig tarballs)
+which dpkg-source is not able to represent.
+Your build or push will probably fail later.
+.TP
+.B --force-unsupported-source-format
+Carry on despite dgit not understanding your source package format.
+dgit will probably mishandle it.
+.TP
+.B --force-dsc-changes-mismatch
+Do not check whether .dsc and .changes match.
+The archive will probably reject your upload.
+.TP
+.BR --force-import-gitapply-absurd " | " --force-import-gitapply-no-absurd
+Force on or off the use of the absurd git-apply emulation
+when running gbp pq import
+when importing a package from a .dsc.
+See Debian bug #841867.

 .SH WORKFLOW - SIMPLE
 It is always possible with dgit to clone or fetch a package, make
 changes in git (using git-commit) on the suite branch
 .SH WORKFLOW - SIMPLE
 It is always possible with dgit to clone or fetch a package, make
 changes in git (using git-commit) on the suite branch


@@ -952,6 +998,7 @@ fetches may result in subsequent actions being different.  Doing a
 non-dry-run dgit fetch first will help.
 .SH SEE ALSO
 \fBdgit\fP(7),
 non-dry-run dgit fetch first will help.
 .SH SEE ALSO
 \fBdgit\fP(7),

+\fBdgit-maint-merge\fP(7),

 \fBcurl\fP(1),
 \fBdput\fP(1),
 \fBdebsign\fP(1),
 \fBcurl\fP(1),
 \fBdput\fP(1),
 \fBdebsign\fP(1),