Skip to content

Document image save and load stdout/stdin fallbacks.#1905

Open
anxkhn wants to merge 1 commit into
apple:mainfrom
anxkhn:docs/image-save-load-optional-io
Open

Document image save and load stdout/stdin fallbacks.#1905
anxkhn wants to merge 1 commit into
apple:mainfrom
anxkhn:docs/image-save-load-optional-io

Conversation

@anxkhn

@anxkhn anxkhn commented Jul 5, 2026

Copy link
Copy Markdown

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update

Motivation and Context

The command reference documented container image save --output and
container image load --input as required flags, which hid the piping workflow.
Both options are optional: when --output is omitted, image save writes the OCI
archive to stdout, and when --input is omitted, image load reads the archive
from stdin. This is what the code already does:

  • ImageSave.swift declares var output: FilePath? (optional) and, when it is
    absent, streams the archive to FileHandle.standardOutput.
  • ImageLoad.swift declares var input: FilePath? (optional) and, when it is
    absent, reads the archive from FileHandle.standardInput.

The docs were never updated after that stdin/stdout support landed, so the
synopsis and prose still marked the flags as required. This change brings the
reference in line with the behavior and matches how the sibling container export
entry already documents its stdout fallback.

Specifically, for both image save and image load it:

  • brackets [--output <output>] / [--input <input>] in the synopsis so they read
    as optional,
  • reworks the description to note the stdout / stdin fallback (dropping the
    inaccurate "on disk" for save and "The tar file must be specified via --input."
    for load),
  • annotates the option bullets with "(defaults to stdout)" / "(defaults to stdin)",
  • adds a short Examples block showing both a file and a piped invocation.

No code changes; documentation only.

Testing

  • Tested locally
  • Added/updated tests
  • Added/updated docs

Verified the documented behavior against the source in
Sources/ContainerCommands/Image/: the optional output / input options and
the stdout / stdin fallback branches. Reviewed the rendered Markdown for the
image save and image load sections; git diff --check is clean. No automated
test applies to a documentation-only change (the file is hand-maintained, not
generated).

The image save --output and image load --input options are optional: when
omitted, save writes the OCI archive to stdout and load reads it from stdin.
The command reference still presented both flags as required, which hid the
piping workflow. Bracket the options in the synopsis, note the stdout/stdin
defaults, and add piping examples, matching the container export entry.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant