From 6a45cf9105d9db0c73ba474e043790e886b61f20 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Fri, 28 Jun 2019 16:48:37 +0100 Subject: [PATCH] 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 --- dgit.1 | 53 ++++++++++++++++++++++++++++++++++++++++++++++------- dgit.7 | 20 ++++++++++++++++---- 2 files changed, 62 insertions(+), 11 deletions(-) diff --git a/dgit.1 b/dgit.1 index 5696778c..dca6ff0b 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. diff --git a/dgit.7 b/dgit.7 index 8325c06b..d1e5c7ea 100644 --- 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 -- 2.30.2