[PATCH v2] CodingGuidelines: document a shell that "fails" "VAR=VAL shell_func"

From

Junio C Hamano <gitster@pobox.com>

Date

Jul 22, 2024, 23:10 UTC

Message-ID

<xmqqjzhd81la.fsf@gitster.g>

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/CodingGuidelines | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 1d92b2da03..203ef49364 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -204,6 +204,30 @@ For shell scripts specifically (not exhaustive):
 	local variable="$value"
 	local variable="$(command args)"
 
+ - The common construct
+
+	VAR=VAL command args
+
+   to temporarily set and export environment variable VAR only while
+   "command args" is running is handy, but some versions of dash (like
+   0.5.10.2-6 found on Ubuntu 20.04) makes a temporary assignment
+   without exporting the variable, when command is *not* an external
+   command.  Do not use it for shell functions.  A common workaround
+   is to do an explicit export in a subshell, like so:
+
+	(incorrect)
+	VAR=VAL func args
+
+	(correct)
+	(
+		VAR=VAL &&
+		export VAR &&
+		func args
+	)
+
+   but be careful that the effect "func" makes to the variables in the
+   current shell will be lost across the subshell boundary.
+
  - Use octal escape sequences (e.g. "\302\242"), not hexadecimal (e.g.
    "\xc2\xa2") in printf format strings, since hexadecimal escape
    sequences are not portable.

Range-diff:
1:  78a3847e80 ! 1:  75d07c05c7 CodingGuidelines: give an example shell that "fails" "VAR=VAL shell_func"
    @@ Metadata
     Author: Junio C Hamano <gitster@pobox.com>
     
      ## Commit message ##
    -    CodingGuidelines: give an example shell that "fails" "VAR=VAL shell_func"
    +    CodingGuidelines: document a shell that "fails" "VAR=VAL shell_func"
     
         Over the years, we accumulated the community wisdom to avoid the
         common "one-short export" construct for shell functions, but seem to
         have lost on which exact platform it is known to fail.  Now during
    -    an investigation on a breakage for a recent topic, let's document
    -    one example of failing shell.
    +    an investigation on a breakage for a recent topic, we found one
    +    example of failing shell.  Let's document that.
     
         This does *not* mean that we can freely start using the construct
         once Ubuntu 20.04 is retired.  But it does mean that we cannot use
    @@ Documentation/CodingGuidelines: For shell scripts specifically (not exhaustive):
     +
     +	(correct)
     +	(
    -+		VAR=VAL && export VAR &&
    ++		VAR=VAL &&
    ++		export VAR &&
     +		func args
     +	)
     +

-- 
2.46.0-rc1-52-g816ffef0a1