dgit(1), dgit(7): Better reference docs for combined suites.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/debian/changelog b/debian/changelog
index 348f5aec740998bb421d37737664fde4c4cf08f8..2136b8b641de52b631c06cd7b43fb87bd7a39d54 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -3,6 +3,7 @@ dgit (2.11~) unstable; urgency=medium
   Documentation:
   * dgit-user(7): Better explanation of combined suites (comma syntax).
     Thanks to Sean Whitton for review and suggestions.
   Documentation:
   * dgit-user(7): Better explanation of combined suites (comma syntax).
     Thanks to Sean Whitton for review and suggestions.

+  * dgit(1), dgit(7): Better reference docs for combined suites.

 
   Test suite:
   * Replace make in Test-Depends with build-essential.  Most of the tests
 
   Test suite:
   * Replace make in Test-Depends with build-essential.  Most of the tests

diff --git a/dgit.1 b/dgit.1
index f2821dffd32ba6172bfcc203674065c1ebb29150..0029dfaadb257d644732594ee8e2dc5b58834248 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -74,23 +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.
-The history generated by this feature is not normally suitable
-for merging back into upstreams,
-as it necessarily contains unattractive pseudomerges.
+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


@@ -109,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

diff --git a/dgit.7 b/dgit.7
index 6f5844b4e694c19a187e3f0c29b699f55702a9a4..f7e50e4b6c45ec05efbd636ba1b6a5fdfc3ba00f 100644 (file)
--- a/dgit.7
+++ b/dgit.7
@@ -112,6 +112,57 @@ using dgit look like
 reasonable
 changes made in an NMU: in a `3.0 (quilt)' package the delta from the
 previous upload is recorded in new patch(es) constructed by dpkg-source.
 reasonable
 changes made in an NMU: in a `3.0 (quilt)' package the delta from the
 previous upload is recorded in new patch(es) constructed by dpkg-source.

+.SH COMBINED SUITES
+dgit can synthesize a combined view of several underlying suites.
+This is requested by specifying, for
+.I suite,
+a comma-separated list:
+.IP
+.IR mainsuite \fB,\fR subsuite ...
+.LP
+This facility is available with dgit clone, fetch and pull, only.
+
+dgit will fetch the same package from each specified underlying suite,
+separately (as if with dgit fetch).
+dgit will then generate a pseudomerge commit
+on the tracking branch
+.BI remotes/dgit/dgit/ suite
+which has the tip of each of the underlying suites
+as an ancestor,
+and which contains the same as the suite which
+has the highest version of the package.
+
+The package must exist in mainsuite,
+but need not exist in the subsuites.
+
+If a specified subsuite starts with
+.B -
+then mainsuite is prepended.
+
+So, for example,
+.B stable,-security
+means to look for the package in stable, and stable-security,
+taking whichever is newer.
+If stable is currently jessie,
+dgit clone would leave you on the branch
+.BR dgit/jessie,-security .
+
+Combined suites are not supported by the dgit build operations.
+This is because those options are intended for building for
+uploading source packages,
+and look in the changelog to find the relevant suite.
+It does not make sense to name a dgit-synthesised combined suite
+in a changelog,
+or to try to upload to it.
+
+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.
+
+The history generated by this feature is not normally suitable
+for merging back into upstreams,
+as it necessarily contains unattractive pseudomerges.

 .SH LIMITATIONS
 Because the synthesis
 of the suite tracking branches
 .SH LIMITATIONS
 Because the synthesis
 of the suite tracking branches