|author||Ian Jackson <firstname.lastname@example.org>||2019-06-28 16:48:37 +0100|
|committer||Ian Jackson <email@example.com>||2019-06-29 00:36:12 +0100|
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 <firstname.lastname@example.org>
2 files changed, 62 insertions, 11 deletions
@@ -742,7 +742,7 @@ it can mean that
dgit fails to find necessary git commits.
.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
+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
do not want your branch changed by dgit.
+These quilt modes are known as
+.BR "splitting quilt modes" .
+See --split-view, below.
.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.
+.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
+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.
+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.
+splits the view regardless of the source format and the quilt mode.
+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:
+.BI remotes/dgit/dgit/ suite
+.BR archive/ \fIdistro\fR / \fIversion\fR.
+Note that split view does not affect dgit fetch,
+and is not compatible with dgit pull.
.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.
-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.
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.
+.BR dgit-distro. \fIdistro\fR .split-view
.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.
@@ -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
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
+the --split-view command line option
+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.
+will push the dgit view to the dgit
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