commit: 938557a8074f147f16f1e85fb3570d14e6847122
Author: Florian Schmaus <flow <AT> gentoo <DOT> org>
AuthorDate: Sat Feb 1 15:49:15 2025 +0000
Commit: Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Thu Sep 11 00:07:14 2025 +0000
URL: https://gitweb.gentoo.org/proj/portage.git/commit/?id=938557a8
ebuild.5: document 'pipestatus' and 'assert' being deprecated
The 'pipestatus' command was added with 4917a7da16ac ("EAPI 9 has
pipestatus") but unfortunately no documentation was added to the
ebuild(5) man page. Add the missing documentation.
Bug: https://bugs.gentoo.org/566342
Signed-off-by: Florian Schmaus <flow <AT> gentoo.org>
Part-of: https://github.com/gentoo/portage/pull/1453
Closes: https://github.com/gentoo/portage/pull/1453
Signed-off-by: Sam James <sam <AT> gentoo.org>
man/ebuild.5 | 37 ++++++++++++++++++++++++++++++++++---
1 file changed, 34 insertions(+), 3 deletions(-)
diff --git a/man/ebuild.5 b/man/ebuild.5
index b83ea46e17..c82161e10a 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -1085,10 +1085,41 @@ default_src_test
.SS "General:"
.TP
+.B pipestatus\fR \fI[-v]
+Since \fBEAPI 9\fR: Checks the PIPESTATUS array, i.e., the exit status
+of the command(s) in the most recently executed foreground pipeline.
+Returns the last non-zero-element of PIPESTATUS, or zero if all are
+zero. If called with option -v, also outputs the PIPESTATUS array.
+In its simplest form it can be called like this:
+.RS
+.TP
+.I Example:
+.nf
+foo | bar
+pipestatus || die
+.fi
+.RE
+.IP
+Using the -v option allows to save the value of the PIPESTATUS array
+for later diagnostics:
+.RS
+.TP
+.I Example:
+.nf
+local status
+foo | bar
+status=$(pipestatus -v) || die "foo | bar failed, PIPESTATUS: ${status}"
+.fi
+.RE
+.IP
+Note that pipestatus must be the next command following the pipeline.
+In particular, the "local status" declaration must be before the
+pipeline, otherwise it would reset PIPESTATUS.
+.TP
.B assert\fR \fI[reason]
-Checks the value of the shell's PIPESTATUS array variable, and if any
-component is non-zero (indicating failure), calls die with \fIreason\fR
-as a failure message.
+Until \fBEAPI 8\fR. Checks the value of the shell's PIPESTATUS array
+variable, and if any component is non-zero (indicating failure), calls
+die with \fIreason\fR as a failure message.
.TP
.B die\fR \fI[reason]
Causes the current emerge process to be aborted. The final display will
