summaryrefslogtreecommitdiff
path: root/dgit.7
diff options
context:
space:
mode:
authorIan Jackson <ijackson@chiark.greenend.org.uk>2016-11-08 22:10:28 +0000
committerIan Jackson <ijackson@chiark.greenend.org.uk>2016-11-08 22:10:29 +0000
commitfd6adbbf2635ee146d630248f3129b1a4973b7e1 (patch)
tree1c347a4b959672902763058a24269a8cf8adf834 /dgit.7
parentfd0923f31bbc48c0ba822033b2255115f0cab1ce (diff)
dgit(1), dgit(7): Better reference docs for combined suites.
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
Diffstat (limited to 'dgit.7')
-rw-r--r--dgit.751
1 files changed, 51 insertions, 0 deletions
diff --git a/dgit.7 b/dgit.7
index 6f5844b..f7e50e4 100644
--- 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.
+.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