forall: Clarify expansion of REPO_ environment values with -c
If a user executes:
repo forall -c echo $REPO_PROJECT
then $REPO_NAME is expanded by the user's shell first, and passed
as $1 to the shell that executes echo. This will either result in
no output, or output of whatever REPO_NAME is set to in the user's
shell. Either way, this is an unexpected result.
The correct way to do it is:
repo forall -c 'echo $REPO_PROJECT'
such that $REPO_NAME is passed in to the shell literally, and then
expanded to the value set in the environment that was passed to
the shell.
Update the documentation to make this clearer.
Change-Id: I713caee914172ad8d8f0fafacd27026502436f0d
diff --git a/subcmds/forall.py b/subcmds/forall.py
index 2c12c55..52eb5e2 100644
--- a/subcmds/forall.py
+++ b/subcmds/forall.py
@@ -104,6 +104,13 @@
shell positional arguments ($1, $2, .., $#) are set to any arguments
following <command>.
+Example: to list projects:
+
+ %prog% forall -c 'echo $REPO_PROJECT'
+
+Notice that $REPO_PROJECT is quoted to ensure it is expanded in
+the context of running <command> instead of in the calling shell.
+
Unless -p is used, stdin, stdout, stderr are inherited from the
terminal and are not redirected.
