qdepends: make -qq with -Q just print list of packages

Bug: https://bugs.gentoo.org/683430
Signed-off-by: Fabian Groffen <grobian@gentoo.org>

4 files changed, 41 insertions, 4 deletions

diff --git a/man/include/qdepends-05-examples.include b/man/include/qdepends-05-examples.include
index d3eac01d..98ceb3ab 100644
--- a/man/include/qdepends-05-examples.include
+++ b/man/include/qdepends-05-examples.include
@@ -17,3 +17,20 @@ can quickly see what specific dependency is expressed here.  If
 the above had used \fI<logrotate-3\fR, for example, no matches would be
 returned.  Not using any specifiers allows to reveal in what way a
 dependency is expressed.
+.P
+Producing a list of packages that need rebuilding after a Perl upgrade:
+.nf
+	$ \fIqdepends -Qqq -F '%[CATEGORY]%[PN]%[SLOT]' ^perl:0/5.30\fR
+	dev-vcs/git:0
+	perl-core/File-Temp:0
+	dev-perl/Text-CSV_XS:0
+	...
+.fi
+With the double \fB-q\fR flag, just the matching packages are returned,
+allowing to use the list for instance as arguments to \fBemerge\fR(1).
+The custom formatter in this case ensures all selected packages will be
+the best matching for the currently installed SLOT.  Finally, the use of
+the antislot matching (\fI^\fR) is returning all packages that depend on
+perl in SLOT \fB0\fR, but in a different SUBSLOT than \fB5.30\fR,
+effectively requesting the list of packages that need rebuilding to use
+the newly installed version of Perl.
diff --git a/man/include/qdepends.optdesc.yaml b/man/include/qdepends.optdesc.yaml
index dc4ce91c..f49461ce 100644
--- a/man/include/qdepends.optdesc.yaml
+++ b/man/include/qdepends.optdesc.yaml
@@ -32,4 +32,5 @@ verbose: |
     matches.  When used with \fB-t\fR, the atom highlighting matches
     what is used by the installed package, if available.
 quiet: Suppress DEPEND= output for \fB\-f\fR.  Only print the matching
-    atom for \fB\-Q\fR.
+    atom for \fB\-Q\fR.  When given two or more times, suppresses the
+    matching atom for \fB\-Q\fR, e.g.\ producing just a list of packages.
diff --git a/man/qdepends.1 b/man/qdepends.1
index d7c89575..7898e3de 100644
--- a/man/qdepends.1
+++ b/man/qdepends.1
@@ -92,7 +92,7 @@ matches.  When used with \fB-t\fR, the atom highlighting matches
 what is used by the installed package, if available.
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Suppress DEPEND= output for \fB\-f\fR.  Only print the matching atom for \fB\-Q\fR.
+Suppress DEPEND= output for \fB\-f\fR.  Only print the matching atom for \fB\-Q\fR.  When given two or more times, suppresses the matching atom for \fB\-Q\fR, e.g.\ producing just a list of packages.
 .TP
 \fB\-C\fR, \fB\-\-nocolor\fR
 Don't output color.
@@ -121,6 +121,23 @@ can quickly see what specific dependency is expressed here.  If
 the above had used \fI<logrotate-3\fR, for example, no matches would be
 returned.  Not using any specifiers allows to reveal in what way a
 dependency is expressed.
+.P
+Producing a list of packages that need rebuilding after a Perl upgrade:
+.nf
+	$ \fIqdepends -Qqq -F '%[CATEGORY]%[PN]%[SLOT]' ^perl:0/5.30\fR
+	dev-vcs/git:0
+	perl-core/File-Temp:0
+	dev-perl/Text-CSV_XS:0
+	...
+.fi
+With the double \fB-q\fR flag, just the matching packages are returned,
+allowing to use the list for instance as arguments to \fBemerge\fR(1).
+The custom formatter in this case ensures all selected packages will be
+the best matching for the currently installed SLOT.  Finally, the use of
+the antislot matching (\fI^\fR) is returning all packages that depend on
+perl in SLOT \fB0\fR, but in a different SUBSLOT than \fB5.30\fR,
+effectively requesting the list of packages that need rebuilding to use
+the newly installed version of Perl.
 .SH "REPORTING BUGS"
 Please report bugs via http://bugs.gentoo.org/
 .br
diff --git a/qdepends.c b/qdepends.c
index f5aa5a59..b5e89931 100644
--- a/qdepends.c
+++ b/qdepends.c
@@ -251,13 +251,15 @@ qdepends_results_cb(tree_pkg_ctx *pkg_ctx, void *priv)
 
 						if (!firstmatch) {
 							datom = tree_get_atom(pkg_ctx, true);
-							printf("%s:", atom_format(state->format, datom));
+							printf("%s%s", atom_format(state->format, datom),
+									quiet < 2 ? ":" : "");
 						}
 						firstmatch = true;
 
 						snprintf(buf, sizeof(buf), "%s%s%s",
 								RED, atom_to_string(atom), NORM);
-						add_set_unique(buf, state->udeps, NULL);
+						if (quiet < 2)
+							add_set_unique(buf, state->udeps, NULL);
 					} else if (!quiet) {
 						add_set_unique(atom_to_string(atom),
 								state->udeps, NULL);