shell-escape

shell-escape is a tiny Rust crate that escapes a string so it can be safely passed as a single argument to a shell, handling both POSIX-style shells and Windows cmd.exe. It is a Rust port of the escaping logic used by Cargo itself when constructing shell commands from arbitrary strings.

The crate exposes a single top-level escape() function that dispatches to platform-specific unix::escape() or windows::escape() implementations based on the target OS (or the MSYSTEM environment variable on Windows), so callers building shell commands or displaying copy-pasteable command strings don’t need to hand-roll platform-specific quoting rules.

What You Get

• A top-level escape(Cow<str>) -> Cow<str> function that auto-detects the current platform’s shell quoting rules
• A unix::escape() implementation using a character whitelist and single-quote wrapping
• A windows::escape() implementation matching cmd.exe’s backslash/quote escaping rules
• Zero-copy behavior via Cow<str> — strings that need no escaping are returned unchanged

Common Use Cases

• Building a shell command string from user- or config-supplied arguments before executing or displaying it
• Generating copy-pasteable CLI invocations in tool output or error messages
• Escaping compiler/linker flags before passing them through to a shell invocation, as Cargo itself does
• Cross-platform tooling that needs consistent quoting behavior on both Unix shells and Windows cmd.exe

Under The Hood

Architecture - The crate is a single src/lib.rs file exposing one public escape() function that branches on cfg!(unix) (or an MSYSTEM environment variable check for MSYS/Git Bash on Windows) to dispatch into one of two child modules, unix and windows, each implementing its own escape() with platform-appropriate quoting rules. The Unix implementation whitelists safe characters (alphanumerics plus -_=/,.+) and wraps anything else in single quotes with embedded-quote handling; the Windows implementation replicates cmd.exe’s double-quote and backslash-doubling rules.

Tech Stack - Pure standard-library Rust with no external dependencies — only std::borrow::Cow and std::env are used. The crate targets a pre-2018 Rust edition (no edition key in Cargo.toml) and has no build dependencies or feature flags.

Code Quality - Coverage is limited to inline #[test] functions within each platform module (unix::test_escape, windows::test_escape) covering common cases like flags, paths with spaces, and empty strings; there is no separate tests/ integration suite. The code is small and readable but uses now-deprecated inclusive range-pattern syntax ('a'...'z') reflecting its age — last substantive commit in 2020, matched by an ‘inactive’ GitHub activity status.

API Design - The public surface is a single function (plus two submodule variants for explicit platform targeting), taking and returning Cow<str> so callers pay no allocation cost when a string needs no escaping. There is no configuration, no builder, and no setup beyond calling escape() directly, making it about as low-friction as a utility crate can be.