X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.7;h=584632cb24d8a3075b36d8a008cf6711fcb53ca9;hp=6f5844b4e694c19a187e3f0c29b699f55702a9a4;hb=68d88a087c25d9e1cee7106938ab4e9751cfa146;hpb=cb809d942c58dea5dfba6ad8b7e3298338ebb24e;ds=sidebyside

diff --git a/dgit.7 b/dgit.7
index 6f5844b4..584632cb 100644
--- a/dgit.7
+++ b/dgit.7
@@ -56,8 +56,11 @@ server to authenticate pushes.
 Uploads made by dgit contain an additional field
 .B Dgit
 in the source package .dsc.  (This is added by dgit push.)
-This specifies a commit (an ancestor of the dgit/suite
-branch) whose tree is identical to the unpacked source upload.
+This specifies: a commit (an ancestor of the dgit/suite
+branch) whose tree is identical to the unpacked source upload;
+and the distro and suite to which the upload was made
+(and a url,
+in case the client seeing this .dsc does not know of that distro).
 
 Uploads not made by dgit are represented in git by commits which are
 synthesised by dgit.  The tree of each such commit corresponds to the
@@ -112,6 +115,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.
+.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