fetch and pull ignore the changelog suite when it is UNRELEASED.

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index 677a51be2eea2517aa6b9ada23ef8d55d408d62d..54ed3d362f15e0c85f15ad6417189931c3710975 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -74,20 +74,9 @@ for the distro to which
 belongs.
 
 .I suite
 belongs.
 
 .I suite

-may be
-.IR mainsuite \fB,\fR subsuite ...
-in which case dgit will synthesize a view giving the most
-recent version in any of the specified suites.
-(The subsuites do not need to have the package.)
-If a subsuite starts with
-.B -
-then mainsuite is prepended.
-Each of the suite names will be individually canonicalised
-to calculate the canonical branch names to use.
-When using this facility, it is important to always specify the
-same suites in the same order:
-dgit will not be make a coherent fast-forwarding history
-view otherwise.
+may be a combination of several underlying suites in the form
+.IR mainsuite \fB,\fR subsuite ...;
+see COMBINED SUITES in dgit(7).

 
 For your convenience, the
 .B vcs-git
 
 For your convenience, the
 .B vcs-git


@@ -106,10 +95,7 @@ then dgit fetch defaults to
 .IR suite ;
 otherwise it parses debian/changelog and uses the suite specified
 there.
 .IR suite ;
 otherwise it parses debian/changelog and uses the suite specified
 there.

-
-suite may be
-.IR mainsuite \fB,\fR subsuite ...
-as for clone.
+suite may be a combined suite, as for clone.

 .TP
 \fBdgit pull\fR [\fIsuite\fP]
 Does dgit fetch, and then merges the new head of the remote tracking
 .TP
 \fBdgit pull\fR [\fIsuite\fP]
 Does dgit fetch, and then merges the new head of the remote tracking


@@ -201,15 +187,14 @@ current directory; however, signing operations are done on the
 invoking host.  This allows you to do a push when the system which has
 the source code and the build outputs has no access to the key:
 
 invoking host.  This allows you to do a push when the system which has
 the source code and the build outputs has no access to the key:
 

+.TS
+l l.

 1.     Clone on build host (dgit clone)
 1.     Clone on build host (dgit clone)

-.br

 2.     Edit code on build host (edit, git commit)
 2.     Edit code on build host (edit, git commit)

-.br

 3.     Build package on build host (dgit build)
 3.     Build package on build host (dgit build)

-.br

 4.     Test package on build host or elsewhere (dpkg -i, test)
 4.     Test package on build host or elsewhere (dpkg -i, test)

-.br

 5.     Upload by invoking dgit rpush on host with your GPG key.
 5.     Upload by invoking dgit rpush on host with your GPG key.

+.TE

 
 However, the build-host must be able to ssh to the dgit repos.  If
 this is not already the case, you must organise it separately, for
 
 However, the build-host must be able to ssh to the dgit repos.  If
 this is not already the case, you must organise it separately, for


@@ -281,6 +266,16 @@ and it therefore does not
 make a pseudomerge to bind the import
 into any existing git history.
 
 make a pseudomerge to bind the import
 into any existing git history.
 

+Because a .dsc can contain a Dgit field naming a git commit
+(which you might not have),
+and specifying where to find that commit
+(and any history rewrite table),
+import-dsc might need online access.
+If this is a problem
+(or dgit's efforts to find the commit fail),
+consider --no-chase-dsc-distro
+or --force-import-dsc-with-dgit-field.
+

 There is only only sub-option:
 
 .B --require-valid-signature
 There is only only sub-option:
 
 .B --require-valid-signature


@@ -312,11 +307,6 @@ If
 .I branch
 does not start with refs/, refs/heads/ is prepended.
 The specified branch is unconditionally updated.
 .I branch
 does not start with refs/, refs/heads/ is prepended.
 The specified branch is unconditionally updated.

-
-If the specified .dsc contains a Dgit field,
-dgit will simply make a branch of that commit.
-If you cannot manage to find that commit anywhere,
-consider --force-import-dsc-with-dgit-field.

 .TP
 .B dgit version
 Prints version information and exits.
 .TP
 .B dgit version
 Prints version information and exits.


@@ -324,6 +314,11 @@ Prints version information and exits.
 .BI "dgit clone-dgit-repos-server" " destdir"
 Tries to fetch a copy of the source code for the dgit-repos-server,
 as actually being used on the dgit git server, as a git tree.
 .BI "dgit clone-dgit-repos-server" " destdir"
 Tries to fetch a copy of the source code for the dgit-repos-server,
 as actually being used on the dgit git server, as a git tree.

+.TP
+.BI "dgit print-dgit-repos-server-source-url"
+Prints the url used by dgit clone-dgit-repos-server.
+This is hopefully suitable for use as a git remote url.
+It may not be useable in a browser.

 .SH OPTIONS
 .TP
 .BR --dry-run " | " -n
 .SH OPTIONS
 .TP
 .BR --dry-run " | " -n


@@ -471,6 +466,30 @@ someone should make a suitable dgit push
 to update the contents of dgit-repos
 to a version without the controversial changes.
 .TP
 to update the contents of dgit-repos
 to a version without the controversial changes.
 .TP

+.BR --no-chase-dsc-distro
+Tells dgit not to look online
+for additional git repositories
+containing information about a particular .dsc being imported.
+Chasing is the default.
+
+For most operations
+(such as fetch and pull),
+disabling chasing
+means dgit will access only the git server
+for the distro you are directly working with,
+even if the .dsc was copied verbatim from another distro.
+For import-dsc,
+disabling chasing
+means dgit will work completely offline.
+
+Disabling chasing can be hazardous:
+if the .dsc names a git commit which has been rewritten
+by those in charge of the distro,
+this option may prevent that rewrite from being effective.
+Also,
+using it can mean that
+dgit fails to find necessary git commits.
+.TP

 .BR --dgit-view-save= \fIbranch\fR|\fIref\fR
 Specifies that when a split view quilt mode is in operation,
 and dgit calculates
 .BR --dgit-view-save= \fIbranch\fR|\fIref\fR
 Specifies that when a split view quilt mode is in operation,
 and dgit calculates


@@ -680,6 +699,24 @@ By default, dgit looks in the parent directory
 .BI --no-rm-on-error
 Do not delete the destination directory if clone fails.
 .TP
 .BI --no-rm-on-error
 Do not delete the destination directory if clone fails.
 .TP

+.BI --dep14tag
+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.
+.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.)
+.TP
+.BI --dep14tag-always
+Insist on generating a DEP-14 tag
+as well as a dgit tag.
+If the server does not support that, dgit push will fail.
+.TP

 .BI -D
 Prints debugging information to stderr.  Repeating the option produces
 more output (currently, up to -DDDD is meaningfully different).
 .BI -D
 Prints debugging information to stderr.  Repeating the option produces
 more output (currently, up to -DDDD is meaningfully different).


@@ -910,6 +947,9 @@ may be a glob pattern.
 .BI dgit.default.distro " distro"
 The default distro for an unknown suite.
 .TP
 .BI dgit.default.distro " distro"
 The default distro for an unknown suite.
 .TP

+.BI dgit.default.default-suite " suite"
+The default suite (eg for clone).
+.TP

 .BR dgit.default. *
 for each
 .BR dgit-distro. \fIdistro\fR . *,
 .BR dgit.default. *
 for each
 .BR dgit-distro. \fIdistro\fR . *,


@@ -982,6 +1022,12 @@ services (archive and git) are provided.  These should not normally be
 adjusted, but are documented for the benefit of distros who wish to
 adopt dgit.
 .TP
 adjusted, but are documented for the benefit of distros who wish to
 adopt dgit.
 .TP

+.BI dgit-distro. distro .nominal-distro
+Shown in git tags, Dgit fields, and so on.
+.TP
+.BI dgit-distro. distro .alias-canon
+Used for all access configuration lookup.
+.TP

 .BR dgit-distro. \fIdistro\fR /push. *
 If set, overrides corresponding non \fB/push\fR config when
 .BR readonly=false ,
 .BR dgit-distro. \fIdistro\fR /push. *
 If set, overrides corresponding non \fB/push\fR config when
 .BR readonly=false ,


@@ -1014,6 +1060,8 @@ 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
+.TP

 .BI dgit-distro. distro .ssh
 .TP
 .BI dgit-distro. distro .sshpsql-dbname
 .BI dgit-distro. distro .ssh
 .TP
 .BI dgit-distro. distro .sshpsql-dbname


@@ -1021,6 +1069,16 @@ or when pushing and
 .BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force )
 .TP
 .BI dgit-distro. distro .backports-quirk
 .BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force )
 .TP
 .BI dgit-distro. distro .backports-quirk

+.TP
+.BI dgit-distro. distro .rewrite-map-enable
+.TP
+.BI dgit.default.old-dsc-distro
+.TP
+.BI dgit.dsc-url-proto-ok. protocol
+.TP
+.BI dgit.dsc-url-proto-ok.bad-syntax
+.TP
+.BI dgit.default.dsc-url-proto-ok

 .SH ENVIRONMENT VARIABLES
 .TP
 .BR DGIT_SSH ", " GIT_SSH
 .SH ENVIRONMENT VARIABLES
 .TP
 .BR DGIT_SSH ", " GIT_SSH