File Marks

Overview ¶

ytt allows to control certain metadata about files via --file-mark flag.

$ ytt ... --file-mark <path>:<mark>=<value>

where:

• path — location to the file(s) being marked
  • exact path (use --files-inspect to see paths as seen by ytt)
  • path with * to match files in a directory
  • path with **/* to match files and directories recursively
• mark — metadata to modify on the file(s) selected by path
• value — the value for the mark

Note that this flag can be specified multiple times.

Example:

ytt -f . \
  --file-mark 'alt-example**/*:type=data' \
  --file-mark 'example**/*:type=data' \
  --file-mark 'generated.go.txt:exclusive-for-output=true' \
  --output-files ../../tmp/

Available Marks ¶

path ¶

Changes the relative path.

--file-mark '<path>:path=<new-path>'

Example:

--file-mark 'generated.go.txt:path=gen.go.txt'

renames generated.go.txt to gen.go.txt

exclude ¶

Exclude file from any kind of processing.

--file-mark '<path>:exclude=true'

type ¶

Change type of file, affecting how ytt processes it.

--file-mark '<path>:type=<file-type>'

By default file-type is determined based on file extension and — as of v0.32.0 — content.

file-type can be:

• yaml-template (default for: .yml or .yaml) — parsed as a YAML document and evaluated for templating.
• yaml-plain — parsed as a simple YAML document (not evaluated for templating).
• text-template (default for: .txt) — parsed as a text document containing text templating.
• text-plain — included in output, as is.
• starlark (default for: .star) — a Starlark source file (executed)
• data (default for all other files) — a text file that can be loaded by data.read()

Example:

--file-mark 'config.yml:type=data'

indicates that config.yml is not a yaml-template, but is data. This file will not be parsed, evaluated, or included in the output, but can be loaded using data.read().

type detection for YAML files ¶

(as of v0.32.0)

First, ytt determines the type of each YAML file:

1. if it has a .yml or .yaml extension, it’s assumed to be a yaml-template
2. if it is yaml-template but does not contain any ytt templating, it is treated as if it were yaml-plain
3. if it is marked with type=yaml-plain, it is treated as yaml-plain

and then processes each:

• yaml-template files are:
  1. parsed as YAML,
  2. evaluated (i.e. executes ytt the template), and
  3. linted (i.e. detects when non-ytt comments are included)
     • this catches errors where the @ is accidentally omitted,
     • if the --ignore-unknown-comments flag is included, this “linting” is disabled.
• yaml-plain files are simply parsed as YAML (with no evaluation or linting).

for-output ¶

Marks a file to be included in the output.

Files of type yaml-template, yaml-plain, text-template, and text-plain are part of the output by default.

--file-mark '<path>:for-output=true'

Example

--file-mark 'config.lib.yml:for-output=true'

By default, .lib.yml files are not included in the rendered output (they are loaded by other templates). With this file mark, config.lib.yml is included in the output.

exclusive-for-output ¶

Limits output to only marked files.

If there is at least one file marked this way, only these files will be used in output.

--file-mark '<path>:exclusive-for-output=true'

Example:

--file-mark 'config.lib.yml:exclusive-for-output=true'

Causes output to only include config.lib.yml.