Skip to content

docs: document the in: stdin redirection option on ProcessExecuter methods #159

Description

@jcouball

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

  1. @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.
    
  2. @example block on at least one method (e.g. run) showing the IO.pipe pattern for feeding stdin content.

  3. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions