Rendered from docs/interfaces/headwater-show.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

headwater show

Synopsis

headwater show <path|identifier> [--root <path>]

The target is a path under the corpus root or an identifier declared by a document. A path can have the form that a shell or an editor writes, relative to the repository root, as the Synopsis section of headwater explain states.

Description

headwater show prints the content of one document. It writes the bytes of the file exactly as they are on disk, and it writes nothing else. It does not decode the text, render the Markdown or add a newline at the end. A reader who redirects standard output to a file gets a copy of the document.

The verb finds the document with the same function that headwater explain uses. A target that explain resolves, show resolves to the same file. A target that explain refuses, show refuses with the same sentence on standard error.

Use explain to learn what a document is. Use show to read what it says, by its identifier, when you do not know its path.

Preconditions

The repository must carry a readable .headwater/taxonomy.lock, consumer declaration and corpus. The target must resolve to a typed or untyped census row. show refuses every row that the walk could not read, as the paragraphs under Exit status say. Such a row is a symlink, a named pipe, a socket or a device, an unreadable directory, or a name that is not UTF-8 (#1366).

An identifier resolves only to a typed document. An untyped document resolves only by its path.

Options

Option	What it does
<path|identifier>	Select the document to print.
--root <path>	Select the repository to read.
--no-color	Force plain text on both streams: bold and dim weight plus glyphs, no escape sequence. The default already senses whether each stream is a terminal, and renders color only there. Standard output is the document's own bytes, so this flag changes only a refusal on standard error.
--no-banner	Suppress the masthead: the line naming this binary and its version, that the root help screen alone prints. It is accepted here and does nothing, since only the root screen prints one.

--json is not an option of this verb, because the output is the document and not a report about it. Global --help, --version and --no-banner are answered before the verb runs.

Exit status

0 means that the target resolved and the bytes of its file were written to standard output. Standard error is empty.

1 means that the target was missing or is a row that the walk could not read, or that the file could not be read. It also means that the command line was invalid or the repository could not load. A missing target writes its refusal to standard error and no byte to standard output. A bare headwater show writes "show takes a path or an identifier".

A missing target states one of five things. The five states and their sentences are the table in the Exit status section of headwater explain. show writes the same sentence as explain for each target, because one function writes the refusal for both verbs.

A row that the walk could not read is refused in the sentence of explain. explain refuses such a row, and show writes the same sentence with its own name as the verb. The sentence names the path and the reason, and it ends "so show prints nothing". For a symlink, the reason names the target of the link. show writes no byte to standard output (#1366).

A symlink is refused. The census walk does not follow a symlink, and show does not follow one either. A link at a document path is a row that the walk could not read, so the paragraph above applies. The sentence names the target of the link. The walk makes no row under a directory that is a symlink. So a path through such a directory holds no document, and show writes the sentence that headwater explain writes for a path with no document. A link can name any file on the host, and these refusals keep every read inside the root. A path through a symlink that leads out of the root gets a different refusal. It is outside the repository, and show writes the sentence that headwater explain writes for that state (#1249).

A named pipe, a socket or a device is refused. The census walk never opens such an entry, because a read of a named pipe that has no writer does not end. show does not open one either, and it writes no byte to standard output. Standard error names the path, and the sentence ends "which the census never opens, so show prints nothing" (#1333).

1, and never 101, when standard output or standard error cannot be written, and one sentence on standard error names a failed standard output.

Environment

No environment variable reaches this verb. The target and repository come from the command line, and the census and graph come from the tree.

Files

Path	How this verb treats it
.headwater/taxonomy.lock	Read for the resolved taxonomy.
.headwater/taxonomy.yml	Read through the consumer loader.
The corpus	Read for census rows and identifiers. The resolved document is read as bytes.
.headwater/imports/	Read where .headwater/taxonomy.yml declares an import, for the anchors that an imported snapshot supplies. An imports entry that does not read stops the verb with exit 1, and so does an at path outside the repository root.
the path each harvests.<name>.at names	Read where .headwater/taxonomy.yml declares a pinned corpus export, for the anchors that export supplies. A harvests entry that does not read stops the verb with exit 1, and so does an at path outside the repository root. A pin with no digest binds no anchor. An absent file binds no anchor, and neither does a file that fails the pinned digest or is not an export.

The verb writes no file.

See also

headwater explain states the kind, derivation and relations of the same document.

headwater route selects pointers from a task description.