dgit(1): Update BUGS section

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index f3e87feee095f90238ad2c97875ce70865b18f69..98b525bca0809ae5472822a7a7130def9bac4b80 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]


@@ -744,6 +747,12 @@ dgit will probably mishandle it.
 .B --force-dsc-changes-mismatch
 Do not check whether .dsc and .changes match.
 The archive will probably reject your upload.
 .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


@@ -957,42 +966,31 @@ and other subprograms and modules used by dgit are affected by various
 environment variables.  Consult the documentaton for those programs
 for details.
 .SH BUGS
 environment variables.  Consult the documentaton for those programs
 for details.
 .SH BUGS

-dgit's git representation of format `3.0 (quilt)' source packages does
-not represent the patch stack as git commits.  Currently the patch
-series representation cannot round trip between git and the archive.
-Ideally dgit would represent a quilty package with an origin commit of
-some kind followed by the patch stack as a series of commits followed
-by a pseudo-merge (to make the branch fast-forwarding).  This would
-also mean a new `dgit rebase-prep' command or some such to turn such a
-fast-forwarding branch back into a rebasing patch stack, and a `force'
-option to dgit push (perhaps enabled automatically by a note left by
-rebase-prep) which will make the required pseudo-merge.
-
-If the dgit push fails halfway through, it should be restartable and
-idempotent.  However this is not true for the git tag operation.
-Also, it would be good to check that the proposed signing key is
+There should be
+a `dgit rebase-prep' command or some such to turn a
+fast-forwarding branch containing pseudo-merges
+back into a rebasing patch stack.
+It might have to leave a note
+for a future dgit push.
+
+If the dgit push fails halfway through,
+it is not necessarily restartable and
+idempotent.
+It would be good to check that the proposed signing key is

 available before starting work.
 
 available before starting work.
 

-dgit's handling of .orig.tar.gz is not very sophisticated.  Ideally
-the .orig.tar.gz could be transported via the git repo as git tags.
-Doing this is made more complicated by the possibility of a `3.0
-(quilt)' package with multiple .orig tarballs.
-
-dgit's build functions, and dgit push, should not make any changes to
+dgit's build functions, and dgit push, may make changes to

 your current HEAD.  Sadly this is necessary for packages in the `3.0
 (quilt)' source format.  This is ultimately due to what I consider
 design problems in quilt and dpkg-source.
 
 your current HEAD.  Sadly this is necessary for packages in the `3.0
 (quilt)' source format.  This is ultimately due to what I consider
 design problems in quilt and dpkg-source.
 

-There should be an option which arranges for the `3.0 (quilt)'
-autocommit(s) to not appear on your HEAD, but instead only in the
-remote tracking suite branch.
-

 --dry-run does not always work properly, as not doing some of the git
 fetches may result in subsequent actions being different.  Doing a
 non-dry-run dgit fetch first will help.
 --dry-run does not always work properly, as not doing some of the git
 fetches may result in subsequent actions being different.  Doing a
 non-dry-run dgit fetch first will help.

+--damp-run is likely to work much better.

 .SH SEE ALSO
 \fBdgit\fP(7),
 .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),