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

[Junio C Hamano <gitster@pobox.com>]

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, 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
the construct until Ubuntu 20.04 is fully retired from the machines
that matter.

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