X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=dgit.1;h=337b0637f0f57ca47fba93ee3cc55cfa049bf64c;hb=d14f9ca00ec562e5a64bc64940756a1701baf08b;hp=9addd5a14c7a6756189341aaec30a8fbc69d9403;hpb=68b4931ea75f361a936121e3dd9e9ff34ff62f34;p=dgit.git

diff --git a/dgit.1 b/dgit.1
index 9addd5a1..337b0637 100644
--- a/dgit.1
+++ b/dgit.1
@@ -695,7 +695,7 @@ of git merge -s ours) to stitch the archive's version into your own
 git history, so that your push is a fast forward from the archive.
 
 (In quilt mode
-.BR gbp ", " dpm " or " unpatched ,
+.BR gbp ", " dpm ", " unpatched " or " baredebian ,
 implying a split between the dgit view and the
 maintainer view, the pseudo-merge will appear only in the dgit view.)
 .TP
@@ -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
@@ -856,13 +853,17 @@ Do not check whether source format `3.0 (quilt)' metadata needs
 fixing up.  If you use this option and the metadata did in fact need
 fixing up, dgit push will fail.
 .TP
-.BR -- [ quilt= ] gbp " | " -- [ quilt= ] dpm " | " --quilt=unapplied
+.BR -- [ quilt= ] gbp " | " -- [ quilt= ] dpm " | " --quilt=unapplied " | " -- [ quilt= ] baredebian
 Tell dgit that you are using a nearly-dgit-compatible git branch,
 aka a
 .BR "maintainer view" ,
 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 )
@@ -884,7 +885,15 @@ specifies that your HEAD is a patches-unapplied git branch (and
 that any changes to upstream .gitignore files are represented as
 patches in debian/patches).
 
-With --quilt=gbp|dpm|unapplied,
+.B --quilt=baredebian
+specifies that your HEAD contains only a debian/ directory,
+with any changes to upstream .gitignore files are represented as
+patches in debian/patches.
+The upstream source must be available in git,
+by default, in a suitably named git tag;
+see --upstream-commitish.
+
+With --quilt=gbp|dpm|unapplied|baredebian,
 dgit push (or precursors like quilt-fixup and build) will automatically
 generate a conversion of your git branch into the right form.
 dgit push will push the
@@ -931,6 +940,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, unpatched or baredebian.
+
+.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
@@ -945,6 +990,14 @@ otherwise, the changes file is expected in that directory (by
 default, in
 .BR .. ).
 .TP
+.BI \-\-upstream-commitish= upstream
+For use with --quilt=baredebian only.
+Specifies the commit containing the upstream source.
+This commit must be identical to your .orig tarball.
+The default is to look for one of the git tags
+.IB U " v" U " upstream/" U
+(in that order), where U is the upstream version.
+.TP
 .B \-\-rm-old-changes
 When doing a build, delete any changes files matching
 .IB package _ version _*.changes
@@ -983,19 +1036,14 @@ Do not delete the destination directory if clone fails.
 Generates a DEP-14 tag (eg
 .BR debian/ \fIversion\fR)
 as well as a dgit tag (eg
-.BR archive/debian/ \fIversion\fR)
-where possible.  This is the default.
+.BR archive/debian/ \fIversion\fR).
+This is the default.
 .TP
 .BI --no-dep14tag
-Do not generate a DEP-14 tag, except in split quilt view mode.
-(On servers where only the old tag format is supported,
-the dgit tag will have the DEP-14 name.
-This option does not prevent that.)
+Do not generate a DEP-14 tag, except when split view is in operation.
 .TP
 .BI --always-dep14tag
-Insist on generating a DEP-14 tag
-as well as a dgit tag.
-If the server does not support that, dgit push will fail.
+Obsolete alias for --dep14tag, retained for compatibility.
 .TP
 .BI -D
 Prints debugging information to stderr.  Repeating the option produces
@@ -1298,6 +1346,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.
@@ -1402,7 +1452,7 @@ or when pushing and
 .TP
 .BI dgit-distro. distro .dgit-tag-format
 .TP
-.BR dgit-distro. \fIdistro\fR .dep14tag " " want | no | always
+.BR dgit-distro. \fIdistro\fR .dep14tag " " want | no [| always ]
 .TP
 .BI dgit-distro. distro .ssh
 .TP