dgit(1): Reference tutorials

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index d6ac8b25a907be3b9e857352613114e1862291ec..90f9c10d9b642246c1e936f84998dda692f5f963 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -1,3 +1,4 @@
+'\" t

 .TH dgit 1 "" "Debian Project" "dgit"
 .SH NAME
 dgit \- git integration with the Debian archive
 .TH dgit 1 "" "Debian Project" "dgit"
 .SH NAME
 dgit \- git integration with the Debian archive


@@ -28,21 +29,23 @@ dgit \- git integration with the Debian archive
 .SH DESCRIPTION
 .B dgit
 allows you to treat the Debian archive as if it were a git
 .SH DESCRIPTION
 .B dgit
 allows you to treat the Debian archive as if it were a git

-repository.  See \fBdgit\fP(7) for detailed information about the data
-model, common problems likely to arise with certain kinds of package,
+repository.
+
+This is the command line reference.
+Please read the tutorial(s):
+.TS
+lb l.
+dgit-user(7)   for users: editing, building and sharing packages
+dgit-nmu-simple(7)     for DDs/DMs: doing a straightforward NMU
+dgit-maint-merge(7)    for maintainers: using a merging git workflow
+dgit-maint-gbp(7)      for maintainers: using git-buildpackage
+dgit-sponsorship(7)    for sponsors and sponsored contributors
+.TE
+.LP
+See \fBdgit(7)\fP for detailed information about the data
+model,
+common problems likely to arise with certain kinds of package,

 etc.
 etc.

-
-The usual workflow is:
-.br
-1.     \fBdgit clone\fR or \fBfetch\fR;
-.br
-2.     make, do dev tests, and commit changes in git as desired;
-.br
-3.     build packages for upload, using e.g. \fBdgit sbuild\fR
-.br
-4.     do pre-upload tests of the proposed upload;
-.br
-5.     \fBdgit push\fR.

 .SH OPERATIONS
 .TP
 \fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
 .SH OPERATIONS
 .TP
 \fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]


@@ -721,6 +724,35 @@ 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.
 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 --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


@@ -969,7 +1001,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),
+\fBdgit-*\fP(7),

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