commit: 63e38584600d3292d83a96641bf1e5f75ed54c0d Author: Jernej Jakob <jernej.jakob <AT> gmail <DOT> com> AuthorDate: Tue Jul 22 22:18:51 2025 +0000 Commit: Fabian Groffen <grobian <AT> gentoo <DOT> org> CommitDate: Tue Aug 19 11:58:58 2025 +0000 URL: https://gitweb.gentoo.org/proj/portage-utils.git/commit/?id=63e38584
man: document -F/--format Closes: https://github.com/gentoo/portage-utils/pull/34 Signed-off-by: Jernej Jakob <jernej.jakob <AT> gmail.com> Signed-off-by: Fabian Groffen <grobian <AT> gentoo.org> man/include/qatom.optdesc.yaml | 4 +++- man/include/qcheck.optdesc.yaml | 7 +++++++ man/include/qfile.optdesc.yaml | 8 ++++++++ man/include/qkeyword.optdesc.yaml | 6 ++++++ man/include/qlist.optdesc.yaml | 27 +++++++++++++++++++++++++++ man/include/qlop.optdesc.yaml | 7 +++++++ man/include/qsearch.optdesc.yaml | 8 ++++++++ man/include/qsize.optdesc.yaml | 7 +++++++ man/include/quse.optdesc.yaml | 8 ++++++++ man/include/qwhich.optdesc.yaml | 16 ++++++++++++++++ man/qatom.1 | 6 ++++-- man/qcheck.1 | 9 +++++++-- man/qfile.1 | 8 +++++++- man/qkeyword.1 | 8 ++++++-- man/qlist.1 | 27 ++++++++++++++++++++++++++- man/qlop.1 | 7 ++++++- man/qsearch.1 | 8 +++++++- man/qsize.1 | 7 ++++++- man/quse.1 | 8 +++++++- man/qwhich.1 | 23 +++++++++++++++++++---- 20 files changed, 192 insertions(+), 17 deletions(-) diff --git a/man/include/qatom.optdesc.yaml b/man/include/qatom.optdesc.yaml index e71dfb7..3755562 100644 --- a/man/include/qatom.optdesc.yaml +++ b/man/include/qatom.optdesc.yaml @@ -14,7 +14,9 @@ format: | variables from \fBebuild\fR(5). .RS .IP CATEGORY - The category of the package. + The category of the package. If this field is specified as + \fI%[CATEGORY]\fR and it precedes a subsequent field start symbol, + the field will be suffixed with a \fI/\fR. .IP P The package name and version without the ebuild revision. .IP PN diff --git a/man/include/qcheck.optdesc.yaml b/man/include/qcheck.optdesc.yaml new file mode 100644 index 0000000..cd15520 --- /dev/null +++ b/man/include/qcheck.optdesc.yaml @@ -0,0 +1,7 @@ +format: | + Print matched atom using given format string. + The default is \fI%[CATEGORY]%[PN]\fR or \fI%[CATEGORY]%[PF]\fR in + verbose mode (\fB-v\fR|\fB--verbose\fR). + Note that this only sets the format of the atom field, not the + entire output line. + For more information see \fBqatom\fR(1). diff --git a/man/include/qfile.optdesc.yaml b/man/include/qfile.optdesc.yaml index 249da71..fd0a7e4 100644 --- a/man/include/qfile.optdesc.yaml +++ b/man/include/qfile.optdesc.yaml @@ -15,3 +15,11 @@ follow: | locations which contain a symlink traversal, e.g. /bin/bash. By default only the input arguments are resolved to make an exact match with the VDB. Turning this option on may affect performance. +format: | + Print matched atom using given format string. + The default is \fI%[CATEGORY]%[PN]\fR or \fI%[CATEGORY]%[PF]\fR in + verbose mode (\fB-v\fR|\fB--verbose\fR). + If \fB-S\fR|\fB--slot\fR is set, \fI%[SLOT]\fR will be appended. + Note that this only sets the format of the atom field, not the + entire output line. + For more information see \fBqatom\fR(1). diff --git a/man/include/qkeyword.optdesc.yaml b/man/include/qkeyword.optdesc.yaml new file mode 100644 index 0000000..ecbaaae --- /dev/null +++ b/man/include/qkeyword.optdesc.yaml @@ -0,0 +1,6 @@ +format: | + Print matched atom using given format string. + The default is \fI%[CATEGORY]%[PF]\fR. + Note that this only sets the format of the atom field, not the + entire output line. + For more information see \fBqatom\fR(1). diff --git a/man/include/qlist.optdesc.yaml b/man/include/qlist.optdesc.yaml index 0ae0700..8cfe273 100644 --- a/man/include/qlist.optdesc.yaml +++ b/man/include/qlist.optdesc.yaml @@ -27,3 +27,30 @@ verbose: | When listing the package contents, \fB\-v\fR displays symlinks with an arrow (\->) to their target. Shows disabled USE-flags when used with \fB\-U\fR. +format: | + Print matched atom using given format string. + + The default base format is: + \fI%[CATEGORY]%[PN]\fR + .br + If \fB-v\fR|\fB--verbose\fR the base format is instead: + \fI%[CATEGORY]%[PF]\fR + .br + + If \fB-k\fR|\fB--binpkgs\fR is set: + \fI%[BUILDID]\fR is appended + .br + If \fB-S\fR|\fB--slots\fR is set once: + \fI%[SLOT]\fR is appended + .br + If \fB-S\fR|\fB--slots\fR is set twice: + \fI%[SUBSLOT]\fR is appended + .br + If \fB-R\fR|\fB--repo\fR is set: + \fI%[REPO]\fR is appended + .br + + Note that this only sets the format of the atom field, not the + entire output line. + + For more information see \fBqatom\fR(1). diff --git a/man/include/qlop.optdesc.yaml b/man/include/qlop.optdesc.yaml index fc268d6..8ebb7d9 100644 --- a/man/include/qlop.optdesc.yaml +++ b/man/include/qlop.optdesc.yaml @@ -68,3 +68,10 @@ emerge: | It is possible to combine this flag with the \fB-d\fR flag, in which case the default behaviour of displaying the last merge (\fB-l\fR) is disabled. +format: | + Print matched atom using given format string. + The default is \fI%[CATEGORY]%[PN]\fR or \fI%[CATEGORY]%[PF]\fR in + verbose mode (\fB-v\fR|\fB--verbose\fR). + Note that this only sets the format of the atom field, not the + entire output line. + For more information see \fBqatom\fR(1). diff --git a/man/include/qsearch.optdesc.yaml b/man/include/qsearch.optdesc.yaml index 9bbaeaa..962405a 100644 --- a/man/include/qsearch.optdesc.yaml +++ b/man/include/qsearch.optdesc.yaml @@ -1,2 +1,10 @@ verbose: Ignored for compatibility with other qapplets. quiet: Ignored for compatibility with other qapplets. +format: | + Print matched atom using given format string. + The default is \fI%[CATEGORY]%[PN]\fR or \fI%[CATEGORY]%[PF]\fR in + verbose mode (\fB-v\fR|\fB--verbose\fR). + If \fB-R\fR|\fB--repo\fR is set, \fI%[REPO]\fR will be appended. + Note that this only sets the format of the atom field, not the + entire output line. + For more information see \fBqatom\fR(1). diff --git a/man/include/qsize.optdesc.yaml b/man/include/qsize.optdesc.yaml index 8dd58e4..998750c 100644 --- a/man/include/qsize.optdesc.yaml +++ b/man/include/qsize.optdesc.yaml @@ -3,3 +3,10 @@ ignore: | expression, before calculating size. verbose: Ignored for compatibility with other qapplets. quiet: Ignored for compatibility with other qapplets. +format: | + Print matched atom using given format string. + The default is \fI%[CATEGORY]%[PN]\fR or \fI%[CATEGORY]%[PF]\fR in + verbose mode (\fB-v\fR|\fB--verbose\fR). + Note that this only sets the format of the atom field, not the + entire output line. + For more information see \fBqatom\fR(1). diff --git a/man/include/quse.optdesc.yaml b/man/include/quse.optdesc.yaml index 71fcd2d..93bca9e 100644 --- a/man/include/quse.optdesc.yaml +++ b/man/include/quse.optdesc.yaml @@ -9,3 +9,11 @@ describe: | \fB-p\fR, lists all USE-flags with their descriptions (and enabled state prefixed with an asterisk when used with \fB-I\fR) per package. +format: | + Print matched atom using given format string. + The default is \fI%[CATEGORY]%[PN]\fR or \fI%[CATEGORY]%[PF]\fR in + verbose mode (\fB-v\fR|\fB--verbose\fR). + If \fB-R\fR|\fB--repo\fR is set, \fI%[REPO]\fR will be appended. + Note that this only sets the format of the atom field, not the + entire output line. + For more information see \fBqatom\fR(1). diff --git a/man/include/qwhich.optdesc.yaml b/man/include/qwhich.optdesc.yaml new file mode 100644 index 0000000..4cfefcb --- /dev/null +++ b/man/include/qwhich.optdesc.yaml @@ -0,0 +1,16 @@ +format: | + Print matched atom using given format string. + + Setting this option has the effect of also setting + \fB-p\fR|\fB--pretty\fR. + + Note that this only sets the format of the atom field, not the + entire output line. + + For more information see \fBqatom\fR(1). +pretty: | + Print (pretty) atom instead of path. + + The default print format is \fI%[CATEGORY]%[PN]\fR or + \fI%[CATEGORY]%[PF]\fR in verbose mode (\fB-v\fR|\fB--verbose\fR). + The format can be changed with \fB-F\fR|\fB--format\fR. diff --git a/man/qatom.1 b/man/qatom.1 index cb1c972..4d02002 100644 --- a/man/qatom.1 +++ b/man/qatom.1 @@ -1,5 +1,5 @@ .\" generated by mkman.py, please do NOT edit! -.TH qatom "1" "Jan 2024" "Gentoo Foundation" "qatom" +.TH qatom "1" "Aug 2025" "Gentoo Foundation" "qatom" .SH NAME qatom \- split atom strings .SH SYNOPSIS @@ -39,7 +39,9 @@ The following fields are supported, which are inline with the variables from \fBebuild\fR(5). .RS .IP CATEGORY -The category of the package. +The category of the package. If this field is specified as +\fI%[CATEGORY]\fR and it precedes a subsequent field start symbol, +the field will be suffixed with a \fI/\fR. .IP P The package name and version without the ebuild revision. .IP PN diff --git a/man/qcheck.1 b/man/qcheck.1 index 2c7234c..b4eea48 100644 --- a/man/qcheck.1 +++ b/man/qcheck.1 @@ -1,5 +1,5 @@ .\" generated by mkman.py, please do NOT edit! -.TH qcheck "1" "Jan 2024" "Gentoo Foundation" "qcheck" +.TH qcheck "1" "Aug 2025" "Gentoo Foundation" "qcheck" .SH NAME qcheck \- verify integrity of installed packages .SH SYNOPSIS @@ -10,7 +10,12 @@ qcheck \- verify integrity of installed packages .SH OPTIONS .TP \fB\-F\fR \fI<arg>\fR, \fB\-\-format\fR \fI<arg>\fR -Custom output format (default: %[CATEGORY]%[PN]). +Print matched atom using given format string. +The default is \fI%[CATEGORY]%[PN]\fR or \fI%[CATEGORY]%[PF]\fR in +verbose mode (\fB-v\fR|\fB--verbose\fR). +Note that this only sets the format of the atom field, not the +entire output line. +For more information see \fBqatom\fR(1). .TP \fB\-s\fR \fI<arg>\fR, \fB\-\-skip\fR \fI<arg>\fR Ignore files matching the regular expression <arg>. diff --git a/man/qfile.1 b/man/qfile.1 index 204f55d..5d57d89 100644 --- a/man/qfile.1 +++ b/man/qfile.1 @@ -1,5 +1,5 @@ .\" generated by mkman.py, please do NOT edit! -.TH qfile "1" "Apr 2025" "Gentoo Foundation" "qfile" +.TH qfile "1" "Aug 2025" "Gentoo Foundation" "qfile" .SH NAME qfile \- list all pkgs owning files .SH SYNOPSIS @@ -37,6 +37,12 @@ renamed to \fB-d\fR. .TP \fB\-F\fR \fI<arg>\fR, \fB\-\-format\fR \fI<arg>\fR Print matched atom using given format string. +The default is \fI%[CATEGORY]%[PN]\fR or \fI%[CATEGORY]%[PF]\fR in +verbose mode (\fB-v\fR|\fB--verbose\fR). +If \fB-S\fR|\fB--slot\fR is set, \fI%[SLOT]\fR will be appended. +Note that this only sets the format of the atom field, not the +entire output line. +For more information see \fBqatom\fR(1). .TP \fB\-L\fR, \fB\-\-follow\fR Follow symlinks in both input as well as VDB stored entries. This diff --git a/man/qkeyword.1 b/man/qkeyword.1 index fc81e2c..a1a4c67 100644 --- a/man/qkeyword.1 +++ b/man/qkeyword.1 @@ -1,5 +1,5 @@ .\" generated by mkman.py, please do NOT edit! -.TH qkeyword "1" "Jan 2024" "Gentoo Foundation" "qkeyword" +.TH qkeyword "1" "Aug 2025" "Gentoo Foundation" "qkeyword" .SH NAME qkeyword \- list packages based on keywords .SH SYNOPSIS @@ -65,7 +65,11 @@ list latest stable version per package for <arch>. list latest testing version per package for <arch>. .TP \fB\-F\fR \fI<arg>\fR, \fB\-\-format\fR \fI<arg>\fR -Print latest atom using given format string. +Print matched atom using given format string. +The default is \fI%[CATEGORY]%[PF]\fR. +Note that this only sets the format of the atom field, not the +entire output line. +For more information see \fBqatom\fR(1). .TP \fB\-\-root\fR \fI<arg>\fR Set the ROOT env var. diff --git a/man/qlist.1 b/man/qlist.1 index e0e9e81..9496f35 100644 --- a/man/qlist.1 +++ b/man/qlist.1 @@ -1,5 +1,5 @@ .\" generated by mkman.py, please do NOT edit! -.TH qlist "1" "Sep 2024" "Gentoo Foundation" "qlist" +.TH qlist "1" "Aug 2025" "Gentoo Foundation" "qlist" .SH NAME qlist \- list files owned by pkgname .SH SYNOPSIS @@ -64,6 +64,31 @@ Only show symlinks. .TP \fB\-F\fR \fI<arg>\fR, \fB\-\-format\fR \fI<arg>\fR Print matched atom using given format string. + +The default base format is: + \fI%[CATEGORY]%[PN]\fR +.br +If \fB-v\fR|\fB--verbose\fR the base format is instead: + \fI%[CATEGORY]%[PF]\fR +.br + +If \fB-k\fR|\fB--binpkgs\fR is set: + \fI%[BUILDID]\fR is appended +.br +If \fB-S\fR|\fB--slots\fR is set once: + \fI%[SLOT]\fR is appended +.br +If \fB-S\fR|\fB--slots\fR is set twice: + \fI%[SUBSLOT]\fR is appended +.br +If \fB-R\fR|\fB--repo\fR is set: + \fI%[REPO]\fR is appended +.br + +Note that this only sets the format of the atom field, not the +entire output line. + +For more information see \fBqatom\fR(1). .TP \fB\-\-root\fR \fI<arg>\fR Set the ROOT env var. diff --git a/man/qlop.1 b/man/qlop.1 index 379f3c6..19d4f78 100644 --- a/man/qlop.1 +++ b/man/qlop.1 @@ -1,5 +1,5 @@ .\" generated by mkman.py, please do NOT edit! -.TH qlop "1" "Jan 2024" "Gentoo Foundation" "qlop" +.TH qlop "1" "Aug 2025" "Gentoo Foundation" "qlop" .SH NAME qlop \- emerge log analyzer .SH SYNOPSIS @@ -131,6 +131,11 @@ Read package atoms to report from file. .TP \fB\-F\fR \fI<arg>\fR, \fB\-\-format\fR \fI<arg>\fR Print matched atom using given format string. +The default is \fI%[CATEGORY]%[PN]\fR or \fI%[CATEGORY]%[PF]\fR in +verbose mode (\fB-v\fR|\fB--verbose\fR). +Note that this only sets the format of the atom field, not the +entire output line. +For more information see \fBqatom\fR(1). .TP \fB\-\-root\fR \fI<arg>\fR Set the ROOT env var. diff --git a/man/qsearch.1 b/man/qsearch.1 index 8c56216..d2e430b 100644 --- a/man/qsearch.1 +++ b/man/qsearch.1 @@ -1,5 +1,5 @@ .\" generated by mkman.py, please do NOT edit! -.TH qsearch "1" "Jan 2024" "Gentoo Foundation" "qsearch" +.TH qsearch "1" "Aug 2025" "Gentoo Foundation" "qsearch" .SH NAME qsearch \- search pkgname/desc .SH SYNOPSIS @@ -31,6 +31,12 @@ Show repository the ebuild originates from. .TP \fB\-F\fR \fI<arg>\fR, \fB\-\-format\fR \fI<arg>\fR Print matched atom using given format string. +The default is \fI%[CATEGORY]%[PN]\fR or \fI%[CATEGORY]%[PF]\fR in +verbose mode (\fB-v\fR|\fB--verbose\fR). +If \fB-R\fR|\fB--repo\fR is set, \fI%[REPO]\fR will be appended. +Note that this only sets the format of the atom field, not the +entire output line. +For more information see \fBqatom\fR(1). .TP \fB\-\-root\fR \fI<arg>\fR Set the ROOT env var. diff --git a/man/qsize.1 b/man/qsize.1 index b701476..eaa3d9f 100644 --- a/man/qsize.1 +++ b/man/qsize.1 @@ -1,5 +1,5 @@ .\" generated by mkman.py, please do NOT edit! -.TH qsize "1" "Jan 2024" "Gentoo Foundation" "qsize" +.TH qsize "1" "Aug 2025" "Gentoo Foundation" "qsize" .SH NAME qsize \- calculate size usage .SH SYNOPSIS @@ -35,6 +35,11 @@ expression, before calculating size. .TP \fB\-F\fR \fI<arg>\fR, \fB\-\-format\fR \fI<arg>\fR Print matched atom using given format string. +The default is \fI%[CATEGORY]%[PN]\fR or \fI%[CATEGORY]%[PF]\fR in +verbose mode (\fB-v\fR|\fB--verbose\fR). +Note that this only sets the format of the atom field, not the +entire output line. +For more information see \fBqatom\fR(1). .TP \fB\-\-root\fR \fI<arg>\fR Set the ROOT env var. diff --git a/man/quse.1 b/man/quse.1 index 2263b1a..aa7f071 100644 --- a/man/quse.1 +++ b/man/quse.1 @@ -1,5 +1,5 @@ .\" generated by mkman.py, please do NOT edit! -.TH quse "1" "Jan 2024" "Gentoo Foundation" "quse" +.TH quse "1" "Aug 2025" "Gentoo Foundation" "quse" .SH NAME quse \- find pkgs using useflags .SH SYNOPSIS @@ -36,6 +36,12 @@ Show repository the ebuild originates from. .TP \fB\-F\fR \fI<arg>\fR, \fB\-\-format\fR \fI<arg>\fR Print matched atom using given format string. +The default is \fI%[CATEGORY]%[PN]\fR or \fI%[CATEGORY]%[PF]\fR in +verbose mode (\fB-v\fR|\fB--verbose\fR). +If \fB-R\fR|\fB--repo\fR is set, \fI%[REPO]\fR will be appended. +Note that this only sets the format of the atom field, not the +entire output line. +For more information see \fBqatom\fR(1). .TP \fB\-\-root\fR \fI<arg>\fR Set the ROOT env var. diff --git a/man/qwhich.1 b/man/qwhich.1 index b97d442..ceb18a5 100644 --- a/man/qwhich.1 +++ b/man/qwhich.1 @@ -1,5 +1,5 @@ .\" generated by mkman.py, please do NOT edit! -.TH qwhich "1" "Jan 2024" "Gentoo Foundation" "qwhich" +.TH qwhich "1" "Aug 2025" "Gentoo Foundation" "qwhich" .SH NAME qwhich \- find path to pkg .SH SYNOPSIS @@ -33,12 +33,19 @@ Look at binary packages. Look in main tree and overlays. .TP \fB\-p\fR, \fB\-\-pretty\fR -Print (pretty) atom instead of path for use with -F. +Print (pretty) atom instead of path. + +The default print format is \fI%[CATEGORY]%[PN]\fR or +\fI%[CATEGORY]%[PF]\fR in verbose mode (\fB-v\fR|\fB--verbose\fR). +The format can be changed with \fB-F\fR|\fB--format\fR. .TP \fB\-d\fR, \fB\-\-dir\fR Print directory instead of path. .TP -\fB\-R\fR, \fB\-\-repo\fR +\fB\-r\fR \fI<arg>\fR, \fB\-\-repo\fR \fI<arg>\fR +Only look in given repo. +.TP +\fB\-R\fR, \fB\-\-printrepo\fR Print repository name instead of path for tree/overlay matches. .TP \fB\-f\fR, \fB\-\-first\fR @@ -54,7 +61,15 @@ Skip virtual category. Skip acct-user and acct-group categories. .TP \fB\-F\fR \fI<arg>\fR, \fB\-\-format\fR \fI<arg>\fR -Print matched using given format string. +Print matched atom using given format string. + +Setting this option has the effect of also setting +\fB-p\fR|\fB--pretty\fR. + +Note that this only sets the format of the atom field, not the +entire output line. + +For more information see \fBqatom\fR(1). .TP \fB\-\-root\fR \fI<arg>\fR Set the ROOT env var.
