diff options
| -rw-r--r-- | debian/changelog | 1 | ||||
| -rw-r--r-- | dgit.1 | 25 | ||||
| -rw-r--r-- | dgit.7 | 51 |
3 files changed, 56 insertions, 21 deletions
diff --git a/debian/changelog b/debian/changelog index 348f5ae..2136b8b 100644 --- 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. + * dgit(1), dgit(7): Better reference docs for combined suites. Test suite: * Replace make in Test-Depends with build-essential. Most of the tests @@ -74,23 +74,9 @@ for the distro to which 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 @@ -109,10 +95,7 @@ then dgit fetch defaults to .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 @@ -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 |