[PATCH v2 1/6] CodingGuidelines: add shell piping guidelines
Add two guidelines:
- pipe characters should appear at the end of lines, and not cause
indentation
- pipes should be avoided when they swallow exit codes that can
potentially fail
---
Documentation/CodingGuidelines | 29 +++++++++++++++++++++++++++++
1 file changed, 29 insertions(+)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 48aa4edfb..7f903c1aa 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -163,6 +163,35 @@ For shell scripts specifically (not exhaustive):
does not have such a problem.
+ - In a piped sequence which spans multiple lines, put each statement
+ on a separate line and put pipes on the end of each line, rather
+ than the start. This means you don't need to use \ to join lines,
+ since | implies a join already. Also, do not indent subsequent
+ lines; if you need a sequence to visually stand apart from the
+ surrounding code, use a blank line before and/or after the piped
+ sequence.
+
+ (incorrect)
+ echo '...' > expected
+ git ls-files -s file.1 file.2 file.3 file.4 file.5 \
+ | awk '{print $1}' \
+ | sort >observed
+ test_cmp expected actual
+
+ (correct)
+ echo '...' > expected
+
+ git ls-files -s file.1 file.2 file.3 file.4 file.5 |
+ awk '{print $1}' |
+ sort >observed
+
+ test_cmp expected actual
+
+ - In a pipe, any non-zero exit codes returned by processes besides
+ the last will be ignored. If there is any possibility some
+ non-final command in the pipe will raise an error, prefer writing
+ the output of that command to a temporary file with '>' rather than
+ pipe it.
For C programs:
--
2.19.0.444.g18242da7ef-goog
Matthew DeVore <matvore@google.com>