xff reference

Description

xff walks each starting path and acts on the entries matching an expression, like find(1). With no path it searches the current directory; with no action it prints each match. xff --compare LEFT RIGHT instead compares two directory trees as selected status records or a patch.

xff has two flavors selected by the program name: invoked as find it restricts the expression to find-compatible primaries, operators, and values; invoked as xff it enables the modern extensions. Whole-run xff globals remain available as explicit controls in either flavor. An explicit --config=find|xff overrides the program name. The detailed reference marks the xff extensions beyond find.

Command structure

A command consists of whole-run options, zero or more starting paths, and an optional expression. Starting paths come before the expression; the first expression primary begins with a single dash.

Whole-run double-dash options are position-independent, so --summary=ext may appear before the paths or after the expression. They remain literal arguments inside an argument-taking primary such as -exec or -printf.
The compatibility globals -H, -L, -P, -g, -j, and -z are leading-only because a single-dash word can otherwise be an expression primary.
Adjacent tests and actions have an implicit -a (AND). Use ! for NOT, -o for OR, and shell-quoted or escaped ( and ) for grouping. Evaluation is left to right and short-circuits.
With no starting path, xff searches the current directory (.). With no explicit action, it prints each matching entry. A bare -- ends option parsing so a path beginning with - can be named unambiguously.

Basic examples

xff src -type f -name '*.cc'

find regular C++ source files below src

xff . \( -name '*.cc' -o -name '*.h' \) -print

group alternatives explicitly; the shell escapes keep the parentheses for xff

xff --compare left-tree right-tree

compare two trees and print only discrepancies

Configuration

xff configuration. Options resolve from layered config tiers, then the command line; later layers win. A style (find / xff / rg) sets the baseline defaults, which the tiers and the command line then adjust. Run --explain to print exactly what resolved.

Layers (lowest to highest precedence)

system config: machine-wide defaults (plus root-owned global controls that can prohibit arming)
user config: your personal defaults
autoloaded .xffrc: opt-in root discovery; a NON-ARMING tier before command-line processing
--xffrc=FILE: an explicitly named file (repeatable) - a NON-ARMING tier
command line: flags and --config, highest

Autoloading defaults off (--rc-). --rc discovers .xffrc in directory search roots; --rc+ also discovers descendant files. No ancestor search occurs. --no-config disables discovery and excludes named system and user sections. Existing globals remain active by default; the corresponding --no-require-*-globals permits excluding them too. Both files are still read and validated. An explicit command-line --xffrc remains active.

Globals-requirement directives and the --allow-xffrc pair are config-only, not command-line options. Existing globals are required by default; missing automatic files remain normal. The user config is <OS account home>/.config/xff/config, independent of environment variables. Explicit --xffrc=FILE must exist. Existing unreadable configs and dangling symlinks are errors, even when a skip is requested. The system pair --require-system-globals / --no-require-system-globals is allowed only in unsectioned system globals, once per pair. The user pair --require-user-globals / --no-require-user-globals is allowed in unsectioned system or user globals, once per pair per file; the system decision wins, even if its own globals are skipped. Required globals stay active while named sections are excluded; optional globals are also excluded when the corresponding skip is requested. A permission alone does not skip anything. --no-config requests both exclusions and disables autoloading. Named sections remain optional; selecting a name unavailable in every active file is an error. Neither the CLI nor named sections or .xffrc files may set these requirement directives. Explicit --xffrc files may not contain any of these controls. Separately, --allow-xffrc / --no-allow-xffrc is a normal config-only setting usable in system defaults or any user config block; user selection and precedence decide whether command-line --xffrc=FILE is accepted, and an unsectioned system denial cannot be overridden. Admission is checked before any .xffrc discovery or explicit paths are opened. The admission pair also governs autoloading. User decisions follow ordinary application order, including in-place --config=NAME composition; INI section order never overrides explicit selector order. Each section applies once.

[deny]
--no-allow-xffrc
[allow]
--allow-xffrc

With that user INI, xff . --config=allow --config=deny --xffrc=task.rc rejects loading before opening task.rc; reversing the selectors permits loading. The same rule applies to --rc and --rc+.

System, user, and all .xffrc files share one INI grammar. Write unconditional options with their exact command-line spelling before the first section, and named configurations as plain [NAME] sections. For example, write --color=auto, then [dev] and -E; do not remove the option dashes or add a config section prefix. Global lines are validated and an invalid one fails the run, including when a trusted file is requested to be skipped. Named sections are atomic: one invalid line disables the entire section. A name may be declared only once per file, including empty sections; duplicate declarations disable that name. Other files may refine the same name. Disablement propagates through --config=NAME references, and selecting a disabled section is a usage error. Thus -E development disables its section because -E takes no value and development is an unexpected token.

A line may contain multiple directives: --hidden --color=never or -name foo -name bar. Adjacent predicates mean AND; use -name foo -o -name bar for either name. Config predicates and actions form an expression that is ANDed as a group with the CLI expression. Each primary consumes only its own arguments. Closed choices are validated by the shared CLI parser: -type garbage is invalid, while -type f,d is a valid any-of list.

Config files emulate the shell's quoting and escaping to produce arguments for the same CLI parser. The config reader removes comments before passing those arguments to the parser; config files are not shell scripts. System, user, and all .xffrc files all use this rule. Single or double quotes group arguments, including spaces and empty values; outside quotes, a backslash escapes the next character. Inside double quotes, backslash escapes only double quote, backslash, dollar, backtick, or newline. Braced environment substitutions are supported as described below; command, pathname, and tilde expansion are not. Use the same flag spelling as on the CLI: --color=auto, not --color = auto. Whitespace separates arguments; it is not assignment syntax.

INI arguments support ${NAME} (unset is an error; empty is allowed), ${NAME:-DEFAULT} (literal fallback when unset or empty), and ${NAME:?MESSAGE} (error when unset or empty). Names start with an ASCII letter or underscore and contain only ASCII letters, digits, and underscores. Substitution uses the cached process environment when the file is read, before validation and section selection. Errors invalidate the line under the usual global/section rules. Single quotes and escaped dollars prevent substitution; double quotes permit it. Bare $NAME and section names remain literal. Values stay within one argument, including spaces and comment characters, and are never parsed or expanded again. DEFAULT and MESSAGE are literal text through the next }; quotes and backslashes there remain content. Newlines, nested substitutions, and other operators are unsupported. The CLI performs no such substitution itself.

For example, --temp-root="${TMPDIR:-/private/tmp}" and --output-root="${HOME:?HOME must be set}/xff-results" may appear in unsectioned system/user INI. Expanded roots must still exist and pass physical-path validation. Environment values are caller-controlled: using them in root declarations delegates the path choice to the caller. Use literal paths and mandatory flags for administrator-enforced fixed boundaries; a fallback or required-value check does not establish trust. %{...} is not processed by the INI reader: -printf '%{env.HOME}' still delegates to the field renderer, while roots have no field renderer.

An unquoted # at the beginning of a word starts a comment through the end of the physical line. foo#bar, \#, and "#" are literal arguments. An unquoted, unescaped ; starts a comment anywhere outside quotes. Both comment markers may follow any amount of whitespace. Quote or escape literal semicolons: \; or ";" supplies the -exec terminator, just as on the CLI. For example, -exec echo x \; ; comment contains an exec action followed by a comment. Likewise, -name '#*' # Match names beginning with a hash contains one predicate and a comment.

Quotes may span lines. Backslash-newline continues a logical line without adding a character, except inside single quotes. An unmatched quote or trailing backslash invalidates the logical line, with a diagnostic at its starting line number; no partial arguments are applied.

Config-only controls

These directives are accepted only inside the stated system/user config files, not on the command line or in any .xffrc file. An allow/deny pair is one setting: where a pair is limited to one occurrence, its positive and negative forms may not both appear.

The system pair is --require-system-globals / --no-require-system-globals; the user pair is --require-user-globals / --no-require-user-globals.

System pair: unsectioned system config only.
User pair: unsectioned system or user config; the system decision wins.
Each pair may appear once per permitted file.
Neither pair is allowed in named sections, explicit .xffrc files, or on the CLI.
--no-config excludes both sets of named sections, retains required globals, and disables rc autoloading.

--no-require-system-globals: permits skipping system globals with --no-system-config or --no-config; system config only, before the first section, and at most one of this pair
--require-system-globals: keeps system globals active, including with --no-config; system config only, before the first section, and at most one of this pair
--no-require-user-globals: permits skipping user globals with --no-user-config or --no-config; before the first section in the system or user config, and at most one of this pair per file; the system decision is authoritative
--require-user-globals: keeps user globals active, including with --no-config; before the first section in the system or user config, and at most one of this pair per file; the system decision is authoritative
--allow-xffrc: allows automatic discovery and command-line --xffrc=FILE; usable in system defaults or any user config block, with normal config selection and last-value precedence
--no-allow-xffrc: denies automatic discovery and command-line --xffrc=FILE; usable in system defaults or any user config block, with normal config selection and last-value precedence; an unsectioned system denial is authoritative
--allow-rc-globals: permits unsectioned content in autoloaded .xffrc files; once per pair before sections in system/user INI; a system denial wins, otherwise the applying user choice wins
--no-allow-rc-globals: rejects autoloaded files containing unsectioned content before actions run (default); same scope and precedence as the positive form; explicit --xffrc=FILE is unaffected
--block-policy-categories=LIST: selects the interpretation of blocks in this file, including its named sections; once before sections in system or user config; see --help=safety for the operation table

Neither explicit nor autoloaded .xffrc files may contain the require/no-require pairs, --allow-xffrc, --no-allow-xffrc, the rc-globals permission pair, or --block-policy-categories. The separate runtime flag --allow-exec is accepted on the CLI and in config files, but an explicit file's own setting never arms its dangerous directives.

Tiny config examples

Defaults and a named override in /etc/xff.ini: xff . --config=dev ends with --color=never; adding --color=always after the selector overrides it.

--color=auto
[dev]
--color=never

Refine [dev] across files: the system file supplies --color=auto, the user file supplies --color=always, and task.xffrc supplies --color=never. xff . --config=dev --xffrc=task.xffrc ends with --color=never. Each file declares [dev] only once.

# user config
[dev]
--color=always
--config=checks
[checks]
-type f

# task.xffrc
[dev]
--color=never

--config=checks composes configurations; repeated references are allowed and each contributing line applies at most once. Later-file refinements wait for the earlier file's section to finish. Section names are literal: [common] is named, and [xff:debug] matches only --config=xff:debug. Unconditional flags go before the first section.

An explicit task.xffrc uses exactly the same INI format. Its unsectioned flags apply when loaded; named flags apply only when that configuration is selected:

--hidden

[quiet]
--color=never

xff . --xffrc=task.xffrc applies --hidden; adding --config=quiet also applies --color=never. The invocation name or another config's --config=quiet can also select the section. A selector alone does not discover files. Unsectioned --config=NAME directives can select sections when the file loads. Autoloading is separately enabled with --rc or --rc+.

Keep system globals mandatory while permitting user globals to be skipped. These system controls override the user file's own globals requirement.

--require-system-globals
--no-require-user-globals

xff . --no-config retains system globals, excludes user globals, excludes both sets of named sections, and disables autoloading. To permit excluding globals from both files, use:

--no-require-system-globals
--no-require-user-globals

To prohibit execution regardless of its source, require globals in an administrator-owned system file and set --block-execution. Add --no-allow-xffrc to reject explicit files altogether:

--require-system-globals
--block-execution
--no-allow-xffrc

Neither user --allow-xffrc nor an explicit file's own --allow-exec can undo those prohibitions. Execution blocks also constrain actions typed directly on the CLI. Runtime --safe, --dry-run, and action-specific confirmation remain separate. Without a system prohibition, --allow-exec from the CLI or an applying automatic config permits dangerous explicit-file lines through the config gate; the explicit file cannot arm itself.

Choosing a style

Every --config=NAME remains active, so multiple named blocks can apply. Among built-in style selectors, the last find, xff, or rg selects the baseline; custom names do not change it. See --help=styles for the table. The invocation name (argv[0]) is the leading selector, so a symlink named find selects the find expression style and rg the rg style; any other name (e.g. a mytool symlink) activates a same-named config block over the xff default. Explicit --config selectors stack on top.

Configuration expands in application order. Automatic system/user defaults and the invocation selector come first; each command-line --config then activates newly matching lines at that exact position, and each --xffrc loads its currently matching lines where it appears. Because conflicting options usually use the last value, moving a selector can intentionally change the result. A config line is applied at most once.

Within one logical config section, repeating an overriding setting keeps the normal last-value-wins result but emits a warning: the earlier value is locally redundant and is usually a copy/paste mistake. Options that deliberately accumulate (such as --exclude, --summary, and --define) may repeat without warning, as may expression primaries. Separate config sections and tiers remain independent. Command-line repetition is never warned about, so a pasted command can be adjusted by appending an override.

Autoloading .xffrc files

--rc-: disable automatic loading (default); explicit --xffrc=FILE remains active
--rc: load .xffrc directly in each directory search root
--rc+: also load .xffrc throughout descendant directories

Modes may be set on the CLI or in applying system/user configuration; the last setting wins. --no-config suppresses all discovery regardless of mode order. An .xffrc cannot set its own discovery mode. With no root argument the default root is .; file roots do not load a parent's configuration. There is no ancestor search, directory-symlink following, or discovery inside archives. Discovery visits physical directories before expression execution, independently of ignore files, hidden-file settings, depth limits, and pruning. Recursive mode can therefore inspect a large tree, even for --explain, which performs discovery but never evaluates actions.

Each file affects the whole invocation, not just its subtree. Argument roots are processed in order; within a tree, parents precede descendants and sibling names are sorted. Overlapping or repeated roots do not automatically load the same directory twice. Discovered files follow system/user defaults and precede CLI flags. Named sections retain the shared --config=NAME composition and selection rules. Explicit files retain their CLI positions; explicitly naming a discovered file applies it again there. Relative flag values remain relative to the working directory, as in every other INI file.

By default an autoloaded file may contain only named sections. The config-only permission pair --allow-rc-globals / --no-allow-rc-globals may appear once before sections in each system or user INI. A system denial is authoritative; otherwise an applying user decision overrides the system default. Neither named sections, .xffrc files, nor CLI arguments may set this permission. Explicit --xffrc=FILE is unaffected. When globals are forbidden, any unsectioned directive fails loading before actions run: this includes expression primaries and --config=NAME, not only double-dash options. Nothing is silently discarded, because doing so could remove an intended restriction.

# project/.xffrc: no global permission needed
[checks]
-type f

xff project --rc --config=checks selects the shared file-only profile.

# user INI, before all sections
--rc
--allow-rc-globals

# project/.xffrc
--hidden
[quiet]
--color=never

With that grant, xff project applies --hidden, and --config=quiet also applies --color=never. Without the grant the unsectioned --hidden causes an error. Missing .xffrc files are normal; unreadable files/directories and non-regular config files fail discovery. --explain reports the mode and every consulted config path. Autoloading and the globals grant never arm dangerous actions; trusted --allow-exec and mandatory --block-* restrictions keep their existing meanings. Ordinary options can still change results, so granting globals is a deliberate trust decision.

Arming dangerous directives

A dangerous directive (the exec family -exec / -execdir / -ok / -capture, or -delete) carried by an explicit or autoloaded .xffrc file is inert unless --allow-exec is set from a trusted tier (the command line or the system/user config, never an --xffrc file itself). Unarmed lines are dropped with a warning. Arming cannot bypass unconditional safety blocks or an active safe profile.

Safety

Without configured restrictions, operations are allowed. --block-* restrictions accumulate and cannot be cleared by later settings. --safe activates the configurable profile; --no-safe deactivates that profile without clearing unconditional blocks. Every --safe-block-* has a --no-safe-block-* counterpart; these profile settings use the last applied value. Initially the profile blocks every relevant capability. Activating it does not reset its definition.

--block-policy-categories=LIST selects categories that use dedicated controls. The list is comma-separated; an empty list (the default) uses ordinary file controls throughout. archive, temp, and output are supported categories. Unknown categories are errors. This config-only directive may occur once in the unsectioned system config and once in the unsectioned user config; each file chooses its own policy. Named sections, explicit .xffrc files, and the CLI cannot set it. Keep policy globals active with --require-system-globals or --require-user-globals when users must not skip them.

Each file's directives are translated before composition. Selecting archive in another file cannot remove mandatory restrictions already imposed. Select archive for precise archive control; an empty list is the simple default. CLI file controls cover archives as well. Every control listed in a table cell must permit the operation. Names omit their prefixes: file-writing means both --block-file-writing and, when safe mode is active, --safe-block-file-writing. execution independently controls arbitrary command execution. The table defines permissions; it does not enable archive operations or add unsupported member-editing actions.

Operation	archive not selected (default)	archive selected
What switches	Archives and members use file controls	Archive output and member edits use archive controls
Create ordinary file	file-writing	file-writing
Overwrite ordinary file	file-writing, file-overwrite	file-writing, file-overwrite
Delete file or entire archive	file-deletion	file-deletion
Pack new archive and members	file-writing	archive-writing
Pack replacement archive	file-writing, file-overwrite	archive-writing, archive-overwrite
Add member to existing archive	file-writing, file-overwrite	archive-writing, archive-overwrite, archive-content-writing
Replace existing member	file-writing, file-overwrite	archive-writing, archive-overwrite, archive-content-writing, archive-content-overwrite
Delete existing member	file-writing, file-overwrite, file-deletion	archive-writing, archive-overwrite, archive-content-deletion
Extract to new ordinary file	file-writing	file-writing
Extract over existing file	file-writing, file-overwrite	file-writing, file-overwrite

--temp-root=PATH and --output-root=PATH are config-only, once per unsectioned system or user INI. The system declaration wins. Roots must be existing absolute directories without symlink components; use physical paths (for example /private/tmp on macOS). Permissions cover all descendants, including subdirectories, but never deletion or replacement of the root itself. Root declarations do not redirect output filenames. The temp root also selects extraction and mount scratch placement. Environment variables alone grant no directory exception. INI ${NAME} substitution in a root declaration explicitly trusts the caller to choose that path; use literal roots for fixed administrator boundaries. See --help=config for defaults, quoting, and validation.

Operation	Ordinary path	temp selected	output selected
Create file	file-writing	temp-file-writing	output-file-writing
Overwrite file	file-writing, file-overwrite	temp-file-writing, temp-file-overwrite	output-file-writing, output-file-overwrite
Delete file or symlink	file-deletion	temp-file-deletion	output-file-deletion
Create directory	directory-creation	temp-directory-creation	output-directory-creation
Delete empty directory	directory-deletion	temp-directory-deletion	output-directory-deletion
Recursive deletion	Check every entry	Check every entry	Check every entry
Delete or replace a declared root	Prohibited	Prohibited	Prohibited

Unselected directory categories inherit ordinary controls through per-INI expansion. Overlapping temp/output scopes require both sets of permissions. Explicit archive restrictions also apply to archives within directory scopes. With declared roots, archive output outside all roots also needs ordinary file writing/overwrite permission. Select archive alongside directory categories to allow archives inside them while blocking ordinary writes elsewhere. Scoped paths reject parent traversal (..) and symlink traversal. Scoped overwrite replaces the directory entry rather than modifying a shared hard-link inode. Ordinary extraction and mount scratch require writing and directory-creation permission. Archive-owned staging is part of an authorized archive write, remains on the destination filesystem for archive publication, and is cleaned through retained handles. It does not grant access to other pre-existing temporary files. User-directed directory creation and deletion have separate controls.

--require-system-globals
--block-policy-categories=archive,temp,output
--output-root=/srv/xff/results
--temp-root=/srv/xff/scratch
--block-execution
--block-file-writing
--block-file-deletion
--block-directory-creation
--block-directory-deletion
--block-output-file-overwrite
--block-output-file-deletion
--block-output-directory-deletion

With those existing roots, this system policy permits new output and scratch work while prohibiting ordinary writes, ordinary deletion, execution, and overwrite/deletion of output contents. An unselected category in another mandatory file can impose additional restrictions. To prohibit an operation everywhere, leave its categories unselected when imposing the ordinary block, or explicitly block every dedicated category as well.

Packing a new archive includes building its contents; member-editing controls do not apply. Replacing an entire archive replaces all its contents, regardless of member-editing restrictions. To preserve existing archives, block archive overwrite. Archive authorization covers only the selected archive output and its necessary owned temporary files, never extraction or unrelated writes. When overwrite is blocked, creation must atomically refuse an existing destination, including symlinks.

--require-system-globals
--block-policy-categories=archive
--block-execution
--block-file-writing
--block-file-deletion
--block-directory-creation
--block-directory-deletion
--block-archive-overwrite

This system config allows packing new archives while blocking ordinary writes, deletion, execution, and replacement of existing archives. Child processes are not sandboxed by xff's file controls; block execution when those controls must not be bypassed by a command.

Explicit-file arming with --allow-exec covers execution and deletion. It does not gate file or archive output: an unarmed explicit file can request writes and overwrites when this safety policy permits them. Use unconditional blocks for mandatory output restrictions.

--dry-run validates safety restrictions first, then previews actions without executing commands or modifying files. It never grants a blocked operation. Reading and normal terminal output remain allowed. A command's exit status or captured output cannot be predicted: preview stops evaluation of that entry and reports an incomplete preview rather than inventing subsequent matches.

See also: Configuration, Archives, Output

Options

Config

`--config=NAME`(global, xff)

activate a named config or select the find, xff, or rg style; repeatable

A config style sets the defaults for ignore files, hidden files, sizes, sort order, and case. find restricts the expression to find-compatible vocabulary and defaults; whole-run xff globals remain available as explicit overrides. xff keeps find's grammar but sorts and prints human sizes; rg is opinionated (respect .gitignore, skip hidden, smart case). Every occurrence remains an active selector, so several named config blocks can apply. All config files use INI sections; each name is declared once per file and may be refined in other files. --config=NAME inside a section composes it with another config. Among the built-in style selectors, the last find, xff, or rg occurrence chooses the baseline; custom names do not change it. A STYLE:EPOCH spelling such as xff:2 selects STYLE while retaining the full name as a config selector, which must be declared in an active config file. Only plain find, xff, and rg need no declaration. See --help=styles for the per-style defaults and --help=config for layering.

See also: Configuration

`--require-system-globals`(global, xff, config-only)

keep existing system globals active when named configs are skipped

Config-only: unsectioned system config only, once per positive/negative pair. System globals remain active with --no-system-config or --no-config. This is the default; missing files remain normal. Named sections can still be excluded.

See also: Configuration

`--no-require-system-globals`(global, xff, config-only)

permit skipping system globals along with named configs

Config-only: unsectioned system config only, once per pair. --no-system-config or --no-config then excludes globals as well as named sections. Without a skip request, globals still apply. Authoritative system admission and requirement controls are still inspected.

See also: Configuration

`--require-user-globals`(global, xff, config-only)

keep existing user globals active when named configs are skipped

Config-only: unsectioned system or user config, once per pair per file. The system decision wins. User globals remain active with --no-user-config or --no-config. This is the default; missing files remain normal. Named sections can still be excluded.

See also: Configuration

`--no-require-user-globals`(global, xff, config-only)

permit skipping user globals along with named configs

Config-only: unsectioned system or user config, once per pair per file. The system decision wins. --no-user-config or --no-config then excludes user globals as well as named sections. Without a skip request, globals still apply.

See also: Configuration

`--allow-xffrc`(global, xff, config-only)

permit explicit and automatic .xffrc loading

Config-only: unsectioned system config or any user section. User decisions follow configuration application order, including composed sections. A system denial remains authoritative. Neither the CLI nor an .xffrc file may grant admission.

See also: Configuration

`--no-allow-xffrc`(global, xff, config-only)

reject explicit and automatic .xffrc loading

Config-only: unsectioned system config or any user section. A system denial cannot be overridden by user or .xffrc content, or by skipping system defaults. Admission is checked before files are opened.

See also: Configuration

`--no-config`(global, xff, command-line-only)

exclude named system and user configs and disable rc autoloading

Command-line only; rejected in configuration files.

Excludes named system and user sections and disables .xffrc autoloading regardless of flag order. Existing globals remain active by default; the applicable --no-require-system-globals or --no-require-user-globals permits excluding the corresponding globals too. Both files are still read and validated. Missing automatic files remain normal. Explicit --xffrc=FILE inputs and ignore files remain active.

See also: Configuration

`--no-system-config`(global, xff, command-line-only)

exclude named system config sections while retaining required globals

Command-line only; rejected in configuration files.

Excludes named sections in /etc/xff.ini. Unsectioned globals remain active by default or with --require-system-globals; --no-require-system-globals allows excluding them too. The file is still read and validated. User and explicit .xffrc configurations remain active.

See also: Configuration

`--no-user-config`(global, xff, command-line-only)

exclude named user config sections while retaining required globals

Command-line only; rejected in configuration files.

Excludes named user sections. Unsectioned globals remain active by default or with --require-user-globals; --no-require-user-globals allows excluding them too. The system decision takes precedence over the user declaration. The file is still read and validated. System and explicit .xffrc configurations remain active.

See also: Configuration

`--rc[-|+]`(global, xff)

discover .xffrc in argument roots; minus disables, plus includes descendants

Defaults to --rc- (off). --rc loads .xffrc in each directory search root; --rc+ also searches descendant directories. With no roots, the default root is .. Discovery finishes before execution, in argument order, parent before children and lexicographically among siblings. Files contribute to the whole invocation, after trusted defaults and before CLI flags. Discovery ignores search filters and never follows directory symlinks or enters archives. Only system/user configuration and the CLI may set this mode. --no-config disables discovery. Unsectioned content requires a trusted --allow-rc-globals grant; otherwise loading fails. Explicit --xffrc=FILE remains independent.

Affects: --xffrc, --explain

Affected by: --allow-rc-globals, --no-allow-rc-globals

`--allow-rc-globals`(global, xff, config-only)

permit unsectioned content in automatically discovered .xffrc files

Config-only: once per pair in unsectioned system/user configuration. A system --no-allow-rc-globals decision cannot be overridden. Without a grant, an autoloaded file containing unsectioned content fails before execution. Named sections remain available; explicit --xffrc=FILE is unaffected. This permission does not arm dangerous actions.

Affects: --rc

`--no-allow-rc-globals`(global, xff, config-only)

reject unsectioned content in automatically discovered .xffrc files

The default without an explicit grant. Config-only: once per pair before all sections in system/user configuration. A system denial is authoritative. Rejection includes unsectioned expressions and --config=NAME; nothing is silently dropped. Explicit --xffrc=FILE keeps its existing global and named-section behavior.

Affects: --rc

`--xffrc=FILE`(global, xff, command-line-only)

also load a specific config file (a non-arming tier; see --allow-exec)

Command-line only; rejected in configuration files.

Loads FILE as a config tier above the user config (naming it is consent to LOAD it). It is a NON-ARMING tier: execution and deletion actions - the exec family (-exec/-execdir/-ok, -capture) or -delete - are inert unless --allow-exec is set from a trusted tier (the CLI or the user/system config, never from an --xffrc file itself). An unarmed dangerous line is dropped with a one-line warning. Repeatable; later files win.

Affects: --allow-exec

Affected by: --rc, --allow-exec

See also: Configuration, --rc, --allow-exec

`--allow-exec`(global, xff)

arm dangerous directives from explicit or autoloaded .xffrc files

Permits the sensitive/destructive directives (the exec family -exec/-execdir/-ok and -capture, and the destructive -delete) carried by an explicit or autoloaded .xffrc file to actually run. Honored only from a trusted tier - typed on the CLI, or set in the user/system config - never from an --xffrc file (so a named config cannot authorize itself). Arming cannot bypass unconditional blocks or the active safe profile; see --help=safety.

Affects: --xffrc

Affected by: --xffrc

`--explain`(global, xff, command-line-only)

inspect resolved configuration and execution resources

Command-line only; rejected in configuration files.

Prints the active style, every config source consulted and whether it was found, resolved flags in application order with their provenance, rejected config directives, and the style-default table with this run's effective values. The effective safety table shows unconditional blocks, the stored safe profile, active decisions, and source file/line/section or CLI origins. It also shows per-file category translation, resolved temp/output roots, and dry-run state. Profile origins remain visible when an unconditional block wins. Named declarations list their source, selection, availability or skip/validation reason, and whether they declare globals, predicates, or actions; availability never authorizes a gated action. The resource view reports worker limits, potential retained state, active hash/line-count fields, and advisory expression costs. It does not predict bytes read, peak memory, or latency. It performs enabled .xffrc discovery but does not evaluate the expression. Existing unreadable config files and missing explicit --xffrc files are errors. For modifiers with registered dependencies, inactive-modifier notes identify effective CLI settings with no consumer. Dormant config defaults and superseded settings stay quiet; the notes do not reject commands or prove that a conditional action will run.

Affected by: --rc

Matching

`-E`(global, find)

use the configured extended-regex grammar (RE2 by default)

Accepts BSD/macOS find's leading extended-regex switch. In xff the extended grammar is selected by --regextype; it defaults to RE2, and command-line --re2 or --pcre override a configured choice. This compatibility flag does not itself replace that choice.

Affects: -regex, -iregex, -rxc, -irxc, -grep, -capture, -capturedir

Traversal

`-H`(global, find)

follow symlinks named on the command line, not while walking

Dereferences each symlink root operand before matching or descending, but keeps symlinks found below that root as symlinks. A dangling root symlink falls back to the link itself. -H, -L, and -P are mutually overriding leading options; the last occurrence wins.

`-L`(global, find)

follow symlinks everywhere during the walk

Dereferences symlink roots and symlinks encountered below them. Matching sees the target's type and metadata, and directory targets are descended. Dangling links fall back to the link itself. Filesystem loops are detected and reported instead of recursed indefinitely. -H, -L, and -P are mutually overriding leading options; the last occurrence wins.

`-P`(global, find)

never follow symlinks (the default)

Matches every symlink as a link and never descends through it, including a symlink supplied as a root operand. Predicates that explicitly inspect a target, such as -xtype and -lname, retain their documented behavior. -H, -L, and -P are mutually overriding leading options; the last occurrence wins.

Archive traversal

`--archive[=none|roots|all|any], -z[-|+|++], -Z[-|+|++]`(global, xff)

descend into archives: -z- none, -z roots only, -z+ / bare --archive all

One of:

none: an archive is one plain file (find behavior; the find-style default)
roots: dive only when a search root is itself an archive (the xff-family default)
all: also dive archives found during the walk (what bare --archive selects)
any: all, plus offer EVERY file to the reader, not only container-looking names

Treats each archive (tar, gz, bzip2, xz, zstd, lz4, zip, ...) as a directory, so a member is an ordinary entry at a member path like foo.tar.gz!inner/x and the expression matches it with the same -name / -type / -size / -newer every other entry gets - and the predicates and fields that READ an entry (-grep, -content, -hash, {hash}, {lines}) read the member out of its container. The modes are nested: none keeps find's behavior (an archive is one plain file); roots dives only when a search root is itself an archive (pointing xff AT an archive implies looking inside); all also dives archives discovered during the walk; any is all without the name gate, offering every file to the reader (the older spelling is --archive-any). Bare --archive means all, and the short form carries chmod-style suffix signs (-z- none, -z roots, -z+ all, -z++ any). The UPPER-case family is the same ladder with writing armed (-Z is -z plus --archive-write, -Z+ is -z+ plus it, -Z++ is -z++ plus it): the case carries the capability and the signs carry the level, so aiming at one cannot reach the other. The two axes resolve independently and later wins, so -Z++ -z- arms writing with reading off, while -Z- is the full reset (reading off AND writing disarmed). Filename sniffing follows that final mode too: --archive=any --archive=all restores the filename gate, including when the modes come from named configurations applied in that order. The find style defaults to none, every xff-family style to roots. Members are read-only until a write spelling arms them, so -delete and the exec family refuse them rather than silently skipping. Under all, a file met mid-walk is offered to the reader only if its NAME looks like a container (any drops that gate); one named on the command line always is. A native phar exposes its executable stub as .phar/stub.php, matching tar- and zip-based phars; it is an ordinary regular member for matching, fields, and statistics. If the manifest stores that path, the stored member wins so one path never denotes two entries. The synthetic stub is readable but cannot be deleted because the format requires it. build-time extras: the stock binary is lean and omits readers; rebuild with --config=xff_full, --//xff:xff_archive for the broad libarchive-backed set, or one of the independent --//xff:xff_asar or --//xff:xff_squashfs readers. Asking for archive handling without any reader is a hard error.

Affected by: --archive-depth, --archive-aggregate, --archive-delete, --archive-extract, --archive-mount, --archive-any

`--archive-depth=N`(global, xff)

how many containers deep --archive dives (default 1)

Counted in CONTAINERS, not directory levels: the default 1 opens an archive but leaves an archive INSIDE it a plain member, so a .gem shows its data.tar.gz without unpacking it. --archive-depth=2 opens that one too. Its own knob rather than part of -maxdepth because nesting is where a decompression bomb lives - a few kilobytes can promise gigabytes per level - while -maxdepth keeps counting member levels as the ordinary depth they are. Only all nests: under roots a member is never a search root, so nothing inside the container is dived whatever the value. N must be at least 1; use --archive=none / -z- to stop diving.

Affects: --archive

`--archive-aggregate=<MODE>`(global, xff)

what --summary / --histogram count when the walk dives (default members)

MODE is one of:

members: count what is INSIDE a dived container, not the container (the default)
container: count containers as the files they are on disk, never their members
both: count each container AND its members - the archive plus its unpacked copy

Diving makes one byte visible twice - once as the container's own size, once as its members' - so a total that adds both describes no filesystem that exists. members (the default) counts a dived container's members instead of the container itself, which is what unpacking it and measuring the result would give; container counts the archives and never what is in them, which is what the disk holds; both counts everything, the archive AND its unpacked copy, for when the doubling is the point. Only the REDUCTIONS are affected: -print and every action still see every entry the walk visits, so a member is listed under container and the container is listed under members. members needs the walk to open a container before deciding, so a -prune on a container no longer avoids opening it - use another mode, or no reduction, to keep that.

Affects: --archive

`--archive-delete`(global, xff)

let -delete remove an archive member, rewriting its container

There is no such thing as removing a member in place: an archive is a stream of header and data records, so the container is written again from the members that survive. That is why this is opt-in and why -delete refuses a member without it - an action that silently rewrites a whole archive is not one to do by default. The rewrite happens after the walk, once per container however many of its members matched, because the walk is reading that same container while it runs. The new archive keeps the original's format and compression (a .tar.gz stays a gzipped tar) and every surviving member keeps its name, mode, times and content; it is written beside the original and renamed over it only when complete, so an interrupted run leaves the container as it was. --dry-run lists the members that would go and writes nothing. A NATIVE phar is rewritten too, by xff's own writer: the manifest and data section are rebuilt from the surviving entries verbatim (so per-member gz / bz2 compression is untouched) and the trailing signature is recomputed (md5 / sha1 / sha256 / sha512). Refused, with the reason named: a format this build reads but cannot write (7-Zip, RAR, ISO); a TAR-based or ZIP-based phar, whose signature is a MEMBER computed over the rest of the container, so a rewrite would leave it stale and PHP would reject the result; an OpenSSL-signed phar, which cannot be re-signed without its private key; a compressed single file, which has no member list to rewrite; and a member of a container nested inside another one.

Affects: --archive

Affected by: --archive-write

See also: Archives, --archive-write, --archive

`--archive-extract`(global, xff)

let -exec / -ok run on an archive member, via a temporary copy

A member is bytes inside a container, so there is no path a child process can open and the exec family refuses one by default. With this flag the member is written to its own temporary directory under the same name it has inside the archive, and the child is handed THAT path: {} renders as the temporary file, -execdir runs in the temporary directory, and -ok shows the copy in its prompt before anything runs. Each copy is removed as soon as its child finishes (for a + batch or a -j child, when the run ends), so nothing is left behind. The copy first goes to a memory-backed directory where the platform has one ($XDG_RUNTIME_DIR or /dev/shm on Linux, both tmpfs), so the child gets an ordinary path without normally writing the member to disk. If no memory-backed directory is available, or the member is larger than its reported free space, xff falls back to $TMPDIR (or the platform temporary directory); extraction therefore does not guarantee that member data never reaches disk. It is opt-in because the child is editing a COPY: a formatter or a patch tool will report success and change nothing in the archive. -delete stays refused whatever this flag says - removing a temporary copy would be a no-op dressed as a deletion. The container itself is an ordinary file, so an action on IT never needed this.

Affects: --archive

Affected by: --archive-mount, --archive-write

`--archive-mount`(global, xff)

let -exec / -ok run on an archive member by mounting its container read-only

The alternative to --archive-extract, answering the same question - what path can a child process open for a member? - with the container itself instead of a copy. The container is mounted read-only (once, whichever members are visited), so {} names a path INSIDE the archive: a tool that only reads it (a compiler, a checksum, grep) sees the real member and nothing is written anywhere. That also removes extraction's trap, where an in-place formatter edits a temporary copy and reports success while the archive keeps its old content: here the mount has no write path at all, so such a tool fails honestly. Mounting is a per-MACHINE capability (it needs the fuse extra AND a runtime FUSE library and permission to mount), so where it cannot happen the run says so once and falls back to extraction rather than failing - which is why this flag is safe to keep in a config file. --archive-extract is still what arms writing through a copy; this one arms reading in place.

Affects: --archive, --archive-extract

`--archive-write, -Z[-|+|++]`(global, xff)

arm both archive write flags (--archive-extract + --archive-delete)

One spelling for "let actions touch members", because the two write flags are almost always wanted together: --archive-extract so -exec / -ok can run over a member, and --archive-delete so -delete can remove one. It is exactly those two flags and nothing else - the dive MODE is untouched. The short form is the UPPER-case archive ladder: -Z is -z with writing armed, -Z+ is -z+ with it, -Z++ is -z++ with it. Case carries the capability and the signs carry the level, so a slipped shift key changes which of the two you asked for, never both - and arming is not doing, since an action still has to ask for the write and --safe / --dry-run still apply. The level and the arming resolve as separate axes with later winning, so -Z++ -z- keeps writing armed with diving off; -Z- is the full reset, disarming writing and turning diving off together.

Affects: --archive-delete, --archive-extract

`--archive-any`(global, xff)

alias for --archive=any: traverse all archives without the filename gate

Selects the same traversal mode as --archive=any or -z++: open archives discovered during the walk, even when their names lack a known archive suffix. This may read every candidate file to identify its format. A root file is always offered to the reader when archive traversal is enabled. Like the other archive mode selectors, a later selector can replace this mode, including --archive=roots or --archive=none.

Affects: --archive

`--archive-separator=STRING`(global, xff)

string between container and member in a member path (default !)

A member path is <container><separator><member>, and there is no single ecosystem convention - ! (JAR / Java URLs), # (fragment style), and the multi-character !/ or #/ other tools print all exist - so this is a presentation choice rather than something hard-coded. ANY string is accepted, not a fixed menu, so xff can emit what another system accepts. Rendering is plain concatenation and xff adds or removes no slash, so a member stored with a leading slash keeps it: a.tgz!/rooted (and with --archive-separator=!/, the doubled a.tgz!//rooted, which is why plain ! is the better default). Parsing splits at the FIRST occurrence and takes the remainder verbatim, so a path xff printed round-trips. A plain / is allowed and composes with globs, but is lossy - a real directory named x.tar becomes indistinguishable from an archive - so it is never the default.

`--archive-prefix=[URI|STRING]`(global, xff)

prefix a member path: empty (default), URI, or any literal string

One of:

(empty): no prefix - a bare path, a.tgz!inner/x (the default)
URI: the receiving ecosystem's own URL: phar://, jar:file:...!/, else archive:
STRING: any other value is used literally, e.g. --archive-prefix=vfs:

Empty (the default) prints the bare path, a.tgz!inner/x. URI renders a URL the RECEIVING tool will accept, which means the ecosystem's own where one owns the format: a .phar as PHP's phar:///abs/a.phar/inner/x, a .jar / .war / .ear as Java's jar:file:/abs/a.jar!/pkg/C.class, and everything else as archive:///abs/a.tar!x for an absolute container or the opaque archive:a.tgz!x for a relative one - archive://a.tgz would be WRONG, since // starts the authority and would make a.tgz a host name. The choice is by EXTENSION, because that is what the claim is: a jar IS a zip, and only its name says which readers expect it. Those two spellings fix the separator as well, so --archive-separator does not reach them; the BARE path keeps one separator whatever the container is, since being re-pasteable matters more there than matching a foreign form. Any other value is used LITERALLY (e.g. --archive-prefix=vfs:), the same freedom --archive-separator has; URI is the one keyword, spelled in caps like RE2 / PCRE2 / GLOB. There is deliberately no none value: it would be indistinguishable from a literal prefix spelled none, which is why empty means no prefix. Applies to PARSING too - under a prefix, a bare path is not accepted as a member path, so the spellings never silently interchange.

Concurrency and ordering

`-j N, -j=N, --jobs=N|all`(global, xff)

directory-read and concurrent -exec workers (all = every detected core)

N is a positive integer; use -j 4, -j=4, or --jobs=4. The conventional attached short form -j4 is also accepted. Every form accepts all in place of N. -j 1 makes directory reads and -exec ... ; synchronous. At larger values, xff reads directories on N worker threads and may independently keep up to N semicolon-form -exec / -execdir children outstanding. Reads and children can overlap; N is not one shared operation budget. The children's truth value is therefore success on launch. The ... + batch forms still run once after the walk and propagate a failing exit status. With no flag, xff uses one fewer than the detected cores, capped at 15 and floored at 1; find and rg modes use every detected core. all always means every detected core.

`--sort[=<ORDER>]`(global, xff)

sibling/traversal ordering (default depends on the mode)

ORDER is one of:

none: filesystem order, whatever the directory yields (fastest)
dir: sort each directory's entries (a bare --sort; also spelled name)
subtree: sorted entries with each subtree inlined contiguously
tree: path-ordered depth-first traversal within each root
roots: sort root operands; retain filesystem order below them
global: sort the roots, then walk each in tree order
score: best -fuzzy match first (buffers everything; needs -fuzzy)

Traversal order and result buffering are separate. Every mode materializes one directory listing, and --jobs may read additional directory listings ahead; none of the path-order modes buffers every match. none preserves each directory's filesystem order. dir sorts a directory's complete child listing, emits that listing, then descends into its sorted children. subtree emits sorted non-directory children first, then each sorted directory or container subtree contiguously. tree visits each sorted child and its descendants before the next child, giving lexicographic depth-first order WITHIN each root while retaining command-line root order. roots stable-sorts only the root operands and otherwise behaves like none. global stable-sorts the roots and applies tree below each one, producing a total hierarchical order by root and then path. Duplicate or overlapping roots remain separate walks and can therefore repeat paths. -depth makes every mode post-order (children before their parent); none retains filesystem sibling order; roots does too, while every other ordered mode uses sorted sibling order. The default is per style: xff sorts per directory, while find and rg leave the order unspecified. score is the odd one out: the others are TRAVERSAL orders the walk streams, while a -fuzzy score only exists once an entry has been evaluated, so results are buffered and ranked after the walk (best first, ties keeping the walk's own order). It needs -fuzzy or -ifuzzy in the expression - ranking by a value nothing produced is a mistake, not an empty ordering - and side-effecting actions such as -exec still run during the walk, so only the printed listing is reordered.

Affected by: --root, --pack

See also: Output, Statistics, --root, --pack

Matching

`--block-size=SIZE`(global, xff)

bytes per bare/-b block for -size and -blocks (default 512)

A bare number is bytes. Explicit B/kB/MB/... units use SI powers of 1000; KiB/MiB/... use IEC powers of 1024. Legacy k/M/G/... remain binary for find compatibility. The value must be positive and fit in 64 bits. Lowercase b is invalid here because defining a block in blocks is circular. This changes the comparison unit for both -size (apparent bytes) and -blocks (allocated bytes); it does not change filesystem metadata or the fixed units printed by -ls.

`--exact`(global, xff)

disable xff's filesystem-native case folding for name/path/fuzzy matching

In xff mode, the otherwise case-sensitive -name, -path, -fuzzy, and -fuzzypath matchers follow the containing volume: xff folds ASCII case on a case-insensitive volume and compares exactly on a case-sensitive one. --exact opts out and makes those matchers byte-case-exact unless --case=insensitive or an explicitly insensitive primary (-iname, -ipath, -ifuzzy, -ifuzzypath) requests folding. Find mode is already exact by default. The volume probe is cached per device and safely defaults to exact matching if unavailable.

`--case=<MODE>, -i, -s[-|+]`(global, xff)

letter case for matchers: -i insensitive, -s/-s+ smart, -s- sensitive (rg -> smart)

MODE is one of:

sensitive: match exactly (-s-)
insensitive: fold case (-i)
smart: fold case unless the pattern contains ASCII uppercase (-s / -s+)

Controls the otherwise case-sensitive name, path, symlink-target, fuzzy, regex, and content matchers (-name, -path, -lname, -fuzzy, -fuzzypath, -regex, -rxc, -grep). Their -i... variants always fold independently. sensitive matches exactly; insensitive (-i) folds case; smart (-s / -s+) folds only when the pattern is all free of ASCII uppercase letters and matches exactly otherwise; -s- forces sensitive. For name, path, and fuzzy matching, xff's filesystem-native folding can additionally apply unless --exact is present. rg defaults to smart; xff and find default to sensitive.

Affects: -name, -path, -lname, -fuzzy, -fuzzypath, -regex, -rxc, -grep, -content

`--regextype=<GRAMMAR>`(global, xff)

match engine: RE2, ERE, EXACT, FNMATCH, GLOB, SHGLOB, or PCRE2 (a build extra)

GRAMMAR is one of:

ERE: platform POSIX extended regular expressions via regcomp(3)
EXACT: a literal string; metacharacters are plain text
FNMATCH: flat shell wildcard; * matches any character including /
GLOB: path-aware shell glob; wildcards and classes are component-local
PCRE2: Perl syntax (lookaround, backreferences); a build extra
RE2: linear-time regular expressions (the default)
SHGLOB: GLOB plus {a,b} brace alternation, so *.{cc,h} matches either

Selects one grammar for every -regex/-iregex, -rxc/-irxc, and -grep pattern in the run; the last occurrence wins. RE2 is the default. Selecting PCRE2 in a build without that extra is a hard error; see --help=extras for availability.

Affects: -regex, -iregex, -rxc, -irxc, -grep, -capture, -capturedir

Affected by: --re2, --pcre

`--re2`(global, xff)

select the fast, linear-time RE2 grammar

A convenient command-line spelling of --regextype=RE2. It overrides a grammar selected by configuration; among grammar selectors, the last occurrence wins.

Affects: --regextype, -regex, -iregex, -rxc, -irxc, -grep, -capture, -capturedir

`--pcre`(global, xff)

select the PCRE2 grammar (a build extra)

A convenient command-line spelling of --regextype=PCRE2. It overrides a grammar selected by configuration; among grammar selectors, the last occurrence wins. PCRE2 is available only in a full build, and selecting it in a lean build is a usage error.

Affects: --regextype, -regex, -iregex, -rxc, -irxc, -grep, -capture, -capturedir

Path filters

`--exclude=GLOB`(global, xff)

skip paths matching a gitignore-style glob (repeatable; a matched directory is pruned)

See also: Ignore and VCS traversal

`--include=GLOB`(global, xff)

re-include paths a --exclude would skip, matching a gitignore-style glob (repeatable)

See also: Ignore and VCS traversal

Classification databases

`--lang-db=FILE`(global, xff)

overlay language metadata and suffix/filename mappings from JSON; repeatable

Loads a JSON object keyed by canonical language name. Each value may set type, color, group, and source, plus string arrays aliases, extensions, and filenames. Later files override earlier files and compiled data. Extensions may include their leading dot and may contain multiple parts; matching folds suffix case while exact filenames retain case. Conflicts between two languages in ONE file follow --lang-conflicts.

Affects: -lang

Affected by: --lang-conflicts

See also: Content, --lang-conflicts, -lang

`--lang-conflicts=error|first|last`(global, xff)

resolve ambiguous suffix or filename claims within one language vocabulary file

One of:

error: reject two languages claiming one suffix or filename in the same file (default)
first: keep the first claim in that file
last: keep the last claim in that file

Controls only ambiguity inside one --lang-db file. Layering remains deterministic: a later file intentionally overrides earlier files and compiled data. error is the default; first or last is an explicit compatibility escape hatch for imported databases.

Affects: --lang-db

`--mime-vocabulary=FILE`(global, xff)

overlay media-type metadata and extension mappings from JSON; repeatable

Loads a JSON object keyed by canonical media type. Each value may set description, source, charset, boolean compressible, and string arrays aliases and extensions. Later files override earlier files and compiled data. An extension may include its leading dot; matching folds case. Conflicts between two types in ONE file follow --mime-conflicts.

Affects: -mime

Affected by: --mime-conflicts

See also: Content, --mime-conflicts, -mime

`--mime-conflicts=error|first|last`(global, xff)

resolve ambiguous extension claims within one MIME vocabulary file

One of:

error: reject two media types claiming one extension in the same file (default)
first: keep the first claim in that file
last: keep the last claim in that file

Controls only ambiguity inside one --mime-vocabulary file. Layering remains deterministic: a later file intentionally overrides earlier files and compiled data. error is the default; first or last provides an explicit compatibility escape hatch for imported databases.

Affects: --mime-vocabulary

Filter & Ignore

`--gitignore[=off|auto|on], -g[-|+]`(global, xff)

respect .gitignore files: -g = auto (only in a git repo), -g+/=on always, -g-/=off never

One of:

off: ignore .gitignore files entirely (also -g-, no / false / 0)
auto: respect .gitignore only inside a git working tree (a bare -g / --gitignore)
on: respect it anywhere, git repository or not (also -g+, yes / true / 1)

Reads .gitignore rules while walking, including nested .gitignore files, .git/info/exclude, and core.excludesFile. -g / auto activates only inside a git working tree; -g+ / =on forces it anywhere; -g- / =off disables it. Independent of --ignore-files (.ignore / .xffignore).

See also: Ignore and VCS traversal

`--ignore-files`(global, xff)

respect per-directory .ignore and .xffignore files (off by default)

See also: Ignore and VCS traversal

`--ignore-file=PATH`(global, xff)

read an extra gitignore-format file, rooted at its own directory (repeatable)

See also: Ignore and VCS traversal

`--no-ignore, -u`(global, xff)

disable all ignore-file processing (.gitignore/.ignore/.xffignore)

See also: Ignore and VCS traversal

`--ignore-vcs`(global, xff)

respect version-control ignore files (.gitignore / .git/info/exclude / core.excludesFile)

The rg-style affirmative for the VCS ignore-file layer - today git's (.gitignore at any depth, .git/info/exclude, core.excludesFile), the same layer -g / --gitignore auto enables. Use it to countermand an earlier --no-ignore-vcs or a style default. Independent of --ignore-files (.ignore / .xffignore), which keep their own switch; --no-ignore / -u still turns off every ignore source. Last of the ignore-mode flags wins.

See also: Ignore and VCS traversal

`--no-ignore-vcs`(global, xff)

do not respect version-control ignore files (keeps .ignore / .xffignore)

Drops the VCS ignore-file layer (git's .gitignore / .git/info/exclude / core.excludesFile) while leaving --ignore-files (.ignore / .xffignore) untouched - that is the difference from --no-ignore / -u, which turns off every ignore source. Today git is the only VCS ignore file xff reads, so this is nearly --gitignore=off. Last of the ignore-mode flags wins.

See also: Ignore and VCS traversal

`--hidden`(global, xff)

include hidden dotfiles in the walk (default: find/xff show, rg skips)

See also: Ignore and VCS traversal

`--no-hidden`(global, xff)

skip hidden dotfiles (the rg default; opts find/xff out)

See also: Ignore and VCS traversal

`--skip-vcs[=<LIST>]`(global, xff)

prune VCS metadata dirs (.git, .hg, ...); bare/=all = every known VCS, =LIST a subset

LIST is one of:

git: .git
hg: .hg
svn: .svn
jj: .jj
bzr: .bzr
darcs: _darcs
cvs: CVS
all: every known VCS (the bare-flag default)
none: off (same as --no-skip-vcs)

Prunes version-control metadata directories at any depth (like ripgrep / fd), so a search never wades into repo plumbing. Bare --skip-vcs (or =all) covers every known VCS: git (.git), hg (.hg), svn (.svn), jj (.jj), bzr (.bzr), darcs (_darcs), cvs (CVS). A comma list (--skip-vcs=git,hg) is an explicit, frozen subset - it never changes if a VCS is added to the default set later. --no-skip-vcs (or =none) turns it off. Independent of --hidden, so the user's own dotfiles (.bazelrc, .gitignore) still show. -g / gitignore mode implies --skip-vcs=git (only .git); an explicit --skip-vcs overrides that. Default off otherwise.

See also: Ignore and VCS traversal

`--no-skip-vcs`(global, xff)

keep VCS metadata dirs in the walk (opts out of --skip-vcs and the -g .git default)

See also: Ignore and VCS traversal

Result formatting

`--format=<FORMAT>`(global, xff)

output format: plain, nul, jsonl, csv, tsv, aligned, markdown (md), tree; default plain

FORMAT is one of:

plain: one path per line (the default)
nul: NUL-separated paths (for xargs -0)
jsonl: JSON objects for built-in listing, comparison, grep, and reduction records
csv: comma-separated columns
tsv: tab-separated columns
aligned: column-aligned table
markdown: a Markdown table (also md)
tree: an indented directory tree

markdown (alias md) also renders ordinary, comparison-result, and paired summary tables as Markdown, with vertically aligned separators and right-aligned numeric headers and values in both source and rendered tables. Aligned and Markdown cells and tree labels C-escape control bytes and literal backslashes; Markdown additionally escapes that spelling for its renderer. Widths include the escaped text. This does not alter raw plain output or CSV, TSV, NUL, and JSONL encoding; --path-encoding controls plain listing paths. Summary schemas come from --summary; --columns selects listing fields and cannot change summary columns. Markdown summaries have descriptive headings above their scope and table. --no-header omits those headings, table headers, and Markdown separator rows when producing fragments. Summaries support plain, aligned, jsonl, markdown (alias md), csv, and tsv; nul and tree are listing-only formats. CSV/TSV summary exports have one header for all requests, explicit row identity, raw numeric values, and canonical scope-prefixed columns. Missing metrics are empty; --no-header removes the single header. TSV uses the same backslash escaping as listings. Histograms, action output, and dry-run previews cannot be mixed into these exports. In comparison mode use --compare=summary or --compare-select=none. Comparison status records support plain and jsonl; comparison patches require plain. Use --compare-select=none to format only comparison summaries. Explicit expression actions retain their own output formats. Built-in -grep uses JSON match/context/count records with jsonl and rejects formats other than plain or jsonl; an explicit -grep:FORMAT remains authored output. JSONL textual values stay strings when valid UTF-8; other byte sequences use {"encoding":"base64","data":"..."} with standard padded base64, preserving every byte.

See also: Output

`--no-header`(global, xff)

omit the header row from tabular --format (csv/tsv/aligned/markdown; on by default)

See also: Output

`--columns=FIELD,...`(global, xff)

columns for tabular --format, from the {field} vocabulary (e.g. path,size,mtime)

See also: Output

Tree comparison and diffs

`--compare[=status|diff|summary]`(global, xff)

compare two roots as selected statuses, a unified diff, or a summary

One of:

summary: shorthand for --compare=status --compare-select=none --summary=compare
status: one tab-separated selected result kind and relative path per record
diff: a unified tree diff suitable for saving as a patch

Requires exactly two roots. --compare=summary expands at its position to --compare=status --compare-select=none --summary=compare; later flags may override its settings. Combining the shorthand with bare --summary emits the comparison summary once. With an explicit --summary-scope, bare --summary also adds scoped totals; explicit groupings such as --summary=ext add their own tables. Bare --compare and --compare=status emit only discrepancies as tab-separated left-only, right-only, or different records. With --format=jsonl, each status is a JSON object containing record: comparison, status, relative path, left_root, and right_root. --compare=diff emits one unified tree diff, suitable for redirecting to a patch file; --diff-context and --diff-algorithm tune it. Unlike -diff TARGET, which is an expression action comparing each match from one walk with a templated target and therefore cannot discover target-only paths, --compare walks both roots independently and pairs the matches by relative path. The ordinary expression, ignore, hidden-file, archive, traversal, and -P / -H / -L symlink rules apply unchanged to each side; comparison itself enables none of them. Regular files are compared byte for byte (text and binary). Unfollowed symlinks are compared by target. Both walks complete before comparison records are emitted in bytewise relative-path order; --sort affects each walk, not that final order. In status mode, --path-encoding=escape makes control bytes in the relative path unambiguous. --summary / --summary=compare append results and combined bytes by entry type and status. Results count each pair once; bytes include both sides, including two copies of identical files. Directories and special entries are included; directory equality compares the entry kind, not its subtree. Ordinary summary groupings default to --summary-scope=compare: one table with left and right columns across all comparison categories. Explicit --summary-scope=all combines both sides; --summary-scope=root separates roots. --compare changes this default regardless of option order.

Affected by: --compare-select, --diff-algorithm, --diff-context, --summary-precision

`--compare-select=KIND,...`(global, xff)

tree-comparison results to emit: left-only, right-only, identical, different, all, or none

Selects comma-separated result kinds for --compare. The default is left-only,right-only,different, so equal files stay silent. all selects every kind. none or an empty value suppresses per-path output. Requires --compare; neither comparison-result nor ordinary summaries are filtered by this selection. identical is available with status output and is rejected with --compare=diff, where an unchanged file has no patch representation.

Affects: --compare

`--diff-algorithm=naive|direct|myers`(global, xff)

diff engine for -diff and tree diffs: naive, direct, or myers (the default)

One of:

myers: minimal diff, as git computes it (the default)
direct: line-by-line, no alignment search
naive: the simple longest-common-subsequence walk

Affects: -diff, --compare

See also: Comparing trees, -diff, --compare

`--diff-ignore=TOKEN,...`(global, xff)

normalize -diff comparison: ws, change, trail, blank, case, eofnl (comma-separated)

Sets the normalization used by -diff; the last value wins. It may be saved in user config or an explicit --xffrc=FILE, and a command-line value overrides the configured value. An empty value disables configured normalization. Tokens are ws, change, trail, blank, case, and eofnl, comma-separated.

Affects: -diff

See also: Comparing trees, Content, -diff

`--diff-ignore-matching=REGEX`(global, xff)

-diff ignores lines matching this regex (RE2)

Drops matching lines before -diff compares the two inputs. It may be saved in user config or an explicit --xffrc=FILE; the last value wins, so a command-line value overrides configuration. An empty value disables a configured expression. The expression uses RE2.

Affects: -diff

See also: Comparing trees, Content, -diff

`--diff-format=u|c|n|y`(global, xff)

default -diff format: u/unified (default), c/context, n/normal, y/side-by-side

One of:

u: unified, the diff -u shape (the default; also spelled unified)
c: context, the diff -c shape (also context)
n: normal, the plain diff shape (also normal)
y: side by side, the diff -y shape (also side-by-side)

Affects: -diff

See also: Comparing trees, Content, -diff

`--diff-context=N`(global, xff)

default -diff context lines (3); overrides --context for -diff, and -diff:uN overrides it

Affects: -diff, --compare

Affected by: --context

Output values and actions

`--hash-algorithm=<ALGO>`(global, xff)

default digest for -hash / {hash} / --summary=hash (sha256 default)

ALGO is one of:

blake2b: BLAKE2b, 512-bit
blake2b_256: BLAKE2b, 256-bit
blake3: BLAKE3 (fast, parallel)
md5: 128-bit legacy (fast, collision-broken)
sha1: 160-bit legacy (collision-broken)
sha224: SHA-2, 224-bit
sha256: SHA-2, 256-bit (the default)
sha384: SHA-2, 384-bit
sha3_224: SHA-3 (Keccak), 224-bit
sha3_256: SHA-3 (Keccak), 256-bit
sha3_384: SHA-3 (Keccak), 384-bit
sha3_512: SHA-3 (Keccak), 512-bit
sha512: SHA-2, 512-bit
sha512_224: SHA-2, 512/224 truncated
sha512_256: SHA-2, 512/256 truncated

Sets the default digest algorithm for the -hash action, the {hash} field, and --summary=hash. sha256 is the default; a -hash:ALGO spec or a {hash:ALGO} qualifier overrides it per use. --explain identifies a CLI default with no active consumer; suppressed output does not count.

See also: Fields, Output

`--hash-encoding=hex|base64`(global, xff)

default -hash / {hash} / --summary=hash rendering: hex (default) or base64

One of:

hex: lower-case hex digits, as the sha256sum family prints (the default)
base64: standard padded base64 (RFC 4648), the Subresource-Integrity spelling

Used by hash actions, fields, and --summary=hash unless that use specifies its own encoding. --explain identifies a CLI default with no active consumer; suppressed output does not count.

See also: Fields, Output

`--path-encoding=raw|escape`(global, xff)

plain-output path byte encoding: raw (verbatim, default) or escape (C-escape controls)

One of:

raw: the path's bytes verbatim, as find writes them (the default)
escape: C-escape control bytes, so a newline in a name cannot forge a line

See also: Output

`--template=TEMPLATE`(global, xff)

render each match through a field template ({path}, {name}, ...)

See also: Output, Fields

`--implicit-print=yes|no`(global, xff)

force the default -print on or off

One of:

yes: print every match even when the expression has its own action (also on / true / 1)
no: never add the default print (also off / false / 0)

See also: Output

Archive creation

`--root=NAME=PATH`(global, xff, command-line-only)

add a named search root; use NAME as its archive destination directory

Command-line only; rejected in configuration files.

Command-line only, like positional root operands. Repeatable. Each name must be a distinct single directory component; . and .., path separators, and control characters are rejected. A directory root contributes NAME/relative/path; a file root contributes NAME/basename. The same physical path may have different names. Named and positional roots retain their argument order, except when --sort explicitly sorts roots. Names affect archive destinations; ordinary path output still uses the input paths. Duplicate root names are errors even with --pack-duplicates=first.

Affects: --pack, --pack-duplicates, --sort

See also: Archives, --pack, --pack-duplicates, --sort

`--pack=FILE`(global, xff)

write every match into a new archive at FILE instead of listing them

The counterpart of --archive: instead of reading a container the walk BUILDS one, so the member list comes from the whole expression vocabulary rather than from a shell pipeline into tar. The output NAME picks the format - --help=archive lists exactly what this binary writes, from the writer's own table rather than a copy kept here, and the single-word shortcuts (.tgz, .txz, .tbz2, .tzst, .tlz, .taZ) mean what they do everywhere else; a name carrying no format is a usage error reported BEFORE the walk, since finding out afterwards would waste the traversal. Each member is stored under the entry's path relative to the search root it was found under, in the order the walk produced it - so --sort decides the order inside the archive. Member destinations are normalized; --pack-duplicates controls collisions. Like --summary it is a sink: it replaces the per-match listing, while explicit actions still run, so add -print to watch what goes in. The archive is written after the walk and renamed into place only when complete, so an interrupted run leaves no half archive and an existing FILE survives a failed one. A file the walk meets that IS the output is skipped rather than packed into itself. An archive MEMBER cannot be packed: reading files out of one container to re-pack them into another is its own feature, and until it exists the run is refused rather than quietly short. A build-time extra, like --archive.

Affects: --sort

Affected by: --root, --pack-duplicates, --pack-option, --pack-level

`--pack-duplicates=error|first`(global, xff)

reject duplicate archive destinations or keep the first input

One of:

error: reject duplicate normalized member destinations (the default)
first: keep the first input for each destination and skip later duplicates

Defaults to error. Member destinations are normalized before comparison: leading and interior ./, repeated separators, and trailing separators do not distinguish names. first keeps the earliest collected input and skips later copies; it does not rename them. Duplicate validation runs before archive output creation and also applies to --dry-run. An error reports both source paths and preserves any existing destination archive.

Affects: --pack

Affected by: --root

`--pack-option=NAME=VALUE|@FILE.json`(global, xff)

tune how --pack writes: repeatable, last value for a NAME wins

The general knob behind --pack-level. NAME is XFF's own vocabulary, not the archive library's: each name is translated to whatever the linked writer calls the same thing, so an unknown name is a usage error rather than a silent no-op, the accepted set is listed by --help=archive straight from the writer's table, and swapping or upgrading that library changes a translation table instead of the flags you type. A name that exists but does not apply to the chosen output format is refused too, naming the formats it does apply to - zip64 is a zip idea, threads is not a gzip one. Everything is checked before the walk starts, so a typo costs no traversal and writes no file. --pack-option=@FILE.json reads one JSON object whose keys are option names and whose values are strings, integers, or booleans; booleans become yes or no. File and inline forms may be repeated and are expanded in command-line order, so the last value for a name wins across both forms.

Affects: --pack

`--pack-level=N`(global, xff)

compression level for --pack (gzip/xz/lzip/lzma/zip 0-9, bzip2/lz4 1-9, zstd 1-22)

How hard the compressor works, on the scale the chosen format uses; left alone it is the format's own default. Exactly --pack-option=level=N, kept as its own spelling because it is the common knob for compressors that expose a level - the same relationship -Z has to --archive-write. On a plain .tar it is a usage error rather than a no-op, because there is no compressor to set a level on and a silently ignored level reads as a smaller archive that never arrives. Legacy Unix compress has no level knob, so .tar.Z refuses this option too.

Affects: --pack

Statistics

`--summary-scope=SCOPE,...`(global, xff)

summarize roots or collect comparison column groups

One of:

all: combine all input roots
root: separate input roots
left-only: comparison entries present only on the left
right-only: comparison entries present only on the right
different: different pairs counted once, with combined sizes
identical: identical pairs counted once, with combined sizes
left-total: all participating left entries
right-total: all participating right entries
left: alias for left-total
right: alias for right-total
diff: left-only,right-only,different
compare: left-total,right-total

Selects root populations or collects ordered comparison column groups for each ordinary --summary grouping. all combines every root; root separates input roots. Without an explicit scope, the default is all outside comparison and compare when --compare is active, regardless of option order. An explicit scope overrides that conditional default; repeated scopes use the last occurrence. Comparison scopes require --compare. compare expands to left-total,right-total; diff expands to left-only,right-only,different. left and right alias left-total and right-total; use left-only and right-only for unmatched entries. Output uses canonical names. Aliases expand in order and duplicate scopes are removed. Repeating the flag replaces the preceding list. Selection is independent of --compare-select. Selected comparison scopes share one table, with a column group per scope: count, count percentage, size, and size percentage. Side totals count their own entries and bytes. Categories count pairs once and sum both sides' bytes. Different grouping keys form a left-to-right transition row. Percentages use each column group's full population before --top; missing entries display a dash. Overlapping scopes are not added into a grand total. all counts both copies. Requires an active file summary such as --summary or --summary=ext; otherwise it is an error. --compare=summary expands to --summary=compare, which only counts comparison results and does not satisfy this requirement.

Affects: --summary

`--summary[=<GROUP>]`(global, xff)

count, count percentage, size, and size percentage table; repeatable

GROUP is one of:

none: clear all previously requested summaries
compare: comparison counts, combined sizes, and percentages by type and status; requires --compare
overall: one row aggregated over all matches
type: by file type
ext: by extension
lang: by programming language
mime: by media (MIME) type
user: by owner
owner: alias for user
group: by owning group
hash: by file digest (dedup: identical files share a bucket; reads every file)
hash-verification: verified / failed tally from exactly one reached -hasheq
{template}: by any field value, e.g. --summary='{ext}-{type}'

With --compare, bare --summary or --summary=compare appends result counts, combined left-plus-right sizes, and percentages by type and status, plus a total after the comparison output. With explicit --summary-scope, bare --summary also adds ordinary count and size statistics. Other groupings default to one left/right table with --compare (--summary-scope=compare), and combine all roots otherwise (--summary-scope=all). Explicit scope selection overrides this conditional default regardless of option order. --summary-scope selects combined, per-root, or comparison-category tables. Plain and Markdown tables identify their grouping unless --no-header is set. JSONL summary rows carry record=summary, a zero-based request index, the canonical summary grouping, and scope. Template groupings also retain their exact template. Comparison tables identify left_root and right_root; ordinary tables identify root (empty when combined). Request indices distinguish repeated groupings and survive table reordering. JSONL rows distinguish aggregate totals with is_total=true; data rows have is_total=false, even when their group is named total. Text and Markdown quote data labels that are empty, equal to total, or begin with a quote, keeping the aggregate label unambiguous. Outside comparison, replaces the per-match listing with an aggregate table: match count and total size per group (overall, by type, extension, programming language, media (MIME) type, user (owner), owning group, file digest, or hash-verification result). The categorical keys reuse the {mime}/{user}/{group}/{hash} field vocabulary; --summary=hash groups identical files into one bucket (a dedup count, reading every file through its active filesystem, including archive members). It uses --hash-algorithm and --hash-encoding, just like {hash}. --summary=hash-verification requires exactly one -hasheq and counts its verified or failed verdict even when that verdict makes the complete expression false; an entry that short-circuits before reaching -hasheq is not counted. Empty expected values and unreadable entries are failed, matching -hasheq itself. A {template} key groups by any field value (e.g. --summary='{ext}-{type}'); a single m// extraction key (--summary='{capture.NAME:m/re/\1/}') groups per extracted line, so a per-file command's multi-line output tallies per key (e.g. git-blame lines per author) - the size column is not meaningful there. Explicit groupings are repeatable: each request adds its own table (e.g. --summary=ext --summary=type), printed in request order within each scope. In comparison mode, bare --summary and --compare=summary reuse an existing comparison-results table; explicit --summary=compare requests remain repeatable. Comparison-result tables precede ordinary tables regardless of request order. Percentages use the complete table totals before --top; a zero denominator yields zero percent. Sizes sum entry metadata sizes, including directory metadata, never recursive subtree sizes. --format=markdown (or md) renders these tables with grouping-specific headings above their scopes and fixed summary columns. Scope/root labels and explanatory notes are Markdown bullet items so each stays on its own rendered line. Each accounting note stays with its table, separated from the next summary by a blank line. Exact bytes align with scaled sizes at the decimal boundary. --format=jsonl includes count_percent and size_percent alongside count and bytes. --top=N limits the rows of each, --summary-precision sets all summary percentage and scaled-size digits, and --format=jsonl emits one object per group for scripts. Supported summary formats are plain, aligned, jsonl, markdown (alias md), csv, and tsv; listing-only formats nul and tree are rejected. CSV/TSV exports use one header, explicit is_total identity, raw numeric metrics, and canonical scope-prefixed columns for comparison groups. They reject histograms, action output, and applicable dry-run previews. Per-path comparison records and expression actions retain their own output; use --compare-select=none or --compare=summary for summary-only exports.

Affected by: --summary-scope, --top, --summary-precision

`--histogram=BUCKET[:MEASURE]`(global, xff)

bar chart per bucket: a count or sum/mean/min/max of size|lines (repeatable)

A terminal reduction like --summary, drawn as bars. BUCKET groups the matches - a category (overall, type, ext, lang, mime, user (owner), or group) or a numeric-range field (size / lines by order of magnitude, depth per level, drawn as an ascending distribution). The optional :MEASURE is the bar's value - count (the default) or an aggregate sum(FIELD) / mean(FIELD) / min(FIELD) / max(FIELD) over a numeric FIELD (size or lines). A numeric metric needs an aggregator (ext:lines is an error; ext:sum(lines) is not). Repeatable and combinable with --summary - both are fed by one walk and replace the per-match listing. Bars scale to the tallest, use Unicode block characters on a UTF-8 locale (see --unicode) or ASCII '#' otherwise; --top=N keeps the N tallest and --format=jsonl emits one object per bar for scripts. --format=markdown renders bucket/value tables with numeric values right-aligned, including when combined with summaries. --no-header omits histogram headings and column headers. plain and aligned retain text bars; csv, tsv, nul, and tree are unsupported for histograms and fail before traversal or actions.

Affected by: --top, --histogram-width, --summary-precision

Sharded files

`--shards[=auto|SCHEME,...]`(global, xff)

collapse each set of sharded files (e.g. data-00000-of-00010) to one line

One of:

auto: recognize every built-in scheme (the default when bare --shards)
of: only <stem>-<index>-of-<total> (TFRecord-style)
dotnum: only <stem>.<NNN> (7-Zip-style volumes)
underscore: only <stem>_<NNN>

Recognizes sharded-file naming conventions and collapses each logical set to a single line instead of listing every shard. Bare --shards (or =auto) enables all built-in schemes: <stem>-<index>-of-<total> (of), <stem>.<NNN> (dotnum), and <stem>_<NNN> (underscore). Restrict to specific schemes with a comma list, e.g. --shards=of,dotnum. Grouping is per-directory; files that match no scheme are listed unchanged. Off by default. In --compare mode, entries and reductions remain physical files; --shards does not collapse them or infer a whole-set comparison result. Its scheme selection still applies to -shard-status.

See also: Statistics

`--shards-show=first|wildcard|count`(global, xff)

how a collapsed shard set's line reads (default first)

One of:

first: the representative (lowest-index) shard's path (the default)
wildcard: the masked-index name, e.g. arc.??? (or f- idx -of-003)
count: the wildcard name plus the shard count, e.g. arc.??? (3 shards)

Picks each collapsed set's display: first = the representative (lowest-index) shard's path; wildcard = the masked-index name (the index digits shown as ???); count = the wildcard name plus the shard count. An incomplete set is always annotated (present/expected - INCOMPLETE). Only meaningful with --shards.

See also: Statistics

`--shards-dedup=first|mtime|error`(global, xff)

how same-index shard duplicates are resolved (default first)

One of:

first: keep the lexicographically-first name among same-index copies (the default)
mtime: keep the newest by modification time (ties break on name)
error: treat a same-index duplicate as an error (non-zero exit)

When two files are the same logical shard (they differ only by an opaque tail, e.g. a regeneration id), --shards-dedup picks which is the representative: first keeps the lexicographically-first name; mtime keeps the newest; error treats the duplicate as an error and fails the run (non-zero exit). Also selects the representative used when -shard-status classifies physical files.

See also: Statistics

`--shard-pattern=REGEX`(global, xff)

a custom shard scheme via a named-capture regex (repeatable); the escape hatch

Defines a custom sharded-file scheme for --shards and -shard-status when the built-ins do not fit. REGEX is an RE2 pattern with named groups: (?P<stem>...) and (?P<index>...) are required, (?P<total>...) and (?P<dup>...) are optional. Repeatable; the patterns are tried in order, before the built-in schemes.

See also: Statistics

Content-match output

`--count, -c`(global, xff)

with -grep, print a per-file matching-line count (path:count) instead of the lines

Affects: -grep

`--context=SPEC`(global, xff)

-grep context lines: N both sides, or A:N,B:N,C:N for after/before/both

--context=2 is grep's -C 2 (two lines either side); the A / B / C keys inside the value select one side (--context=A:3,B:1), which is what --after-context and --before-context spell one at a time. xff has NO single-dash -A / -B / -C: those letters are unclaimed for now (see TODO.md), and a single-dash flag would be an expression primary under xff's dash-count rule rather than a whole-run option. A final symmetric before/after context also supplies the default for contextual -diff output, unless --diff-context or a per-action count overrides it.

Affects: -grep, -diff, --diff-context

See also: Content, -grep, -diff, --diff-context

`--after-context=N`(global, xff)

with -grep, print N lines of context after each match (= --context=A:N)

Together with the other context settings, a final symmetric context also supplies the default for contextual -diff output unless --diff-context or a per-action count overrides it.

Affects: -grep, -diff

See also: Content, Regex matching, -grep, -diff

`--before-context=N`(global, xff)

with -grep, print N lines of context before each match (= --context=B:N)

Together with the other context settings, a final symmetric context also supplies the default for contextual -diff output unless --diff-context or a per-action count overrides it.

Affects: -grep, -diff

See also: Content, Regex matching, -grep, -diff

Result limits

`--max-results=N`(global, xff)

list at most N matched entries without stopping or truncating reductions

Caps the implicit result listing after the whole expression, across every branch and every per-instance -first / -top filter. It does NOT stop traversal: --summary, --histogram, --count, and archive packing still see the complete matched set rather than silently reporting a partial walk. Explicit expression actions (-print, -grep, -exec, and friends) keep their own positional semantics and are not suppressed; use -first or -top before an action to cap the entries that reach it. With one capped filter this flag is usually redundant; its distinct use is an aggregate ceiling such as $ -type f -first 10 $ -o $ -type d -first 5 $ --max-results=12. Last occurrence wins. A malformed or negative count is a usage error; 0 lists none.

`--top=N`(global, xff)

with --summary or --histogram, keep only the N largest/tallest groups

Requires a non-negative integer; 0 removes the limit. Last occurrence wins. Ordinary summary groups rank by bytes, then count, then name; comparison-scope tables rank by the sum of displayed column-group bytes, including overlap. Extraction summaries rank by count because they have no byte dimension. Totals and percentage denominators include groups omitted by the limit. When groups are omitted, summary tables state how many are shown out of the complete set; JSONL rows add groups_shown and groups_total. Comparison scopes count distinct group keys across the selected columns, including overlapping scopes only once. Comparison-result summaries always show every type and status; --top does not truncate them. Numeric-range histograms retain every range; only categorical histogram buckets are top-limited.

Affects: --summary, --histogram

See also: Statistics, --summary, --histogram

Statistics display

`--histogram-width=N`(global, xff)

cell width the tallest --histogram bar fills (default 40)

Requires a positive integer; zero, negative, malformed, and overflowing values are errors. Last occurrence wins.

Affects: --histogram

`--summary-precision=N`(global, xff)

fraction digits for summary percentages and human-readable sizes (default 2)

Accepts integers from 0 through 9; other values are errors. Last occurrence wins. Applies to ordinary and comparison summaries, including JSON percentage fields, and histogram means. Exact byte counts stay integers.

Affects: --summary, --compare, --histogram

Terminal display

`--color[=auto|always|never]`(global, xff)

colorize the plain listing by file type and language: auto (a tty), always, or never

One of:

auto: colour only when stdout is a terminal (the default; a bare --color is always)
always: colour even through a pipe or pager (also on / yes / true / 1)
never: no colour at all (also off / no / false / 0)

Colorizes the plain listing by file type and, when the active language vocabulary supplies a colour, programming language. auto colorizes only when stdout is a terminal and NO_COLOR is unset; always forces color even through a pipe or pager and deliberately overrides NO_COLOR; never disables it.

Affected by: --color-scheme

See also: Output, Environment, --color-scheme

`--color-scheme=<SCHEME>`(global, xff)

which palette colour comes from: the terminal's ls theme, or xff's own

SCHEME is one of:

auto: ls OR xff: the theme when $LS_COLORS / $LSCOLORS is set, else xff's scheme (the default; also spelled ls+xff, ls-or-xff or default)
ls: the theme alone ($LS_COLORS, else $LSCOLORS): what it omits prints plain, as in ls
merged: the theme where it speaks, xff's type/language colour where it does not (also ls-and-xff)
xff: xff's built-in type and language scheme, ignoring $LS_COLORS

Colour is a whole-run choice, so this one palette is used by every surface that colours - the plain listing and -ls alike; they cannot disagree. $LS_COLORS is the variable ls and dircolors use, and xff reads the same keys: the two-letter types (di, ln, ex, pi, so, bd, cd, fi) and the per-extension *.tar= entries. Where only BSD's $LSCOLORS is set - the macOS case - that is read instead: its 11 letter pairs carry the same types in a fixed order, with no way to say "leave this plain" and no per-extension entries, so merged is the interesting scheme there. $LS_COLORS wins when both are set, being the richer format. Both variables are read on every platform rather than one per OS: which one is SET is better evidence than which system this is (a macOS shell with GNU coreutils is themed through $LS_COLORS, and $LSCOLORS is not macOS-only), and the fixed 22-character shape makes the BSD one self-validating. "Use ls's colours" turns out to mean three different things, so each has its own name, spelled the way logic spells it: + is OR, and the merge is AND. auto (the default, also ls+xff or ls-or-xff) is the theme OR xff's scheme - a theme that is set at all is the whole answer, and with none set xff's scheme is, so the decision is per VARIABLE; default is a fourth spelling of it, for a config file that wants whatever the default currently is. ls is the theme ALONE, so a type it never mentions prints uncoloured exactly as in a real ls listing (and with no theme set, nothing is coloured). merged (also ls-and-xff) is the theme AND xff's scheme, merged per KEY: the theme where it speaks, xff's colour for every key it omits - for a sparse theme you want filled in. (ls&xff is deliberately not accepted: an unquoted & backgrounds the command.) xff ignores $LS_COLORS entirely. In xff's scheme a regular non-executable file uses the active language vocabulary's #RRGGBB colour when present. A theme's matching extension or fi value wins; ls and a themed auto do not add language colours, while merged uses one only for a key the theme omitted. Executables and non-regular files retain their type colours. An EMPTY value in the theme (di= or fi=) is it saying "leave these plain" and is honoured as such; a malformed entry is skipped rather than failing the run, as in ls. Whether colour is emitted at all is --color's business, not this flag's.

Affects: --color

`--unicode[=auto|always|never]`(global, xff)

--format=tree connectors: auto (a UTF-8 locale), always (Unicode), or never (ASCII)

One of:

auto: Unicode connectors when the locale is UTF-8, else ASCII (the default)
always: force the Unicode connectors (also on / yes / true / 1)
never: force the ASCII connectors (also off / no / false / 0)

Selects the box-drawing characters --format=tree connects nodes with. auto uses Unicode when the locale (LC_ALL / LC_CTYPE / LANG) is UTF-8, else ASCII; always forces the Unicode connectors; never forces the ASCII ones.

See also: Output, Environment

`--human[=si|iec|off]`(global, xff)

size units for -ls / --summary: si (kB/MB, default), iec (KiB/MiB), off (bytes); xff -> si

One of:

si: powers of 1000: kB, MB, GB (the default; also 1000, --si, a bare --human)
iec: powers of 1024: KiB, MiB, GiB (also 1024)
off: plain byte counts, no unit suffix

See also: Output, Environment

`--si`(global, xff)

human sizes in SI (kB/MB, 1000^N); an alias for --human=si (the --human default)

See also: Output, Environment

`--buffer[=auto|off|all|N[kMGT]|NMB|NMiB]`(global, xff)

buffer to size columns (-ls / tables): auto, off, all, N[kMGT] rows, or NMB/NMiB bytes

Row windows use a bare count or decimal k/M/G/T multiplier. Byte budgets require an explicit trailing B: B/kB/MB/.../EB are SI, while KiB/MiB/.../EiB are IEC. The distinct suffixes keep rows and bytes unambiguous. Malformed, negative, and overflowing limits are errors before traversal. off or 0 disables column buffering; all requests the complete row set.

See also: Output, Environment

`--help-format=plain|markdown|html|roff`(global, xff, command-line-only)

renderer for any help target: plain (default), markdown (md), html, or roff

One of:

plain: terminal text; respects width, color, and paging
markdown: Markdown document; no terminal wrapping or colors
md: alias for markdown
html: standalone HTML document; no terminal wrapping or colors
roff: man-page source; terminal formatting and paging follow --man

Command-line only; rejected in configuration files.

Requires help output, including a topic, flag, index, or the full reference. For example, --help=notice --help-format=markdown. Markup output ignores terminal --width and --color; Markdown and HTML disable automatic paging, while explicit --pager=always or a pager command still applies. Roff uses the same terminal formatting and paging as --man. Conflicting format selections are errors, including conflicts with --man (which selects roff).

See also: Output, Environment

`--width[=auto|auto:COLS|none|COLS]`(global, xff)

width for plain help and comparison summaries: capped auto, auto, none, or a column count

Wraps the flowing text of --help and --help=TOPIC to a column width. Also bounds plain/aligned comparison-summary tables: scopes use grouped column headers when they fit, or labelled rows in one table when they do not. Numeric cells are never truncated; a width below one metric row may overflow. The default is auto:110. auto:COLS caps automatic width at COLS, using the cap when detection is unavailable; caps below 40 are errors. Explicit auto (also bare --width) is uncapped and uses $COLUMNS when set, otherwise the terminal width when stdout is a terminal, otherwise unlimited width. none (or 0) disables wrapping; a positive integer sets a fixed width (at least 40 columns); 60 or more is recommended for readability. Aligned help vocabulary tables and example blocks keep their own layout. Does not affect the file listing, comparison-results table, summary legends or path headings, --man, or formatted full help. Save a personal preference such as --width=auto:100 in the unsectioned user INI at <OS account home>/.config/xff/config. Explicit CLI width overrides the preference. Help reads only automatic system/user preferences, including selected named sections; it never loads .xffrc files or executes configured actions. Unavailable or invalid automatic preferences are ignored for help so configuration remains repairable.

See also: Output, Environment

Exit code control

`--quiet, -q`(global, xff)

suppress output; exit 0 if anything matched, else 1 (-q: grep-compatible)

In comparison mode, a match means a left-only, right-only, or different entry in the matched population: 0 means discrepancies, 1 means none, and 2 means an error. --compare-select and summary output do not change this status.

See also: Output

`--exit-match`(global, xff)

keep output; exit 0 if anything matched, else 1

See also: Output

Safety

`--block-policy-categories=LIST`(global, xff, config-only)

select categories with dedicated blocking controls (config only)

One of:

archive: use dedicated controls for archive output and member edits
temp: use dedicated controls within the declared temporary root
output: use dedicated controls within the declared output root

Selects separate controls; this directive itself neither blocks nor allows operations. A comma-separated category list; empty means ordinary file controls for all categories (default). archive, temp, and output are supported. Allowed once before all sections in system or user configuration. Each file chooses its own policy, including for its named sections. Neither named sections, explicit .xffrc files, nor the CLI may set it. See --help=safety for the operation table and archive replacement tradeoff.

See also: Safety

`--temp-root=PATH`(global, xff, config-only)

declare an existing absolute temp root (config only)

Allowed once in unsectioned system or user INI; a system declaration wins. Permissions cover descendants recursively; the root itself remains protected. Roots and descendant traversal must not contain symlinks. INI ${NAME} substitutions are allowed, but trust the caller-controlled environment to choose the root; use literal paths for fixed administrator boundaries. See --help=config and --help=safety.

See also: Safety

`--output-root=PATH`(global, xff, config-only)

declare an existing absolute output root (config only)

See also: Safety