import-dsc: Introduce $info (nfc)

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index d37e5b0bb0c667d9ead536e13d85fffa7cf3d0fc..c2541f0eb8163a8c8ffafff0f288bf634c4628ff 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -155,6 +155,9 @@ the built source package not being identical to the git tree.
 
 In more detail: dgit push checks that the current HEAD corresponds to
 the .dsc.  It then pushes the HEAD to the suite's dgit-repos branch,
+adjusts the .changes to include any .origs which the archive lacks
+and exclude .origs which the archive has
+(so -sa and -sd are not needed when building for dgit push),
 makes a signed git tag, edits the .dsc to contain the dgit metadata
 field, runs debsign to sign the upload (.dsc and .changes), pushes the
 signed tag, and finally uses dput to upload the .changes to the
@@ -237,6 +240,33 @@ other kinds of more exotic history.  If dgit can't find a suitable
 linearisation of your history, by default it will fail, but you can
 ask it to generate a single squashed patch instead.
 .TP
+.BI "dgit import-dsc " ../path/to/.dsc branch
+Import a Debian-format source package,
+specified by its .dsc,
+into git,
+the way dgit fetch would do.
+
+This does about half the work of dgit fetch:
+it will convert the .dsc into a new, orphan git branch.
+Since dgit has no access to a corresponding source package archive
+or knowledge of the history
+it does not consider whether this version is newer
+than any previous import
+or corresponding git branches;
+and it therefore does not
+make a pseudomerge to bind the import
+into any existing git history.
+
+If
+.I branch
+does not start with refs/, refs/heads/ is prepended.
+The specified branch is unconditionally updated.
+
+If the specified .dsc contains a Dgit field,
+dgit will simply make a branch of that commit.
+If you cannot manage to find that commit anywhere,
+consider --force-import-dsc-with-dgit-field.
+.TP
 .B dgit version
 Prints version information and exits.
 .TP
@@ -376,7 +406,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
-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
@@ -585,7 +621,11 @@ Specifies a single additional option to pass, eventually, to
 dpkg-genchanges.
 
 Options which are safe to pass include
-.BR "-si -sa -sd -C" .
+.BR -C
+(and also
+.BR "-si -sa -sd"
+although these should never be necessary with Debian since dgit
+automatically calculates whether .origs need to be uploaded.)
 
 For other options the caveat below applies.
 .TP
@@ -715,6 +755,47 @@ instead.  Furthermore, the specified directory will be emptied,
 removed and recreated before dgit starts, rather than removed
 after dgit finishes.  The directory specified must be an absolute
 pathname.
+.TP
+.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 --import-dsc-with-dgit-field
+Tell dgit import-dsc to treat a .dsc with a Dgit field
+like one without it.
+The result is a fresh import,
+discarding the git history
+that the person who pushed that .dsc was working with.
+.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-changes-origs-exactly
+Use the set of .origs specified in your .changes, exactly,
+without regard to what is in the archive already.
+The archive may well reject your upload.
+.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