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

headwater import

Synopsis

headwater import [<name>] [--expect <digest>] [--write] [--root <path>]

The command reads a declared fetched snapshot, checks its pin, and reports the relation halves it would add.

Description

Without --write, the command reports pending edge halves and changes nothing. With --write, it writes the validated halves into documents at their near ends.

It requires a digest from the declaration or from --expect. It refuses the whole import when a snapshot, edge or write cannot be validated.

Preconditions

The consumer declaration must contain one or more import declarations. A bare command is valid only when exactly one import exists. The selected snapshot directory must exist and match the expected digest. The imports block and each entry under it must be mappings. Each at path must be under the repository root, with no .. segment, no absolute path and no symlink that leads out of the root. Otherwise the verb stops with exit 1 and names the entry.

Options

Option	What it does
<name>	Selects a declared import when more than one exists.
--expect <digest>	Supplies the digest to check against the snapshot.
--write	Writes validated edge halves into documents.
--root <path>	Selects the repository to load.
--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.
--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.

Exit status

0 means that the snapshot was read and the plan was reported or written.

1 means that the import was undeclared, unpinned, invalid or not writable. A refusal writes no edge.

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

The command reads no environment variable.

Files

Path	How this verb treats it
.headwater/taxonomy.yml	Read for import declarations and digest, and for the harvests block.
The declared snapshot directory	Read and checked against its digest.
.headwater/imports/	Read where .headwater/taxonomy.yml declares an import. The graph load reads every declared snapshot, and not only the selected one, 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.
Documents	Written only with --write, after the whole plan validates.

See also

headwater taxonomy vendor installs a fetched taxonomy package. headwater check reads the imported graph.