dgit-user(7): Explain comma notation better.

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index a26f6bc0dea545af6d7742829fd6303f7d4e27e3..f2821dffd32ba6172bfcc203674065c1ebb29150 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -38,8 +38,8 @@ lb l.
 dgit-user(7)   for users: editing, building and sharing packages
 dgit-nmu-simple(7)     for DDs: doing a straightforward NMU
 dgit-maint-native(7)   for maintainers of Debian-native packages
 dgit-user(7)   for users: editing, building and sharing packages
 dgit-nmu-simple(7)     for DDs: doing a straightforward NMU
 dgit-maint-native(7)   for maintainers of Debian-native packages

-dgit-maint-merge(7)    for maintainers: using a merging git workflow
-dgit-maint-gbp(7)      for maintainers: using git-buildpackage
+dgit-maint-merge(7)    for maintainers who want a pure git workflow
+dgit-maint-gbp(7)      for maintainers already using git-buildpackage

 dgit-sponsorship(7)    for sponsors and sponsored contributors
 .TE
 .LP
 dgit-sponsorship(7)    for sponsors and sponsored contributors
 .TE
 .LP


@@ -73,6 +73,25 @@ for the distro to which
 .I suite
 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.
+

 For your convenience, the
 .B vcs-git
 remote will be set up from the package's Vcs-Git field, if there is
 For your convenience, the
 .B vcs-git
 remote will be set up from the package's Vcs-Git field, if there is


@@ -90,6 +109,10 @@ 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.

 .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


@@ -710,6 +733,8 @@ Specifies a single additional option to pass to
 .BR sbuild ,
 .BR ssh ,
 .BR dgit ,
 .BR sbuild ,
 .BR ssh ,
 .BR dgit ,

+.BR apt-get ,
+.BR apt-cache ,

 .BR gbp-pq ,
 .BR gbp-build ,
 or
 .BR gbp-pq ,
 .BR gbp-build ,
 or


@@ -755,6 +780,8 @@ Specifies alternative programs to use instead of
 .BR gpg ,
 .BR ssh ,
 .BR dgit ,
 .BR gpg ,
 .BR ssh ,
 .BR dgit ,

+.BR apt-get ,
+.BR apt-cache ,

 .BR git ,
 .BR gbp-pq ,
 .BR gbp-build ,
 .BR git ,
 .BR gbp-pq ,
 .BR gbp-build ,


@@ -879,6 +906,9 @@ Settings likely to be useful for an end user include:
 Specifies the distro for a suite.  dgit keys off the suite name (which
 appears in changelogs etc.), and uses that to determine the distro
 which is involved.  The config used is thereafter that for the distro.
 Specifies the distro for a suite.  dgit keys off the suite name (which
 appears in changelogs etc.), and uses that to determine the distro
 which is involved.  The config used is thereafter that for the distro.

+
+.I suite
+may be a glob pattern.

 .TP
 .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.