RH(1)

🌈 `rh(1)` — rawhide: find files using pretty C expressions 🌈

(User Commands)

✨ NAME ✨

rh — short for rawhide: find files using pretty C expressions. 💖

🌸 SYNOPSIS 🌸

okay bestie, here's the whole usage situation, preserved exactly so nothing gets lost:

        usage: rh [options] [path...]
        options:
          -h --help    - Show this help message, then exit
          -V --version - Show the version message, then exit
          -N           - Don't read system-wide config (/etc/rawhide.conf)
          -n           - Don't read user-specific config (~/.rhrc)
          -f-          - Read functions and/or expression from stdin
          -f fname     - Read functions and/or expression from a file
         [-e] 'expr'   - Read functions and/or expression from the cmdline

        traversal options:
          -r           - Only search one level down (same as -m1 -M1)
          -m #         - Override the default minimum depth (0)
          -M #         - Override the default maximum depth (system limit)
          -D           - Depth-first searching (contents before directory)
          -1           - Single filesystem (don't cross filesystem boundaries)
          -y           - Follow symlinks on the cmdline and in reference files
          -Y           - Follow symlinks encountered while searching as well

        alternative action options:
          -x 'cmd %s'  - Execute a shell command for each match (racy)
          -X 'cmd %S'  - Like -x but run from each match's directory (safer)
          -U -U -U     - Unlink matches (but tell me three times), implies -D

        output action options:
          -l           - Output matching entries like ls -l (but unsorted)
          -d           - Include device column, implies -l
          -i           - Include inode column, implies -l
          -B           - Include block size column, implies -l
          -s           - Include blocks column, implies -l
          -S           - Include space column, implies -l
          -g           - Exclude user/owner column, implies -l
          -o           - Exclude group column, implies -l
          -a           - Include atime rather than mtime column, implies -l
          -u           - Same as -a (like ls(1))
          -c           - Include ctime rather than mtime column, implies -l
          -v           - Verbose: All columns, implies -ldiBsSac (unless -xXU0L)
          -0           - Output null chars instead of newlines (for xargs -0)
          -L format    - Output matching entries in a user-supplied format
          -j           - Output matching entries as JSON (same as -L "%j\n")

        path format options:
          -Q           - Enclose paths in double quotes
          -E           - Output C-style escapes for control characters
          -b           - Same as -E (like ls(1))
          -q           - Output ? for control characters (default if tty)
          -p           - Append / indicator to directories
          -t           - Append most type indicators (one of / @ = | >)
          -F           - Append all type indicators (one of * / @ = | >)

                           * executable
                           / directory
                           @ symlink
                           = socket
                           | fifo
                           > door (Solaris only)

        other column format options:
          -H or -HH    - Output sizes like 1.2K 34M 5.6G etc., implies -l
          -I or -II    - Like -H but with units of 1000, not 1024, implies -l
          -T           - Output mtime/atime/ctime in ISO format, implies -l
          -#           - Output numeric user/group IDs (not names), implies -l

        debug option:
          -? spec      - Output debug messages: spec can include any of:
                           cmdline, parser, traversal, exec, all, extra

        rh (rawhide) finds files using pretty C expressions.
        See the rh(1) and rawhide.conf(5) manual entries for more information.

        C operators:
          ?:  ||  &&  |  ^  &  == !=  < > <= >=  << >>  + -  * / %  - ~ !

        Rawhide tokens:
          "pattern"  "pattern".modifier  "/path".field  "cmd".sh
          123 0777 0xffff  1K 2M 3G  1k 2m 3g  $user @group  $$ @@
          [yyyy/mm/dd] [yyyy/mm/dd hh:mm:ss]

        Glob pattern notation:
          ? * [abc] [!abc] [a-c] [!a-c]
          ?(a|b|c) *(a|b|c) +(a|b|c) @(a|b|c) !(a|b|c)
          Ksh extended glob patterns are available here (see fnmatch(3))

        Pattern modifiers:
                        .i            .re           .rei
          .path         .ipath        .repath       .reipath
          .link         .ilink        .relink       .reilink
          .body         .ibody        .rebody       .reibody
          .what         .iwhat        .rewhat       .reiwhat
          .mime         .imime        .remime       .reimime
          .acl          .iacl         .reacl        .reiacl
          .ea           .iea          .reea         .reiea
          .sh
          Case-insensitive glob matching is available here (i)
          Perl-compatible regular expressions are available here (re)
          Access control lists are available here (acl)
          Extended attributes are available here (ea)

        Built-in symbols:
          dev           major         minor         ino           mode
          nlink         uid           gid           rdev          rmajor
          rminor        size          blksize       blocks        atime
          mtime         ctime         attr          proj          gen
          nouser        nogroup       readable      writable      executable
          strlen        depth         prune         trim          exit
          now           today         second        minute        hour
          day           week          month         year          IFREG
          IFDIR         IFLNK         IFCHR         IFBLK         IFSOCK
          IFIFO         IFDOOR        IFMT          ISUID         ISGID
          ISVTX         IRWXU         IRUSR         IWUSR         IXUSR
          IRWXG         IRGRP         IWGRP         IXGRP         IRWXO
          IROTH         IWOTH         IXOTH         texists       tdev
          tmajor        tminor        tino          tmode         tnlink
          tuid          tgid          trdev         trmajor       trminor
          tsize         tblksize      tblocks       tatime        tmtime
          tctime        tstrlen

        Reference file fields:
          .exists       .dev          .major        .minor        .ino
          .mode         .type         .perm         .nlink        .uid
          .gid          .rdev         .rmajor       .rminor       .size
          .blksize      .blocks       .atime        .mtime        .ctime
          .attr         .proj         .gen          .strlen       .inode
          .nlinks       .user         .group        .sz           .accessed
          .modified     .changed      .attribute    .project      .generation
          .len

        System-wide and user-specific functions can be defined here:
          /etc/rawhide.conf          ~/.rhrc
          /etc/rawhide.conf.d/*      ~/.rhrc.d/*

🦋 INTRODUCTION 🦋

okay so Rawhide (rh) is the moment: it lets you search for files on the command line using expressions and user-defined functions in a mini-language inspired by C. It's giving find(1), but honestly more fun to use. Your search criteria can be super readable and self-explanatory and/or very concise and typeable, and you can create your own lexicon of search terms. The output can include lots of detail, like ls(1). 💖

💖 DESCRIPTION 💖

rh (Rawhide) searches the filesystem, starting at each path you give it, for files that make the given search criteria expression true. If no search paths are given, the current working directory is searched. periodt.

You can feed the search criteria expression from a few places: from the command line with the -e option, from a file with the -f option, or from standard input (stdin) with -f-. If there is no explicit -e option expression, rh looks for an implicit expression among any remaining command line arguments. If no expression is specified, the default search criteria is the expression 1, which matches all filesystem entries. iconic.

An rh expression is a C-like expression that can call user-defined functions. These expressions can contain all of C's conditional, logical, relational, equality, arithmetic, and bit operators. no cap.

Numeric constants can be decimal, octal, or hexadecimal integers. Decimal constants can have scale units (e.g., 10K). cute.

There are built-in symbols that represent each candidate file's inode metadata. These are the fields in the corresponding stat(2) structure (e.g., st_mode, st_uid, st_size, st_mtime, ...). See stat(2) for details. For convenience, the "st_" prefix is omitted from the symbol names (e.g., st_mtime is used as mtime). slay.

Other built-in symbols represent the constants defined by C's <sys/stat.h> header file. These are useful for interpreting the mode in order to identify file types and permissions. The "S_" prefix is omitted from the symbol names (e.g., S_IFMT is used as IFMT). 💅

Other built-in symbols represent various useful values and constants, control flow, more file information, and candidate symlink target inode metadata.

File glob patterns and Perl-compatible regular expressions (regexes) can be used to match files by their name, path, symlink target path, body, file type description, MIME type, access control list, and extended attributes. obsessed.

Search criteria can also include comparisons with the inode metadata of arbitrary reference files, and the exit success status of arbitrary shell commands. yes bestie.

Functions are a means of referring to an expression by name. They allow complex expressions to be composed of simpler ones. They also allow you to create your own lexicon of search terms for finding files.

There is a default standard library of functions to start with. It provides a high-level interface to the built-in symbols mentioned above, and makes rh easy to use. See rawhide.conf(5) for details. 🫶

💅 OPTIONS 💅

-h, --help — Display the help message, then exit. The --help option must not be used with any other command line options or arguments.
- The help message summarizes the command line usage, and presents concise lists of the search criteria language operators, special tokens, glob pattern notation, pattern modifiers, built-in symbols, reference file fields, and the locations of configuration files.
- Some features are not available on all systems: Ksh extended glob patterns, case-insensitive glob matching, Perl-compatible regular expressions (regexes), access control lists, and extended attributes. The help message states which optional features are available on the local system.
- See the SYNOPSIS section above for details.
-V, --version — Display the version message, then exit. The --version option must not be used with any other command line options or arguments.
-N — By default, rh first reads system-wide configuration from /etc/rawhide.conf (or similar), and then (in lexicographic order) from any files in the /etc/rawhide.conf.d directory (or similar) whose names do not start with dot ("."). This option suppresses that behaviour.
-n — By default, rh then reads user-specific configuration from ~/.rhrc, and then (in lexicographic order) from any files in the ~/.rhrc.d directory whose names do not start with dot ("."). This option suppresses that behaviour.
-f-, -f fname — okay so after rh has read all the config files, this bad boy makes it read code from the file named by fname. 🎀 And plot twist: if there's also a directory whose name is fname with .d slapped on the end, rh goes and reads (in lexicographic order, so alphabetically bestie) any files in there whose names don't start with a dot ("."). If fname is itself a directory, rh reads any files in there the same way. And if fname is -, the code comes from standard input (stdin). You can drop -f more than once, but using - (stdin) more than once is an error, no cap.

Each file can hold zero or more function definitions and/or a trailing file test expression at the end. If a file does have one of those trailing file test expressions, that's what gets used to match files — unless another file test expression shows up in a later -f option file, or via -e, or in any of the leftover command line arguments. 💅

-e 'expr' — reads code straight out of the expr argument itself. Supplying -e more than once is an error, periodt.

The expr argument can contain zero or more function definitions and/or a trailing file test expression. -e gets processed after any -f options, so it can totally use any functions you defined via -f. And if expr contains a file test expression (which, like, it's expected to), it overrides any default file test expression from a configuration file or from an -f option file. 👑

Normally the -e argument is what supplies the file test expression used for the file search. But since a lot of the operators are also shell meta-characters, and rh expressions can have spaces in them, it's strongly recommended that you wrap expr in single quotes ("'"). Trust. 🫶

If you don't supply an explicit file test expression via -e, then rh peeks at whatever command line arguments are left over to sniff out an implicit file test expression. Here's the vibe check it runs:

If a command line argument is a path that actually exists in the filesystem, it's treated as a filesystem entry to search. ✨
Otherwise, if it contains characters that are likely to show up in an expression but unlikely to show up in most filesystem paths (i.e., "?:|&^=!<>*%$\"\\[]{};\n"), it's treated as a file test expression.
Otherwise, if it looks like a filesystem path (i.e., it has a slash character ("/") in it and some apparent ancestor directory really does exist in the filesystem), it's treated as a filesystem entry — one that just happens not to exist. 🙈
Otherwise? File test expression. Simple as that.

Only the first suitable command line argument gets interpreted as a file test expression. Everything else on the command line is all search paths, bestie.

This means it's almost always possible to not even bother typing -e at all. It also means you can put search paths before and/or after the file test expression, like:

$ rh -e 'expr' dir1 dir2
$ rh 'expr' dir1 dir2
$ rh dir1 'expr' dir2
$ rh dir1 dir2 'expr'

You only really need to be explicit with -e when the file test expression might happen to be identical to an existing filesystem entry relative to the current working directory (e.g., touch file; rh -e 'file' path), or (less likely) when the expression starts with a minus sign ("-") and would otherwise get mistaken for a command line option. 😭

You can also need an explicit -e if you want the file test expression to sit to the left of any command line options on (most) systems where all non-option command line arguments have to come after all the options and their arguments (e.g., rh -e 'expr' -X 'cmd %S' dir). That doesn't apply to Linux with GNU glibc though, which is chill and flexible about command line option parsing. 💀

And if no file test expression turns up anywhere? The default file test expression is 1, which matches every filesystem entry. Slay.

🌀 Traversal options 🌀

-r — makes rh only report (or act on) the immediate contents of the starting search directories. The starting search directories themselves are excluded 🚫, and the contents of any sub-directories of the starting search directories don't get searched either. This is literally the same as -m1 -M1 (see next).

This option and -m are mutually exclusive.

This option and -M are mutually exclusive.

-m # — overrides the default minimum search depth to report (or act on). By default the minimum search depth is zero, meaning the starting search directories get reported (or acted on) if they satisfy the file test expression. 🎯

So like, setting the minimum search depth to 1 suppresses reporting (or acting on) the starting search directories even if they match — now it only reports (or acts on) the matching entries among those directories' entries and their descendants.

Heads up though: this option does not stop file test evaluation above the minimum search depth. It only stops reporting (or acting on) matching entries. This matters when your search criteria involves the prune, trim, or exit built-ins (see rawhide.conf(5)), because those have control-flow side-effects when they get evaluated. Which is lowkey useful — it lets you skip sub-directories, or straight-up terminate a search, before anything is reported (or acted on). 🔥

This option and -r are mutually exclusive.

-M # — overrides the default maximum search depth to examine. By default that max is a very large system-imposed limit (e.g., 1019). 😳

Setting the maximum search depth to 1, for example, stops the search below the immediate children of the starting search directories. And setting it to 0 stops the search below the starting search paths themselves.

This option and -r are mutually exclusive.

-D — does a depth-first search. That means directories get examined and reported (or acted on) after their descendants, not before them. 🦋

This option is incompatible with the prune and trim built-ins (see rawhide.conf(5)). When you use -D, prune and trim just will not work — they won't prevent searching in sub-directories. 💀

Lowkey important: the -U option implies this one (see below).

-1 — limits the search to each starting search directory's filesystem only. So it stops rh from descending into directories that are mountpoints for other filesystems. 🚧
-y — by default rh does not follow symlinks. This option makes rh follow any symlinks supplied as command line arguments or reference files. But any candidate symlinks it encounters while searching are still not followed. 💅

Note: when a followed symlink is broken/dangling, instead of reporting it as an error, the resulting stat(2) structure fields will be those of the symlink itself. This might or might not be the behaviour you want. It's done for compatibility with the familiar behaviour of find(1). If you'd rather an attempt to follow a broken symlink got reported as an error, set the environment variable RAWHIDE_REPORT_BROKEN_SYMLINKS=1. The resulting stat(2) structure fields will still be those of the symlink itself, and searching will still continue, but you'll get an error message and the eventual exit status will be non-zero to indicate failure. 😭

This option is compatible with the symlink target-related built-ins (see rawhide.conf(5)) and the -L %Y format conversion (see below) — except for any symlinks on the command line. For those, the symlink target-related built-ins and the -L %Y format conversion will only ever get to see symlinks that are broken. 🙈

-Y — by default rh does not follow symlinks. This option makes rh follow any symlinks supplied as command line arguments or reference files, and any candidate symlinks encountered while searching. 👑

Note: when a followed symlink is broken/dangling, instead of reporting it as an error, the resulting stat(2) structure fields will be those of the symlink itself. This might or might not be the behaviour you want. It's done for compatibility with the familiar behaviour of find(1). If you'd rather an attempt to follow a broken symlink got reported as an error, set the environment variable RAWHIDE_REPORT_BROKEN_SYMLINKS=1. The resulting stat(2) structure fields will still be those of the symlink itself, and searching will still continue, but you'll get an error message and the eventual exit status will be non-zero to indicate failure. 🍓

This option is incompatible with the symlink target-related built-ins (see rawhide.conf(5)) and the -L %Y format conversion (see below). The only symlinks they'll ever get to see are broken ones. 💀

🎬 Alternative action options 🎬

By default, rh outputs each matching filesystem entry's full path starting from the search directory. These options give you alternative actions instead. They — plus the -l, -0, -L, and -j options — are all mutually exclusive. Pick one, bestie, you can't have them all. ✨

-x 'cmd' — executes the shell command specified by cmd via system(3) (i.e., via /bin/sh) for each matching entry. Supplying -x more than once is an error.

The cmd argument can contain %s, which gets replaced with the matching entry's full path starting from the search directory. It can also contain %S, which gets replaced with the matching entry's base name (or with "/" when the matching entry is the root directory (/), which has no base name, obviously). For example, given the matching file /etc/passwd, %s and %S would be replaced with "/etc/passwd" and "passwd", respectively. To include a literal per cent sign ("%") in the shell command, use %%. And it's an error if % isn't followed by s, S, or %. 🎀

Any shell meta-characters in the interpolated path or base name get quoted with preceding backslash characters ("\") to prevent shell command injection, so you do not need to put quote characters around %s or %S. Security said slay. 🔥

For this option, the %s interpolation is more likely to be useful than the %S interpolation. iykyk.

If any command exits with a non-zero exit status, rh itself will keep going, but it'll eventually exit with a non-zero exit status. 😭

This is basically the -exec action from POSIX find(1), and bestie, it suffers from the exact same huge pile of path-based race conditions as -exec 😭. On hosts where malicious local actors have write access to the directory tree you're searching, this is insecure, so like — don't generally use it, ok? It is much safer to use the -X option instead (see next 👀). Also note that piping the default output to a program like xargs(1) is insecure in exactly the same way. no cap.

Note: if the user's $PATH environment variable includes the current working directory, or any other non-absolute paths, they get automatically removed first ✨. This is done for consistency with the -X option (see next) and the "cmd".sh "pattern" modifier (see rawhide.conf(5)), where this is needed for security. Which means you can't rely on $PATH to find an executable that's sitting in the current directory — you'd need an explicit path instead (e.g., -x './cmd %s'). periodt.

This option, and the -l, -0, -L, -j, -X, and -U options, are all mutually exclusive. one at a time, bestie 💅

**-X 'cmd'** — Execute the shell command specified by *cmd* via system(3)(i.e., via/bin/sh) for each matching entry. Supplying -X` more than once is an error. 🚨

It's like the -x option (see above), except the shell command is executed after safely changing the current working directory to the directory containing each matching entry. Which minimizes the number of path-based race conditions. she's careful like that 💖

The cmd argument can contain %s, which gets replaced with the matching entry's full path starting from the search directory. It can also contain %S, which gets replaced with the matching entry's base name (or with / when the matching entry is the root directory (/) which has no base name, obviously 🙈). For example, given the matching file /etc/passwd, %s and %S would be replaced with /etc/passwd and passwd, respectively. To include a literal per cent sign (%) in the shell command, use %%. It is an error if % is not followed by s, S, or %.

Any shell meta-characters in the interpolated path or base name are quoted with preceding backslash characters (\) to prevent shell command injection, so there is literally no need to place any quote characters around %s or %S. 🛡️

For this option, the %S interpolation is more likely to be useful than the %s interpolation. iykyk.

If any command exits with a non-zero exit status, rh itself will continue, but it will eventually exit with a non-zero exit status. she's patient, but she remembers 💀

This is similar to the -execdir action in GNU find(1), and so does not suffer from the same large number of path-based race conditions as the -exec action in POSIX find(1). It is much safer than the -x option, and should generally be used in preference. 👑

And if the user's $PATH environment variable includes the current working directory, or any other non-absolute paths, that could be dangerous, so they are automatically removed first.

Note: since the shell commands are executed from the directory containing each matching entry, if they do require the matching entry's full path starting from the search directory (i.e., %s), then it's best if the starting search paths are all absolute paths, so that %s is always an absolute path ✨. Otherwise, the shell command might need to change its current working directory back to the initial working directory. Also note that %s suffers from many path-based race conditions, which is insecure on hosts with malicious local actors that have write access to the directory tree being searched, and so should not generally be used. ⚠️

This option, and the -l, -0, -L, -j, -x, and -U options, are all mutually exclusive. pick one, babe 💅

-U -U -U — Unlink/Remove/Delete matching filesystem entries. 🗑️ Due to the destructive nature of this option, and the ease with which a single letter can be mistyped, this option must be supplied three times in order for it to take effect. It is an error to supply the -U option once or twice. yes, three. we're serious about this one 😤

This option implies the use of the -D option (see above) to ensure that each matching directory's matching entries are removed before it is. Directories can only be removed when they are empty, obviously.

If rh fails to remove any matching entry, it will continue, but it will eventually exit with a non-zero exit status.

This option is incompatible with the prune and trim built-ins (see rawhide.conf(5)). When this option is used, prune and trim will not work. They will not prevent unlinkage/removal/deletion in sub-directories. 💀

When this option is used with the -y or -Y option (see above), and a symlink to a directory is followed, the symlink's ultimate target directory's contents are searched, and any matches found there are removed, but the target directory itself is never removed. It isn't possible to remove a filesystem entry via a symlink to it, bestie — that's just not a thing 🦋. If the target directory itself matches the search criteria, the symlink to it is removed. Similarly, when a symlink to a non-directory is followed, and the symlink's ultimate target matches the search criteria, the symlink is removed, not the ultimate target. the link gets got, not the target 💅

This option, and the -l, -0, -L, -j, -x, and -X options, are all mutually exclusive.

💖 Output action options 💖

-l — By default, rh outputs each matching path on a line by itself. This option includes more details in a format similar to that of ls -l (but unsorted, don't come for her 🌸). The details included are the file type, permissions, existence of an access control list and/or extended attributes, number of hard links, user/owner, group, size (or comma-separated rdev major and minor device numbers), modified time, and path. For symlinks, the target path is also included at the end (preceded by ->).

Note that, unlike ls -l, for readable directories, the reported size is the number of entries they contain (excluding . and ..). For unreadable directories, it is the usual (undocumented) st_size field of the corresponding stat(2) structure. 🙈

If a file has a non-trivial access control list (ACL), this is indicated by a plus sign (+) at the end of the file type and permissions column (e.g., -rw-rw-r--+). If a file has any extended attributes (EA), this is indicated by an at sign (@) (e.g., -rw-rw-r--@). Note that this doesn't include the EAs that are used on Linux for ACLs and selinux(8) contexts, because they are not interesting enough (ACLs are already indicated by +, and selinux(8) contexts are ubiquitous, and they are indicated by . (see below)). If a file has both a (non-trivial) ACL and any (interesting) EAs, this is indicated by an asterisk character (*) (e.g., -rw-rw-r--*). If a file has neither, but it does have a selinux(8) context, this is indicated by a dot character (.) (e.g., -rw-rw-r--.). If a file has none of the above, there's just a space character (" ") at the end of the file type and permissions column. it's giving forensic detail and we're obsessed 🔥

This option, and the -0, -L, -j, -x, -X, and -U options, are all mutually exclusive.

-d — Include the device column. Implies the -l option.

This is the comma-separated major and minor device numbers of the device/filesystem that the matching file resides on. 🖥️

This column is first.

-i — Include the inode number column. Implies the -l option.

This column is after any device column, and before any block size column.

-B — Include the block size column. Implies the -l option.

This column is after any inode number column, and before any blocks column.

Note that this is just the preferred block size for efficient I/O on the matching file's filesystem. On some filesystems (e.g., zfs), this is specific to each file, rather than to the whole filesystem. ✨

Note that this is unrelated to the blocks column (see next). don't confuse the girlies 💅

-s — Include the blocks column. Implies the -l option.

This column is after any block size column, and before any space column.

Note that the number of blocks always refers to standardized 512-byte blocks, even when the filesystem's real block size is something else. math is math 🔢

-S — Include the space column. Implies the -l option.

The space occupied by a file is the number of 512-byte blocks multiplied by 512. This is usually larger than the size in bytes, but it can be smaller in the case of files with holes (and on filesystems with transparent compression). 🤯

This column is after any blocks column, and before the file type and permissions column.

-g — Exclude the user/owner column. Implies the -l option.
-o — Exclude the group column. Implies the -l option.
-a — Include the accessed time column in place of the modified time column. Implies the -l option.

If the -a/-u and -c options are both supplied, then both columns appear in place of the modified time column (with the accessed time column appearing before the inode changed time column). two for one, slay 💖

-u — Same as the -a option (like ls(1)). twin behavior, iconic 🫶
-c — Include the inode changed time column in place of the modified time column. Implies the -l option.

If the -a/-u and -c options are both supplied, then both columns appear in place of the modified time column (with the accessed time column appearing before the inode changed time column).

-v — Turn on verbose mode. 🔍 With the -l option, this option includes all possible columns (i.e., device, inode number, block size, number of blocks, space, file type, permissions, existence of an access control list and/or extended attributes, number of hard links, user/owner, group, size (or comma-separated rdev major and minor device numbers), modified time, accessed time, inode changed time, and path). she's showing off at this point and honestly? deserved 👑

With the -x or -X option, this option outputs each command before it is executed. When standard output (stdout) is a terminal, ? is output in place of any control characters to prevent terminal escape injection. 🛡️

With the -U option, this option outputs each matching path before it is removed. When standard output (stdout) is a terminal, ? is output in place of any control characters to prevent terminal escape injection.

With the -0 option, this option has no effect. 💀 nothing. zero. nada.

With the -L option, this option makes the %z format conversion on FreeBSD and Solaris output the non-compact form of NFSv4 access control lists (ACLs), rather than the default compact form. 🌀

-0 — drops a null character ("\0") after every matching path instead of the usual newline ("\n"). Bestie, this is the one you reach for when you're pairing with xargs -0 and your paths are out here containing chaos like newlines. 🫶

⚠️ But listen — because of a huge pile of path-based race conditions, piping output into something like xargs(1) is insecure on hosts where malicious local actors have write access to the directory tree being searched. So like… don't make it a habit, okay? Using the -X option instead is much safer (scroll up for that one 💅).

This option, plus the -l, -L, -j, -x, -X, and -U options, are all mutually exclusive. Pick one, queen. 👑

-L format — outputs selected info about matching entries, shaped by a format you supply. It's giving printf(3) and strftime(3) energy ✨. Supplying -L more than once is an error — just don't.

Unlike -l and -0, nothing gets appended for you — no newline, no null. Not one crumb. An empty -L argument (i.e., -L '') produces no output at all. Iconic minimalism, honestly.

This option, plus the -l, -0, -j, -x, -X, and -U options, are all mutually exclusive. 😌

🌸 the backslash escape sequences you can use 🌸

\a — Alert or Bell (BEL)
\b — Backspace (BS)
\c — Stop processing this format string and flush the output
\f — Form feed (FF)
\n — Newline or Line feed (LF)
\r — Carriage return (CR)
\t — Horizontal tab (HT)
\v — Vertical tab (VT)
\0 — Null byte (NUL)
\\ — A literal backslash ("\")
\NNN — The byte whose numeric value is NNN (1-3 octal digits)

A backslash followed by any other character is treated as an ordinary character, and both characters get output. No drama, no error. 🦋

💖 the `%` format conversion specifiers 💖

%% — A literal per cent sign ("%").
%p — The path, including the starting search directory.

When standard output (stdout) is a terminal, "?" is output in place of any control characters to prevent terminal escape injection. (Yes, this note shows up a lot down here — it's protecting you every time 🛡️)

%P — The path, excluding the starting search directory.

When standard output (stdout) is a terminal, "?" is output in place of any control characters to prevent terminal escape injection.

%f — The base name: the path minus any leading directories and the final slash character ("/"). Special case gem 💎: for the root directory (/), which has no base name, this is "/".