fy-join1
Fy-tool documentation
Part of fy-tool(1).
Usage
fy-tool [OPTIONS]
[<file>
…]
fy-dump [OPTIONS]
[<file>
…]
fy-testsuite [OPTIONS]
<file>
fy-filter [OPTIONS]
[-f
FILE]
[<path>
…]
fy-join [OPTIONS]
[-T
PATH]
[-F
PATH]
[-t
PATH]
[<file>
…]
fy-ypath [OPTIONS]
<ypath-expression>
[<file>
…]
fy-compose [OPTIONS]
[<file>
…]
fy-b3sum [OPTIONS]
[<file>
…]
Overview
fy-tool is the libfyaml command-line front-end for parsing, rewriting, querying, joining, testing and hashing YAML and JSON data.
The executable changes behaviour either by the invoked program name (fy-dump, fy-testsuite, fy-filter, fy-join, fy-ypath, fy-compose, fy-b3sum) or by an explicit mode-select option such as --dump or --filter.
The default mode is dump.
Options
General options
-
-h, --help -
Display the built-in help message.
-
-v, --version -
Display the libfyaml version.
-
-q, --quiet -
Suppress informational and non-fatal diagnostic output.
-
-d LEVEL, --debug-level LEVEL -
Set the minimum diagnostic severity emitted by the library. The default is
3(warning level).
-
-C MODE, --color MODE -
Control ANSI color output. Supported values are
on,off, andauto. The default isauto.
-
-V, --visible -
Make spaces, tabs, and line breaks visible in text output.
-
--dry-run -
Parse the input but suppress normal output generation.
Diagnostic options
-
--disable-diag MODULE -
Disable diagnostic output for the named module.
-
--enable-diag MODULE -
Enable diagnostic output for the named module.
-
--show-diag OPTION -
Show the named diagnostic field. Supported values are
source,position,type, andmodule.
-
--hide-diag OPTION -
Hide the named diagnostic field.
Parser options
-
-I DIR, --include DIR -
Add DIR to the input include search path.
-
-j MODE, --json MODE -
Select JSON input handling. Supported values are
no,force, andauto. The default isauto.
-
-r, --resolve -
Resolve anchors and merge keys while parsing.
-
--yaml-1.1 -
Force YAML 1.1 rules when the input does not declare a version.
-
--yaml-1.2 -
Force YAML 1.2 rules when the input does not declare a version.
-
--yaml-1.3 -
Force YAML 1.3 rules when the input does not declare a version.
-
-l, --follow -
Follow aliases during path traversal and related path-based operations.
-
--sloppy-flow-indentation -
Accept relaxed indentation rules in flow mode.
-
--prefer-recursive -
Prefer recursive algorithms over iterative ones.
-
--ypath-aliases -
Enable alias processing for ypath evaluation.
-
--allow-duplicate-keys -
Allow duplicate mapping keys.
-
--collect-errors -
Collect multiple parsing errors before reporting failure.
-
--disable-accel -
Disable parser/emitter acceleration features.
-
--disable-buffering -
Disable stdio buffering and use direct file-descriptor reads.
-
--disable-mmap -
Disable memory-mapped input.
-
--disable-depth-limit -
Disable the normal nesting-depth limit.
Emitter options
-
-i INDENT, --indent INDENT -
Set the output indentation width. The default is
2.
-
-w WIDTH, --width WIDTH -
Set the preferred output width. Use
inffor no width limit. The default is80.
-
-m MODE, --mode MODE -
Select the output style. Supported values are
original,block,flow,flow-oneline,json,json-tp,json-oneline,dejson,pretty,flow-compact, andjson-compact.
-
-s, --sort -
Sort mapping keys before emitting output.
-
-c, --comment -
Preserve and emit comments where supported.
-
--strip-labels -
Strip anchors and aliases from emitted output.
-
--strip-tags -
Strip emitted tags.
-
--strip-doc -
Strip document start and end markers.
-
--strip-empty-kv -
Omit keys whose values are empty or null.
-
--null-output -
Suppress normal output generation.
-
--no-ending-newline -
Do not append a final trailing newline.
-
--preserve-flow-layout -
Preserve single-line flow collection layout when possible.
-
--indented-seq-in-map -
Indent block sequences that appear inside block mappings.
-
--streaming -
Use streaming output mode. This is the default.
-
--no-streaming -
Disable streaming output mode.
-
--recreating -
Recreate streaming events instead of passing them through directly.
Testsuite options
-
--disable-flow-markers -
Omit testsuite flow markers.
-
--disable-doc-markers -
Omit testsuite document markers.
-
--disable-scalar-styles -
Omit testsuite scalar-style markers.
-
--document-event-stream -
Build a document first and then generate the event stream from it.
-
--tsv-format -
Emit testsuite output in TSV format.
Input options
-
-f FILE, --file FILE -
Read from FILE instead of standard input where the selected mode uses a single input source. If FILE begins with >, the remaining text is treated as literal input content.
Join options
-
-T PATH, --to PATH -
Join into PATH. The default is
/.
-
-F PATH, --from PATH -
Take joined input from PATH. The default is
/.
-
-t PATH, --trim PATH -
Emit only PATH from the joined result. The default is
/.
YPATH options
-
-F PATH, --from PATH -
Start evaluation from PATH. The default is
/.
-
--dump-pathexpr -
Dump the parsed path expression before evaluation.
-
--noexec -
Parse the expression but do not execute it.
Compose options
-
--dump-path -
Dump the path while composing a document.
B3SUM options
-
--b3sum -
Enable BLAKE3 hashing mode.
-
--derive-key CONTEXT -
Use key-derivation mode with CONTEXT.
-
--no-names -
Omit file names from checksum output.
-
--raw -
Emit raw digest bytes.
-
--length N -
Emit only N output bytes, up to the BLAKE3 maximum.
-
--check -
Verify checksums read from input files.
-
--keyed -
Use keyed hashing, reading the secret key from standard input.
-
--backend BACKEND -
Select the BLAKE3 backend implementation.
-
--list-backends -
List available BLAKE3 backends.
-
--num-threads N -
Set the worker-thread count.
0means automatic selection and-1disables threaded hashing.
-
--file-buffer N -
Set the per-file I/O buffer size.
-
--mmap-min-chunk N -
Set the minimum chunk size used for memory-mapped hashing input.
-
--mmap-max-chunk N -
Set the maximum chunk size used for memory-mapped hashing input.
Modes
-
--dump -
Select dump mode. This is the default and also the mode used by
fy-dump.
-
--testsuite -
Select testsuite mode. This is also the mode used by
fy-testsuite.
-
--filter -
Select filter mode. This is also the mode used by
fy-filter.
-
--join -
Select join mode. This is also the mode used by
fy-join.
-
--ypath -
Select ypath query mode. This is also the mode used by
fy-ypath.
-
--scan-dump -
Select the internal scan-dump mode.
-
--parse-dump -
Select the internal parse-dump mode.
-
--compose -
Select composer-driver dump mode. This is also the mode used by
fy-compose.
-
--yaml-version-dump -
Print YAML version information.
Examples
Dump a YAML file back out using the default emitter mode:
$ fy-dump invoice.yaml
Resolve anchors and strip labels from the result:
$ fy-dump -r --strip-labels simple-anchors.yaml
Read literal input text via --file:
$ fy-filter --file \">foo: bar\" /
Select data from a file using a path expression:
$ fy-filter --file simple-anchors.yaml /baz/bar
Join two root mappings into a single document:
$ fy-join simple-anchors.yaml invoice.yaml
Generate testsuite event output:
$ fy-testsuite invoice.yaml
List available BLAKE3 backends:
$ fy-b3sum --list-backends
History
- Arch Linux 2026-11-01: the text shown here
- Debian 13 (Trixie) to Debian 12 (Bookworm)
--allow-duplicate-keys since Arch Linux 2026-11-01;
--b3sum since Arch Linux 2026-11-01;
--backend since Arch Linux 2026-11-01;
--check since Arch Linux 2026-11-01;
--collect-errors since Arch Linux 2026-11-01;
--derive-key since Arch Linux 2026-11-01;
--disable-diag since Arch Linux 2026-11-01;
--disable-doc-markers since Arch Linux 2026-11-01;
--disable-mmap since Arch Linux 2026-11-01;
--disable-scalar-styles since Arch Linux 2026-11-01;
--document-event-stream since Arch Linux 2026-11-01;
--dry-run since Arch Linux 2026-11-01;
--enable-diag since Arch Linux 2026-11-01;
--file-buffer since Arch Linux 2026-11-01;
--hide-diag since Arch Linux 2026-11-01;
--indented-seq-in-map since Arch Linux 2026-11-01;
--keyed since Arch Linux 2026-11-01;
--length since Arch Linux 2026-11-01;
--list-backends since Arch Linux 2026-11-01;
--mmap-max-chunk since Arch Linux 2026-11-01;
--mmap-min-chunk since Arch Linux 2026-11-01;
--no-ending-newline since Arch Linux 2026-11-01;
--no-names since Arch Linux 2026-11-01;
--no-streaming since Arch Linux 2026-11-01;
--noexec since Arch Linux 2026-11-01;
--num-threads since Arch Linux 2026-11-01;
--parse-dump since Arch Linux 2026-11-01;
--preserve-flow-layout since Arch Linux 2026-11-01;
--raw since Arch Linux 2026-11-01;
--recreating since Arch Linux 2026-11-01;
--scan-dump since Arch Linux 2026-11-01;
--show-diag since Arch Linux 2026-11-01;
--strip-empty-kv since Arch Linux 2026-11-01;
--tsv-format since Arch Linux 2026-11-01;
--yaml-version-dump since Arch Linux 2026-11-01.
--no-exec until Debian 13 (Trixie).