docs: Document --split-view and change terminology

We now speak in the docs of
  * splitting quilt mode(s)
  * split view (being) in operation

Closes: #926640
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

1 files changed, 46 insertions, 7 deletions

diff --git a/dgit.1 b/dgit.1
index 5696778..dca6ff0 100644
--- a/dgit.1
+++ b/dgit.1
@@ -742,7 +742,7 @@ it can mean that
 dgit fails to find necessary git commits.
 .TP
 .BR \-\-save-dgit-view= \fIbranch\fR|\fIref\fR
-Specifies that when a split view quilt mode is in operation,
+Specifies that when split view is in operation,
 and dgit calculates
 (or looks up in its cache)
 a dgit view corresponding to your HEAD,
@@ -753,10 +753,7 @@ so don't specify a branch you want to keep.
 
 This option is effective only with the following operations:
 quilt-fixup; push; all builds.
-And it is only effective with
-\-\-[quilt=]gbp,
-\-\-[quilt=]dpm,
-\-\-quilt=unpatched.
+And it is only effective when split view is actually in operation.
 
 If ref does not start with refs/
 it is taken to be a branch -
@@ -786,7 +783,7 @@ Debian, use this when you are making a renewed upload of an entirely
 new source package whose previous version was not accepted for release
 from NEW because of problems with copyright or redistributibility.
 
-In split view quilt modes,
+When split view is in operation,
 this also prevents the construction by dgit of a pseudomerge
 to make the dgit view fast forwarding.
 Normally only one of
@@ -863,6 +860,10 @@ aka a
 and
 do not want your branch changed by dgit.
 
+These quilt modes are known as
+.BR "splitting quilt modes" .
+See --split-view, below.
+
 .B --gbp
 (short for
 .BR --quilt=gbp )
@@ -931,6 +932,42 @@ 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
+.BR \-\-split-view=auto | always | never
+Controls whether dgit operates a split view,
+separating your own branch (as Debian maintainer)
+from that shown to users of dgit clone and dgit fetch.
+
+When split view is in operation
+dgit will not make or merge any commits onto your own branch.
+Specifically, only the dgit view will contain
+dgit's pseudomerges,
+which bring into the git history previous uploads made with dgit push,
+and any commits in debian/patches required
+to make a correct `3.0 (quilt)' source package.
+
+.B auto
+is the default, and splits the view only when needed:
+i.e., when you are working with a `3.0 (quilt)' source package
+and a splitting quilt mode:
+\-\-[quilt=]gbp, dpm or unpatched.
+
+.B always
+splits the view regardless of the source format and the quilt mode.
+
+.B never
+will cause dgit to fail if split view is needed.
+
+When split view is in operation, the dgit view is visible
+in your git tree,
+but only in refs specific to dgit:
+notably
+.BI remotes/dgit/dgit/ suite
+and
+.BR archive/ \fIdistro\fR / \fIversion\fR.
+
+Note that split view does not affect dgit fetch,
+and is not compatible with dgit pull.
+.TP
 .BI \-C changesfile
 Specifies the .changes file which is to be uploaded.  By default
 dgit push looks for a single .changes file in the parent directory whose
@@ -987,7 +1024,7 @@ as well as a dgit tag (eg
 This is the default.
 .TP
 .BI --no-dep14tag
-Do not generate a DEP-14 tag, except in split quilt view mode.
+Do not generate a DEP-14 tag, except when split view is in operation.
 .TP
 .BI --always-dep14tag
 Obsolete alias for --dep14tag, retained for compatibility.
@@ -1293,6 +1330,8 @@ to provide a single git config compatible with different dgit versions.
 One of the values for the command line \-\-quilt= option; used if
 \-\-quilt is not specified.
 .TP
+.BR dgit-distro. \fIdistro\fR .split-view
+.TP
 .BR dgit-distro. \fIdistro\fR .rm-old-changes
 Boolean, used if neither \-\-rm-old-changes nor \-\-no-rm-old-changes
 is specified.  The default is not to remove.