MTREE(8)

💖 MTREE(8) 💖

System Manager's Manual, but make it bestie-core. okay so this is literally the manual page for mtree, the map-a-directory-hierarchy icon, and we are going to get into every single detail. no skipping. periodt. 💅

---

🌸 NAME 🌸

mtree — map a directory hierarchy ✨

---

🦋 SYNOPSIS 🦋

mtree [-bCcDdejLlMnPqrStUuWx] [-i | -m] [-E tags] [-F flavor] [-f spec]
      [-I tags] [-K keywords] [-k keywords] [-N dbdir] [-O onlyfile]
      [-p path] [-R keywords] [-s seed] [-X exclude-file]

---

💅 DESCRIPTION 💅

The mtree utility compares a file hierarchy against a specification, creates a specification for a file hierarchy, or modifies a specification. like, it's giving “directory hierarchy glow-up” in three different directions. 🫶

The default action, if not overridden by command line options, is to compare the file hierarchy rooted in the current directory against a specification read from the standard input. Messages are written to the standard output for any files whose characteristics do not match the specification, or which are missing from either the file hierarchy or the specification. so if something's off, mtree is gonna say something. not in a mean way. in a “bestie, this doesn't match” way. 😭

The options are as follows, and yes, we're doing every single one:

✨ OPTIONS ✨

• -b — Suppress blank lines before entering and after exiting directories. no extra blank-line drama. 🎀
• -C — Convert a specification into a format that's easier to parse with various tools. The input specification is read from standard input or from the file given by -f spec. In the output, each file or directory is represented using a single line (which might be very long). The full path name (beginning with ./) is always printed as the first field; -K, -k, and -R can be used to control which other keywords are printed; -E and -I can be used to control which files are printed; and the -S option can be used to sort the output. one line per file, potentially huge, but so parseable. 💖
• -c — Print a specification for the file hierarchy originating at the current working directory (or the directory provided by -p path) to the standard output. The output is in a style using relative path names. cute relative-path vibes. 🌸
• -D — As per -C, except that the path name is always printed as the last field instead of the first. path name said “I'll go last,” and honestly? iconic. 👑
• -d — Ignore everything except directory type files. directories only. everyone else can leave. 💀
• -E tags — Add the comma separated tags to the “exclusion” list. Non-directories with tags which are in the exclusion list are not printed with -C and -D. it's giving guest list, but for tags. 🚫
• -e — Don't complain about files that are in the file hierarchy, but not in the specification. no extra yelling about extras. 🙈
• -F flavor — Set the compatibility flavor of the mtree utility. The flavor can be one of mtree, freebsd9, or netbsd6. The default is mtree. The freebsd9 and netbsd6 flavors attempt to preserve output compatibility and command line option backward compatibility with FreeBSD 9.0 and NetBSD 6.0 respectively. choose your fighter, but respectfully. 🦋
• -f spec — Read the specification from the file spec, instead of from the standard input.

If this option is specified twice, the two specifications are compared to each other rather than to the file hierarchy. The specifications will be sorted like output generated using -c. The output format in this case is somewhat reminiscent of comm(1), having “in first spec only”, “in second spec only”, and “different” columns, prefixed by zero, one and two TAB characters respectively. Each entry in the “different” column occupies two lines, one from each specification. spec vs. spec is honestly a whole rivalry arc. 😭

• -I tags — Add the comma separated tags to the “inclusion” list. Non-directories with tags which are in the inclusion list are printed with -C and -D. If no inclusion list is provided, the default is to display all files. VIP list behavior, but make it tags. ✨
• -i — If specified, set the schg and/or sappnd flags. flags are being flagged. 🎀
• -j — Indent the output 4 spaces each time a directory level is descended when creating a specification with the -c option. This does not affect either the /set statements or the comment before each directory. It does however affect the comment before the close of each directory. This is the equivalent of the -i option in the FreeBSD version of mtree. nesting but make it readable. 🪆
• -K keywords — Add the specified (whitespace or comma separated) keywords to the current set of keywords. If all is specified, add all of the other keywords. keyword collection era. 💅
• -k keywords — Use the mandatory type keyword plus the specified (whitespace or comma separated) keywords to replace the current set of keywords. If all is specified, use all of the available keywords. not adding — replacing. main character energy. 👑
• -L — Follow all symbolic links in the file hierarchy. symlinks said “come with me,” and mtree said bet. 🔥
• -l — Do “loose” permissions checks, in which more stringent permissions will match less stringent ones. For example, a file marked mode 0444 will pass a check for mode 0644. “Loose” checks apply only to read, write and execute permissions — in particular, if other bits like the sticky bit or suid/sgid bits are set either in the specification or the file, exact checking will be performed. This option may not be set at the same time as the -U or -u option. permission checks but chill — except for the special bits, which stay strict. no cap. 💀
• -M — Permit merging of specification entries with different types, with the last entry taking precedence. last one wins, bestie. 🏁
• -m — If the schg and/or sappnd flags are specified, reset these flags. Note that this is only possible with securelevel less than 1 (i.e., in single user mode or while the system is running in insecure mode). See init(8) for information on security levels. > warning vibes: securelevel has entered the chat. 🚨
• -n — Do not emit pathname comments when creating a specification. Normally a comment is emitted before each directory and before the close of that directory when using the -c option. no pathname commentary. we're keeping it minimal. 🎀
• -N dbdir — Use the user database text file master.passwd and group database text file group from dbdir, rather than using the results from the system's getpwnam(3) and getgrnam(3) (and related) library calls. custom database directory? slay. 🗂️
• -O onlypaths — Only include files included in this list of pathnames. pathname filter, but make it exclusive. ✨
• -P — Don't follow symbolic links in the file hierarchy, instead consider the symbolic link itself in any comparisons. This is the default. symlink stays symlink. iconic behavior. 🦋
• -p path — Use the file hierarchy rooted in path, instead of the current directory. pick a directory, any directory. 💖
• -q — Quiet mode. Do not complain when a “missing” directory cannot be created because it already exists. This occurs when the directory is a symbolic link. shhh. no complaints. 🙈
• -R keywords — Remove the specified (whitespace or comma separated) keywords from the current set of keywords. The type keyword is mandatory and is always retained. If all is specified, remove all keywords except type. keyword cleanup era, but type is never getting voted off the island. 💅
• -r — Remove any files in the file hierarchy that are not described in the specification. Repeating the flag more than once will attempt to reset all the file flags via lchflags(2) before attempting to remove the file in case the file was immutable. > this one is literally deleting files, bestie — read it twice. 🫶
• -S — When reading a specification into an internal data structure, sort the entries. Sorting will affect the order of the output produced by the -C or -D options, and will also affect the order in which missing entries are created or reported when a directory tree is checked against a specification.

The sort order is the same as that used by the -c option, which is that entries within the same directory are sorted in the order used by strcmp(3), except that entries for subdirectories sort after other entries. By default, if the -S option is not used, entries within the same directory are collected together (separated from entries for other directories), but not sorted. sorting? sometimes. collected together? by default, yes. 🌈

• -s seed — Display a single checksum to the standard error output that represents all of the files for which the keyword cksum was specified. The checksum is seeded with the specified value. one checksum to rule them all, but seeded. 🧚
• -t — Modify the modified time of existing files, the device type of devices, and symbolic link targets, to match the specification. time, devices, and symlink targets are getting adjusted. ⏰
• -U — Same as -u except that a mismatch is not considered to be an error if it was corrected. corrected mismatch? not an error. we love growth. 🌱
• -u — Modify the owner, group, permissions, and flags of existing files, the device type of devices, and symbolic link targets, to match the specification. Create any missing directories, devices or symbolic links. User, group, and permissions must all be specified for missing directories to be created. Note that unless the -i option is given, the schg and sappnd flags will not be set, even if specified. If -m is given, these flags will be reset. Exit with a status of 0 on success, 2 if the file hierarchy did not match the specification, and 1 if any other error occurred. the “actually fix it” option, with receipts. 💅
• -W — Don't attempt to set various file attributes such as the ownership, mode, flags, or time when creating new directories or changing existing entries. This option will be most useful when used in conjunction with -U or -u. no attribute-setting, just vibes. 🎀
• -X exclude-file — The specified file contains fnmatch(3) patterns matching files to be excluded from the specification, one to a line. If the pattern contains a / character, it will be matched against entire pathnames (relative to the starting directory); otherwise, it will be matched against basenames only. Comments are permitted in the exclude-file file. exclusion patterns, but make them globby. 🦋
• -x — Don't descend below mount points in the file hierarchy. mount point said “boundary,” and mtree respected it. ✋

---

Specifications are mostly composed of “keywords”, i.e. strings that specify values relating to files. No keywords have default values, and if a keyword has no value set, no checks based on it are performed.

🧚 CURRENTLY SUPPORTED KEYWORDS 🧚

Currently supported keywords are as follows:

• cksum — The checksum of the file using the default algorithm specified by the cksum(1) utility. checksum behavior, but make it default-algorithm cute. 💖
• device — The device number to use for block or char file types. The argument must be one of the following forms:

okay bestie, we're mid-keyword-list and this is where it gets good — these are literally the building blocks of your whole spec file, so like, pay attention 💅

• format,major,minor — a device with major and minor fields, for an operating system specified with format. Valid formats are listed right below, keep reading ✨
• format,major,unit,subunit — a device with major, unit, and subunit fields, for an OS specified with format. (Currently this is only supported by the bsdos format, iykyk.)
• number — an opaque number (as stored on the file system).

So the recognized values for format are: native, 386bsd, 4bsd, bsdos, freebsd, hpux, isc, linux, netbsd, osf1, sco, solaris, sunos, svr3, svr4, and ultrix. Periodt.

See mknod(8) for more deets.

• flags — the file flags as a symbolic name. Peep chflags(1) for info on these names. If no flags are to be set, the string none may be used to override the current default. Heads up though: the schg and sappnd flags are treated specially (see the -i and -m options) 👀
• ignore — ignore any file hierarchy below this file. Just… don't look at it, bestie 🙈
• gid — the file group as a numeric value.
• gname — the file group as a symbolic name.
• link — the file the symbolic link is expected to reference.
• md5 — the MD5 cryptographic message digest of the file.
• md5digest — synonym for md5.
• mode — the current file's permissions as a numeric (octal) or symbolic value.
• nlink — the number of hard links the file is expected to have.
• nochange — make sure this file or directory exists but otherwise ignore all attributes. Like, be here, that's it, no notes 🫶
• optional — the file is optional; don't complain about the file if it's not in the file hierarchy. So chill.
• ripemd160digest — synonym for rmd160.
• rmd160 — the RMD-160 cryptographic message digest of the file.
• rmd160digest — synonym for rmd160.
• sha1 — the SHA-1 cryptographic message digest of the file.
• sha1digest — synonym for sha1.
• sha256 — the 256-bits SHA-2 cryptographic message digest of the file.
• sha256digest — synonym for sha256.
• sha384 — the 384-bits SHA-2 cryptographic message digest of the file.
• sha384digest — synonym for sha384.
• sha512 — the 512-bits SHA-2 cryptographic message digest of the file.
• sha512digest — synonym for sha512.
• size — the size, in bytes, of the file.
• tags — comma delimited tags to be matched with -E and -I. These may be specified without leading or trailing commas, but will be stored internally with them. Sneaky little commas, iconic 🎀
• time — the last modification time of the file, in second and nanoseconds. The value should include a period character and exactly nine digits after the period. Nine. Not eight. Not ten. Nine. Iykyk ✨
• type — the type of the file; may be set to any one of these:
  • block — block special device
  • char — character special device
  • dir — directory
  • fifo — fifo
  • file — regular file
  • link — symbolic link
  • socket — socket
• uid — the file owner as a numeric value.
• uname — the file owner as a symbolic name.

And the default set of keywords are flags, gid, link, mode, nlink, size, time, type, and uid. Those are the ones you get for free, no cap 💖

---

🌈 the four types of lines

There are four types of lines in a specification, bestie. Four. Let's go:

1. Set global values for a keyword. This consists of the string /set followed by whitespace, followed by sets of keyword/value pairs, separated by whitespace. Keyword/value pairs consist of a keyword, followed by an equals sign (=), followed by a value, without whitespace characters. Once a keyword has been set, its value remains unchanged until either reset or unset. Girl math but make it persistent 💅
2. Unset global values for a keyword. This consists of the string /unset, followed by whitespace, followed by one or more keywords, separated by whitespace. If all is specified, unset all of the keywords. Everything. Gone. 🫠
3. A file specification, consisting of a path name, followed by whitespace, followed by zero or more whitespace separated keyword/value pairs.

The path name may be preceded by whitespace characters. The path name may contain any of the standard path name matching characters ([, ], ? or *), in which case files in the hierarchy will be associated with the first pattern that they match. mtree uses strsvis(3) (in VIS_OCTAL format) to encode path names containing non-printable characters. Whitespace characters are encoded as \040 (space), \011 (tab), and \012 (new line). When flavor netbsd6 is selected, strsvis(3) (in VIS_CSTYLE format) is used and whitespace characters are encoded as \s (space), \t (tab), and \n (new line). # characters in path names are escaped by a preceding backslash \ to distinguish them from comments. Little escape gremlins, we love them 🌸

Each of the keyword/value pairs consist of a keyword, followed by an equals sign (=), followed by the keyword's value, without whitespace characters. These values override, without changing, the global value of the corresponding keyword. Override, not replace — big difference, bestie 📌

The first path name entry listed must be a directory named ., as this ensures that intermixing full and relative path names will work consistently and correctly. Multiple entries for a directory named . are permitted; the settings for the last such entry override those of the existing entry.

A path name that contains a slash (/) that is not the first character will be treated as a full path (relative to the root of the tree). All parent directories referenced in the path name must exist. The current directory path used by relative path names will be updated appropriately. Multiple entries for the same full path are permitted if the types are the same (unless -M is given, in which case the types may differ); in this case the settings for the last entry take precedence.

A path name that does not contain a slash will be treated as a relative path. Specifying a directory will cause subsequent files to be searched for in that directory hierarchy.

4. A line containing only the string .. which causes the current directory path (used by relative paths) to ascend one level. Up we go ⬆️

Empty lines and lines whose first non-whitespace character is a hash mark (#) are ignored. Comments, baby ✨

---

The mtree utility exits with a status of 0 on success, 1 if any error occurred, and 2 if the file hierarchy did not match the specification. Three whole moods, and 2 is the "we have a problem" one 😭

---

📁 FILES

• /etc/mtree — system specification directory. That's where the specs live, bestie 🏠

---

🌸 EXAMPLES

To detect system binaries that have been "trojan horsed", it is recommended that mtree be run on the file systems, and a copy of the results stored on a different machine, or, at least, in encrypted form. The seed for the -s option should not be an obvious value and the final checksum should not be stored on-line under any circumstances! Then, periodically, mtree should be run against the on-line specifications and the final checksum compared with the previous value. While it is possible for the bad guys to change the on-line specifications to conform to their modified binaries, it shouldn't be possible for them to make it produce the same final checksum value. If the final checksum value changes, the off-line copies of the specification can be used to detect which of the binaries have actually been modified. Threat model queen 👑

The -d option can be used in combination with -U or -u to create directory hierarchies for, for example, distributions. Very handy, very slay 💅

---

⚠️ COMPATIBILITY

The compatibility shims provided by the -F option are incomplete by design. Known limitations are described below, don't come for me about it 🙈

The freebsd9 flavor retains the default handling of lookup failures for the uname and group keywords by replacing them with appropriate uid and gid keywords rather than failing and reporting an error. The related -w flag is a no-op rather than causing a warning to be printed and no keyword to be emitted. The latter behavior is not emulated as it is potentially dangerous in the face of /set statements. Yeah. Dangerous. We said it 🫶

The netbsd6 flavor does not replicate the historical bug that reported time as seconds.nanoseconds without zero padding nanosecond values less than 100000000. We fixed the bug, we didn't re-bug it. Growth 💀

---

👀 SEE ALSO

chflags(1), chgrp(1), chmod(1), cksum(1), stat(2), fnmatch(3), fts(3), strsvis(3), mtree(5), chown(8), mknod(8). Read them all, they're all connected bestie, it's giving curriculum 🌈

---

🕰️ HISTORY

The mtree utility appeared in 4.3BSD-Reno. The optional keyword appeared in NetBSD 1.2. The -U option appeared in NetBSD 1.3. The flags and md5 keywords, and -i and -m options appeared in NetBSD 1.4. The device, rmd160, sha1, tags, and all keywords, -D, -E, -I, -L, -l, -N, -P, -R, -W, and -X options, and support for full paths appeared in NetBSD 1.6. The sha256, sha384, and sha512 keywords appeared in NetBSD 3.0. The -S option appeared in NetBSD 6.0. A whole glow-up timeline, honestly 👑

---

okay that's the whole page, bestie — go forth and verify your file hierarchies 🌟 this one's from the Debian crew, dated January 8, 2026, and you can find it filed under MTREE(8). mwah 💖✨