fix(docs): multi-output examples fail when pasted into Bash

Open Beginner friendly
  • Is something wrong?
#323 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
88/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
bash, markdown
Domain
documentation

Research direction

Open content/docs/guides/sbom/getting-started.md around lines 58-69 and content/docs/guides/sbom/formats.md around lines 111-117 in anchore/oss-docs. Remove the spaces and trailing comments after each line-continuation backslash, moving any explanation onto its own line above the command. Done when pasting both examples into Bash forms one syft invocation with all documented -o options.

Written by the indexing model from the issue text.

Description

Summary

The commented multi-output examples in the SBOM getting-started and output-formats guides break the command across separate shell invocations. Copying the getting-started example into Bash sends no output options to syft and runs each -o line as a separate command. This prevents the example from requesting the promised SBOM files.

Runtime or environment

  • Documentation: default branch main at e31256106e227f0d6e6d520fbff93376a30bfd3b; the repository has no published releases or tags.
  • Verification: Bash with a print-only syft function. No Syft binary, container scan, or SBOM-file creation was tested; this reproduces shell parsing independently of Syft.

Steps to reproduce

  1. Start Bash and define this harmless argument-printing function:
syft() { printf 'argc=%s\n' "$#"; printf 'arg=<%s>\n' "$@"; }
  1. Paste the getting-started guide's example exactly, including the spaces and comments after the backslashes:
syft alpine:latest \                 # what we're scanning
  -o table \                         # a human-readable table to stdout
  -o spdx-json=alpine.spdx.json \    # SPDX-JSON formatted SBOM to a file
  -o cyclonedx-json=alpine.cdx.json  # CycloneDX-JSON formatted SBOM to a file
  1. For the output-formats guide's terminal-and-file example, substitute alpine:latest for its <source> placeholder and paste the remaining text unchanged:
syft alpine:latest \
  -o table \           # report to stdout
  -o json=sbom.json    # write to file

Expected behavior

Each example forms one syft invocation with all its documented output options. The getting-started guide promises a table plus SPDX and CycloneDX files; the output-formats guide promises terminal output plus a JSON file. With the stub, the corresponding argument counts are seven and five, with no standalone -o commands.

Actual behavior

The getting-started example prints:

argc=2
arg=<alpine:latest>
arg=< >

Bash then emits three -o: command not found errors; the final command returns status 127. The output-formats example passes four arguments (alpine:latest, -o, table, and a literal space), then emits one -o: command not found error; the final command returns status 127.

The backslash escapes a following space rather than the newline. As a control, removing the spaces and comments after each continuation backslash produces one stub invocation with all seven or five intended arguments, no shell errors, and exit status 0. This control verifies argument delivery, not Syft output generation.

Evidence

Source inspection establishes the documented contract, and executed shell probes establish the parsing failure. Reproduction is complete for shell parsing; Syft runtime behavior was not tested.

Restoration check

Pasting both documented examples into Bash, after replacing the output-formats placeholder, must deliver every documented output option to one invocation without stray whitespace arguments or standalone -o commands. The print-only function checks this without scanning an image. A separate real-Syft smoke test can verify that the documented files are created.

References

Issue #19, “Finalize the SBOM user guide” is closed after broader guide work. This report concerns the currently reproducible shell-parsing failure; that issue does not document this specific failure.

Triage assessment

  • Impact level: P2
  • Assessment status: supported
  • Impact basis: Readers who paste these multi-output examples into Bash cannot deliver the documented file-output options to Syft. The observed failure is bounded to these examples; it does not establish a defect in Syft itself.
  • Workaround status: available
  • Workaround basis: The control preserves all documented arguments by leaving each continuation backslash immediately before the newline. It passes the argument-delivery check without changing the requested outputs.
Dominant language
Python
Stars
8
Forks
12
Avg merge
3m
Merged PRs (30d)
23

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from anchore/oss-docs

All issues in anchore/oss-docs

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.