Disclosure: This draft was generated with AI and checked against the cited primary sources, with a separate AI editorial review. It was prepared for the FrameSprite team, which has a commercial interest in FrameSprite. Proposed examples are not executed tests unless explicitly identified as recorded fixture results.
Treat filenames as data throughout export. Quoting a name protects it from shell splitting, but a command can still interpret a leading hyphen as an option. Prefer path APIs, or use the command's documented separator when passing asset paths.
Key Takeaways
- Keep argument boundaries and option parsing separate.
- Avoid concatenating asset names into shell command strings.
- Check the exact interface of every tool in the pipeline.
Why a quoted filename can still fail
A sprite named -idle.png can be a filesystem entry while a command receiving that string treats it as a flag. Quoting and option parsing happen at different stages. Adding more quote characters does not reliably address the second stage.
The Git add manual documents -- as the separator between options and paths. This is a rule for that command, not a universal guarantee about every exporter or archive tool.
Design around argument arrays
Prefer a process API receiving an executable and an argument list, rather than one shell command string. Pass each asset path as one argument. When no external program is needed, use a filesystem API to copy or inspect the file.
Use path operations to construct paths deliberately. Path normalization does not validate a name for all operating systems. Identity, permitted characters, and command parsing are separate checks.
A production naming policy may reject leading hyphens in delivery names while keeping a source-to-output mapping. Explain the policy to artists. Silent replacement can create different collisions, and changing only the PNG leaves metadata pointing at the previous name.
Example: an idle action placed first in a list
An artist names an experimental action -idle to sort it before other actions. The exporter writes a PNG with that basename. A handoff script passes the basename directly to a command, which interprets it as an option before reading the image.
For Git, an illustrative command is git add -- ./exports/-idle.png. It separates options and uses a relative path. This command was not executed for this guide. Other tools may require a different form or lack this separator.
If the team renames the delivery, update the manifest, animation list, preview references, and any sample scene together. Retain the mapping so the next automated export does not restore the problematic name.
Verify the recipient boundary
Review Windows naming rules when Windows recipients are supported. A name accepted by one filesystem may still be unsuitable elsewhere. Reserved names and trailing characters deserve their own validation.
Proposed acceptance cases include a supported filename with spaces, a leading hyphen, and a non-ASCII character. Verify which file the program processed, not merely its exit status. Record arguments safely without exposing private reference paths unnecessarily.
This is a robustness procedure derived from documented interfaces. It does not report an exporter test and does not make arbitrary command text safe to accept as a path. Validate the naming policy before the packaging step rather than asking users to repair the release themselves.
Related workflow
See game asset unicode normalization manifest for the adjacent failure. Keep the animation handoff checklist with the package and record visual decisions in the art reference board.
Prepared by the FrameSprite Workflow Team. Editorial method · Corrections. Primary documentation checked 2026-10-20.
Top comments (0)