From 6a45cf9105d9db0c73ba474e043790e886b61f20 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Fri, 28 Jun 2019 16:48:37 +0100 Subject: 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 ++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 7 deletions(-) (limited to 'dgit.1') 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. -- cgit v1.2.3