git: a0dfb0668b45 - main - env: Improve documentation.

The branch main has been updated by des:

URL: https://cgit.FreeBSD.org/src/commit/?id=a0dfb0668b45506de97beb4c7acbe3fd1ba69fc8

commit a0dfb0668b45506de97beb4c7acbe3fd1ba69fc8
Author:     Dag-Erling Smørgrav <des@FreeBSD.org>
AuthorDate: 2024-10-07 21:00:38 +0000
Commit:     Dag-Erling Smørgrav <des@FreeBSD.org>
CommitDate: 2024-10-07 21:01:09 +0000

    env: Improve documentation.
    
    * The `env` utility's inability to run a command whose name contains an
      equal sign is a feature, not a bug, so move that paragraph up from the
      BUGS section to the DESCRIPTION section.
    
    * Mention that this can be worked around by prefixing the command name
      with `command`, and add an example of this to the EXAMPLE section.
    
    * Add a test case which verifies that `env` does not run a command with
      an equal sign in its name even if it exists, and also demonstrates the
      workaround.
    
    MFC after:      3 days
    Sponsored by:   Klara, Inc.
    Reviewed by:    markj
    Differential Revision:  https://reviews.freebsd.org/D46997
---
 usr.bin/env/env.1             | 28 +++++++++++++++++++---------
 usr.bin/env/tests/env_test.sh | 20 ++++++++++++++++++++
 2 files changed, 39 insertions(+), 9 deletions(-)

diff --git a/usr.bin/env/env.1 b/usr.bin/env/env.1
index 2b98ef40d053..5581d3838a7b 100644
--- a/usr.bin/env/env.1
+++ b/usr.bin/env/env.1
@@ -28,7 +28,7 @@
 .\" SUCH DAMAGE.
 .\" From FreeBSD: src/usr.bin/printenv/printenv.1,v 1.17 2002/11/26 17:33:35 ru Exp
 .\"
-.Dd March 3, 2021
+.Dd October 7, 2024
 .Dt ENV 1
 .Os
 .Sh NAME
@@ -171,6 +171,19 @@ Both
 and
 .Ar utility
 may not be specified together.
+.Pp
+The
+.Nm
+utility does not handle values of
+.Ar utility
+which have an equals sign
+.Pq Ql =
+in their name, for obvious reasons.
+This can easily be worked around by interposing the
+.Xr command 1
+utility, which simply executes its arguments; see
+.Sx EXAMPLES
+below.
 .\"
 .Ss Details of -S (split-string) processing
 The processing of the
@@ -469,6 +482,11 @@ and
 options:
 .Pp
 .Dl "#!/usr/bin/env -S-P/usr/local/bin:/usr/bin:${PATH} perl"
+.Pp
+To execute a utility with an equal sign in its name:
+.Bd -literal -offset indent
+env name=value ... command foo=bar arg ...
+.Ed
 .Sh COMPATIBILITY
 The
 .Nm
@@ -514,14 +532,6 @@ options were added in
 .Sh BUGS
 The
 .Nm
-utility does not handle values of
-.Ar utility
-which have an equals sign
-.Pq Ql =
-in their name, for obvious reasons.
-.Pp
-The
-.Nm
 utility does not take multibyte characters into account when
 processing the
 .Fl S
diff --git a/usr.bin/env/tests/env_test.sh b/usr.bin/env/tests/env_test.sh
index 7568f81ab603..da238caaf7fa 100644
--- a/usr.bin/env/tests/env_test.sh
+++ b/usr.bin/env/tests/env_test.sh
@@ -89,6 +89,25 @@ altpath_body()
 		  env -P "${PWD}" magic_words
 }
 
+atf_test_case equal
+equal_head()
+{
+	atf_set "descr" "Command name contains equal sign"
+}
+equal_body()
+{
+	echo "echo ${magic_words}" >"magic=words"
+	chmod 0755 "magic=words"
+	atf_check -o match:"^${PWD}/magic=words$" \
+		  env "${PWD}/magic=words"
+	atf_check -o match:"^magic=words$" \
+		  env -P "${PATH}:${PWD}" "magic=words"
+	atf_check -o inline:"${magic_words}\n" \
+		  env command "${PWD}/magic=words"
+	atf_check -o inline:"${magic_words}\n" \
+		  env PATH="${PATH}:${PWD}" command "magic=words"
+}
+
 atf_init_test_cases()
 {
 	atf_add_test_case basic
@@ -97,4 +116,5 @@ atf_init_test_cases()
 	atf_add_test_case true
 	atf_add_test_case false
 	atf_add_test_case altpath
+	atf_add_test_case equal
 }