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>

diff --git a/dgit.1 b/dgit.1
index 5696778cccc24cb3a998fa8134150b7b9a115823..dca6ff0b06d35688d62589d2a1fe924df38f790c 100644 (file)
--- 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.

diff --git a/dgit.7 b/dgit.7
index 8325c06b10aaeed869c49d41345d9e24b4ea4fd3..d1e5c7ea579309a047ac495e1cef8da3256fd80b 100644 (file)
--- a/dgit.7
+++ b/dgit.7
@@ -393,7 +393,7 @@ this problem can occur if you have provided
 Debian git tooling such as git-debrebase, git-dpm or git-buildpackage
 with upstream git commit(s) or tag(s)
 which are not 100% identical to your orig tarball(s).
-.SH SPLIT VIEW QUILT MODE
+.SH SPLIT VIEW AND SPLITTING QUILT MODES
 When working with git branches intended
 for use with the `3.0 (quilt)' source format
 dgit can automatically convert a suitable
@@ -401,21 +401,33 @@ maintainer-provided git branch
 (in one of a variety of formats)
 into a dgit branch.
 
-When a split view mode is engaged
+When a splitting quilt mode is selected
 dgit build commands and
 dgit push
 will, on each invocation,
 convert the user's HEAD into the dgit view,
 so that it can be built and/or uploaded.
 
-dgit push in split view mode will push the dgit view to the dgit
+Split view mode can also be enabled explicitly
+with
+the --split-view command line option
+and
+the .split-view access configuration key.
+
+When split view is in operation,
+regardless of the quilt mode,
+any dgit-generated pseudomerges
+and any quilt fixup commits
+will appear only in the dgit view.
+dgit push
+will push the dgit view to the dgit
 git server.
 The dgit view is always a descendant of the maintainer view.
 dgit push will also make a maintainer view tag
 according to DEP-14
 and push that to the dgit git server.
 
-Split view mode must be enabled explicitly
+Splitting quilt modes must be enabled explicitly
 (by the use of the applicable command line options,
 subcommands, or configuration).
 This is because it is not possible to reliably tell