Summary
The README and YARD docs for spawn_with_timeout, run, and run_with_capture each note they accept "all Process.spawn execution options" (with a link to the Ruby docs), but the in: option for stdin redirection receives no specific treatment.
Why this matters
There is a non-obvious constraint: in: requires a real IO object with a file descriptor. Passing a StringIO silently fails or raises an error at the Process.spawn level because StringIO has no underlying file descriptor. The correct approach is IO.pipe:
reader, writer = IO.pipe
writer.write("HEAD\n")
writer.close
result = ProcessExecuter.run('git cat-file --batch-check', in: reader)
reader.close
Without a callout in the docs, callers are likely to reach for StringIO first (as they would for out: / err:) and be surprised when it doesn't work.
Suggested additions
-
@option tag on spawn_with_timeout, run, and run_with_capture documenting :in, e.g.:
@option options_hash [IO] :in the read end of an IO pipe to use as the subprocess's stdin.
Must be a real IO object with a file descriptor; StringIO is not supported by Process.spawn.
-
@example block on at least one method (e.g. run) showing the IO.pipe pattern for feeding stdin content.
-
README callout — alongside the existing MonitoredPipe section for out:/err:, add a brief note explaining that stdin redirection via in: must use a real IO object and showing the IO.pipe idiom.
Summary
The README and YARD docs for
spawn_with_timeout,run, andrun_with_captureeach note they accept "allProcess.spawnexecution options" (with a link to the Ruby docs), but thein:option for stdin redirection receives no specific treatment.Why this matters
There is a non-obvious constraint:
in:requires a realIOobject with a file descriptor. Passing aStringIOsilently fails or raises an error at theProcess.spawnlevel becauseStringIOhas no underlying file descriptor. The correct approach isIO.pipe:Without a callout in the docs, callers are likely to reach for
StringIOfirst (as they would forout:/err:) and be surprised when it doesn't work.Suggested additions
@optiontag onspawn_with_timeout,run, andrun_with_capturedocumenting:in, e.g.:@exampleblock on at least one method (e.g.run) showing theIO.pipepattern for feeding stdin content.README callout — alongside the existing
MonitoredPipesection forout:/err:, add a brief note explaining that stdin redirection viain:must use a real IO object and showing theIO.pipeidiom.