dgit(1): document --quilt=bareebian

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index 9addd5a14c7a6756189341aaec30a8fbc69d9403..337b0637f0f57ca47fba93ee3cc55cfa049bf64c 100644 (file)
--- 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
 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
 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
 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,
 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.
 
 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 -
 
 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.
 
 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
 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
 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.
 
 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 )
 .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).
 
 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
 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
 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
 .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
 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
 .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
 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
 .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
 .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
 .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
 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.
 .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
 .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
 .TP
 .BI dgit-distro. distro .ssh
 .TP