docs: add bash array pattern for variadic args

[jdx]

Summary

Documents how to properly convert variadic args (var=#true) to bash arrays using the pattern:

eval "arr=($usage_var)"

This handles arguments with spaces correctly.

Example

# Given: usage_files="arg1 'arg with space' arg3"

# Convert to bash array:
eval "files=($usage_files)"

# Now use as array:
for f in "${files[@]}"; do
  echo "Processing: $f"
done

This addresses the common issue where users struggle to handle variadic args with spaces in bash scripts.

Related: #189

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only change; no runtime behavior is modified. Low risk aside from potentially encouraging unsafe eval usage if misapplied.

Overview
Adds a new “Using Variadic Args in Bash” section to docs/spec/reference/arg.md describing how var=#true values are exposed via usage_<name> and providing a Bash snippet (eval "files=($usage_files)") to safely iterate/pass variadic args that may contain spaces.

^{Written by Cursor Bugbot for commit d23303c. This will update automatically on new commits. Configure here.}

[gemini-code-assist]

Summary of Changes

Hello @jdx, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the documentation by providing a new section that clarifies the process of handling variadic arguments in bash scripts. It specifically addresses the common challenge of correctly parsing arguments that contain spaces by providing a robust method for converting the usage_<name> environment variable into a bash array.

Highlights

• Documentation Update: A new section has been added to the docs/spec/reference/arg.md file.
• Variadic Args in Bash: The documentation now includes guidance on how to properly use variadic arguments (var=#true) within bash scripts.
• Handling Spaces in Arguments: A specific pattern using eval "arr=($usage_var)" is demonstrated to convert shell-escaped strings into bash arrays, ensuring correct handling of arguments that contain spaces.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[Copilot]

Pull request overview

This PR adds documentation for handling variadic arguments in bash scripts, specifically addressing how to properly convert shell-escaped strings to bash arrays when arguments contain spaces.

Changes:

• Added a new section "Using Variadic Args in Bash" with code examples
• Documented the eval "arr=($usage_var)" pattern for converting variadic args to bash arrays
• Included usage examples for iterating over and passing array elements to commands

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Using eval with user-controlled input can introduce command injection vulnerabilities. If usage_files contains malicious shell commands, they will be executed. Consider documenting safer alternatives such as using readarray with process substitution, or add prominent security warnings about input validation if eval is necessary.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 70.57%. Comparing base (16f3858) to head (d23303c).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #480   +/-   ##
=======================================
  Coverage   70.57%   70.57%           
=======================================
  Files          47       47           
  Lines        6597     6597           
  Branches     6597     6597           
=======================================
  Hits         4656     4656           
  Misses       1264     1264           
  Partials      677      677           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gemini-code-assist]

Code Review

This pull request adds documentation for handling variadic arguments in Bash, particularly when arguments contain spaces. The suggested approach uses eval to create a Bash array. My feedback focuses on improving the security and robustness of the provided code example by mitigating the risks associated with eval, specifically by preventing unintended filename expansion (globbing).

[gemini-code-assist]

The use of eval here is vulnerable to globbing. If a user provides an argument like *, it will be expanded to a list of all files in the current directory, which can lead to unexpected behavior and security risks. To make this example safer for users to copy and paste, it's crucial to disable globbing before the eval command and restore it afterward.

Suggested change

	eval "files=($usage_files)"
	set -f # Disable globbing to prevent filename expansion
	eval "files=($usage_files)"
	set +f # Re-enable globbing

References

1. When using eval to parse a string into shell arguments, it's important to disable globbing (set -f) to prevent unintended filename expansion from characters like * and ? in the input string. This is a common security best practice for writing robust shell scripts.