Suggest using $@ with ctx.actions.run_shell()
The previous wording said Args objects of unknown size are never useful because they screw up the indices. But they can still be useful in conjunction with $@.
RELNOTES: None
@@ -346,10 +346,12 @@ public interface SkylarkActionFactoryApi extends SkylarkValue {
+ "<a href=\"actions.html#args\"><code>actions.args()</code></a> objects."
+ ""
+ "<p>Bazel passes the elements in this attribute as arguments to the command."
- + "The command can access these arguments as <code>$1</code>, <code>$2</code>, "
- + "etc. Args objects are flattened before indexing. It is generally not useful "
- + "to have an Args object of unknown size in this list, since that means all "
- + "strings in or after that Args object will be at unpredictable indices."
+ + "The command can access these arguments using shell variable substitutions "
+ + "such as <code>$1</code>, <code>$2</code>, etc. Note that since Args "
+ + "objects are flattened before indexing, if there is an Args object of "
+ + "unknown size then all subsequent strings will be at unpredictable indices. "
+ + "It may be useful to use <code>$@</code> (to retrieve all arguments) in "
+ + "conjunction with Args objects of indeterminate size."
+ ""
+ "<p>In the case where <code>command</code> is a list of strings, this "
+ "parameter may not be used."),
@@ -381,9 +383,10 @@ public interface SkylarkActionFactoryApi extends SkylarkValue {
+ "any <a href=\"actions.html#args\"><code>actions.args()</code></a> objects, "
+ "their contents are appended one by one to the command line, so "
+ "<code>$</code><i>i</i> can refer to individual strings within an Args "
- + "object. Note that it is not useful to pass an Args object of unknown size "
- + "as part of <code>arguments</code>, since then the strings would not be at "
- + "known indices."
+ + "object. Note that if an Args object of unknown size is passed as part of "
+ + "<code>arguments</code>, then the strings will be at unknown indices; in "
+ + "this case the <code>$@</code> shell substitution (retrieve all arguments) "
+ + "may be useful."
+ ""
+ "<p><b>(Deprecated)</b> If <code>command</code> is a sequence of strings, "
+ "the first item is the executable to run and the remaining items are its "
