TREE(1)

📦
version 2.3.2 · 11 versions
, in alpine 3.24, arch rolling, nixpkgs unstable

🌳 TREE(1) — General Commands Manual 🌳

okay bestie, this is part 1 of 2, and we're covering tree(1) from the General Commands Manual — the recursive directory-listing icon itself. It's giving filesystem realness, and we're gonna get you all the way together 💅✨

🌸 NAME 🌸

tree — list contents of directories in a tree-like format. That's the whole gig, and it's iconic 🫶

✨ SYNOPSIS ✨

tree [-acdfghilnpqrstuvxACDFJQNSUX] [-L level [-R]] [-H [-]baseHREF] [-T
title] [-o filename] [-P pattern] [-I pattern] [--gitignore]
[--gitfile[=]file] [--matchdirs] [--metafirst] [--ignore-case]
[--nolinks] [--hintro[=]file] [--houtro[=]file] [--inodes] [--device]
[--sort[=]name] [--dirsfirst] [--filesfirst] [--filelimit[=]#] [--si]
[--du] [--prune] [--charset[=]X] [--timefmt[=]format] [--fromfile]
[--fromtabfile] [--fflinks] [--info] [--infofile[=]file] [--noreport]
[--hyperlink] [--scheme[=]schema] [--authority[=]hostname] [--opt-
toggle] [--acl] [--selinux] [--condense] [--compress[=]#] [--version]
[--help] [--] [directory ...]

💖 DESCRIPTION 💖

So tree is a recursive directory listing program, and what it does is produce a depth-indented listing of files. It gets colorized ala dircolors if the LS_COLORS environment variable is set and output is to a tty. Lowkey obsessed with that detail 🌈

With no arguments, tree lists the files in the current directory. When directory arguments are given, tree lists all the files and/or directories found in the given directories, each in turn. Upon completion of listing all files/directories found, tree returns the total number of files and/or directories listed. Periodt.

By default, when a symbolic link is encountered, the path that the symbolic link refers to is printed after the name of the link in the format:

name -> real-path

If the -l option is given and the symbolic link refers to an actual directory, then tree will follow the path of the symbolic link as if it were a real directory. Bestie, that's the follow-the-link behavior, no cap 🦋

🎀 OPTIONS 🎀

Tree understands the following command line switches:

🦋 LISTING OPTIONS 🦋

  • -a — All files are printed. By default tree does not print hidden files (those beginning with a dot .). In no event does tree print the file system constructs . (current directory) and .. (previous directory). Not today, dot-dot 💀
  • -d — List directories only.
  • -l — Follows symbolic links if they point to directories, as if they were directories. Symbolic links that will result in recursion are avoided when detected. Safety first, bestie 🫶
  • -f — Prints the full path prefix for each file.
  • -x — Stay on the current file-system only. Ala find -xdev.
  • -L level — Max display depth of the directory tree.
  • -R — Recursively cross down the tree each level directories (see -L option), and at each level outputting to a file named 00Tree.html (ala -o).
  • -P pattern — List only those files that match the wild-card pattern. You may have multiple -P options. Note: you must use the -a option to also consider those files beginning with a dot . for matching. Valid wildcard operators are:
    • * — any zero or more characters
    • ** — any zero or more characters as well as null /'s, i.e. /**/ may match a single /
    • ? — any single character
    • [...] — any single character listed between brackets (optional - (dash) for character range may be used: ex: [A-Z])
    • [^...] — any single character not listed in brackets
    • | — separates alternate patterns

A / at the end of the pattern matches directories, but not files. Slash at the end means directory energy 💅

  • -I pattern — Do not list those files or directories that match the wild-card pattern. You may have multiple -I options. See -P above for information on wildcard patterns.
  • --gitignore — Uses git .gitignore files for filtering files and directories. Also attempts to walk up the directory tree from the given path(s) searching for .gitignore files as it goes, stopping at / or a directory containing a .git directory. If a .git directory is found it will add the .git/info/exclude file as well. Also uses $GIT_DIR/info/exclude if present. Git girlies rise 🧚
  • --gitfile[=] file — Use file explicitly as a gitignore file.
  • --ignore-case — If a match pattern is specified by the -P or -I option, this will cause the pattern to match without regard to the case of each letter.
  • --matchdirs — If a match pattern is specified by the -P option, this will cause the pattern to be applied to directory names (in addition to filenames). In the event of a match on the directory name, matching is disabled for the directory's contents. If the --prune option is used, empty folders that match the pattern will not be pruned. Directory-name matching said not today to its contents 😭
  • --metafirst — Print the meta-data information at the beginning of the line rather than after the indentation lines.
  • --prune — Makes tree prune empty directories from the output, useful when used in conjunction with -P or -I. See BUGS AND NOTES below for more information on this option.
  • --info — Prints file comments found in .info files. See .INFO FILES below for more information on the format of .info files.
  • --infofile[=] file — Use file explicitly as a info file.
  • --noreport — Omits printing of the file and directory report at the end of the tree listing.
  • --charset[=] charset — Set the character set to use when outputting HTML and for line drawing.
  • --filelimit[=] # — Do not descend directories that contain more than # entries.
  • --condense — Condenses the output of directory 'singletons' — directories that themselves only contain a single directory — onto a single line and does so recursively. Note that any meta-information printed will be for the first directory shown. Singleton directories got condensed, and honestly? Slay.
  • -o filename — Send output to filename.

💅 FILE OPTIONS 💅

  • -q — Print non-printable characters in filenames as question marks instead of the default.
  • -N — Print non-printable characters as is instead of as escaped octal numbers.
  • -Q — Quote the names of files in double quotes.
  • -p — Print the file type and permissions for each file (as per ls -l).
  • -u — Print the username, or UID # if no username is available, of the file.
  • -g — Print the group name, or GID # if no group name is available, of the file.
  • -s — Print the size of each file in bytes along with the name.
  • -h — Print the size of each file but in a more human readable way, e.g. appending a size letter for kilobytes (K), megabytes (M), gigabytes (G), terabytes (T), petabytes (P) and exabytes (E). Human-readable sizes are highkey the move 💖
  • --si — Like -h but use SI units (powers of 1000) instead.
  • --du — For each directory report its size as the accumulation of sizes of all its files and sub-directories (and their files, and so on). The total amount of used space is also given in the final report (like the du -c command.) This option requires tree to read the entire directory tree before emitting it, see BUGS AND NOTES below. Implies -s. Big du energy, but make it tree-shaped 🔥
  • -D — Print the date of the last modification time or if -c is used, the last status change time for the file listed.
  • --timefmt[=] format — Prints (implies -D) and formats the date according to the format string which uses strftime(3) syntax.
  • -F — Append a / for directories, a = for socket files, a * for executable files, a > for doors (Solaris) and a | for FIFO's, as per ls -F.
  • --inodes — Prints the inode number of the file or directory.
  • --device — Prints the device number to which the file or directory belongs.
  • --acl (Linux only) — Prints the permissions, and if an ACL is present on the file appends + to the list of permissions. Implies the -p option.
  • --selinux (Linux only) — Prints the SELinux label for a file if one is present for it.

🌈 SORTING OPTIONS 🌈

  • -v — Sort the output by version.
  • -t — Sort the output by last modification time instead of alphabetically.
  • -c — Sort the output by last status change instead of alphabetically. Modifies the -D option (if used) to print the last status change instead of modification time.
  • -U — Do not sort. Lists files in directory order. Disables --dirsfirst.
  • -r — Sort the output in reverse order. This is a meta-sort that alters the above sorts. This option is disabled when -U is used.
  • --dirsfirst — List directories before files. This is a meta-sort that alters the above sorts. This option is disabled when -U is used.
  • --filesfirst — List files before directories. This is a meta-sort that alters the above sorts. This option is disabled when -U is used.
  • --sort[=] type — Sort the output by type instead of name. Possible values are: ctime (-c), mtime (-t), size, version (-v) or none (-U).

🎨 GRAPHICS OPTIONS 🎨

  • -i — Makes tree not print the indentation lines, useful when used in conjunction with the -f option. Also removes as much whitespace as possible when used with the -J or -X options.
  • -A — Turn on ANSI line graphics hack when printing the indentation lines. This option is now equivalent to --charset=ANSI.
  • -S — Turn on CP437 line graphics (useful when using Linux console mode fonts). This option is now equivalent to --charset=IBM437 and may eventually be depreciated.
  • -n — Turn colorization off always, over-ridden by the -C option, however overrides CLICOLOR_FORCE if present.
  • -C — Turn colorization on always, using built-in color defaults if the LS_COLORS or TREE_COLORS environment variables are not set. Useful to colorize output to a pipe. Color to a pipe? Iconic behavior, honestly 🌈
  • --compress[=] # — Compresses the indentation lines. The argument may be a positive number from 1 (normal) to 3 (a single character) or -1 to -3 which removes the additional space at each indentation level. Greater compression levels turn off indentation lines (i.e. -i).
  • -X — turns on XML output, bestie. Your directory tree becomes an XML formatted file. so structured. much wow. 🦋
  • -J — turns on JSON output. Your directory tree becomes a JSON formatted array. for the jq girlies 💅
  • -H [-]baseHREF — turns on HTML output, including HTTP references. genuinely so useful for ftp sites. baseHREF gives the base ftp location when you're using HTML output — like, your local directory might be /local/ftp/pub, but it has to be referenced as ftp://hostname.organization.domain/pub. so baseHREF should be ftp://hostname.organization.domain. if baseHREF begins with a dash (-), then the dash is removed and it indicates that tree should remove the first directory name from the href URL. ✨
Hint (from the manpage, not me): don't use ANSI lines with this option, and don't give more than one directory in the directory list. If you wish to use colors via CSS style-sheet, use the -C option in addition to this option to force color output. 🎀
  • --hintro[=]file — uses file as the HTML intro in place of the default one. Use an empty file or /dev/null to eliminate the intro altogether. bye intro 👋
  • --houtro[=]file — uses file as the HTML outro in place of the default one. Use an empty file or /dev/null to eliminate the outro altogether. bye outro 👋
  • -T title — sets the title and the H1 header string in HTML output mode. main character energy for your tree fr fr 👑
  • --nolinks — turns off hyperlinks in HTML output. no links, no problem 🫶
  • --hyperlink — enables OSC 8 terminal hyperlinks for terminals that support them. see BUGS AND NOTES below 👀
  • --scheme[=]schema — sets the schema used in the OSC 8 hyperlinks. the default schema is 'file://'. if the schema omits the colon (:), then :// will be appended to the schema. thoughtful of it 💜
  • --authority[=]hostname|authority — sets the authority (hostname) to use for the OSC 8 hyperlinks. by default, the local hostname of the machine as returned by gethostname() is used as the authority. a dot (.) or a set of ""'s, sans =, (i.e. the empty string) can be used to indicate a null authority. poetic honestly 🌸

🌈 INPUT OPTIONS 🌈

  • --fromfile — reads a directory listing from a file rather than the file-system. paths provided on the command line are files to read from rather than directories to search. the dot (.) directory indicates that tree should read paths from standard input. 😭
NOTE: this is only suitable for reading the output of a program such as find, not tree -fi, as symlinks are not distinguished from files that simply contain ' -> ' as part of the filename — unless the --fflinks option is used. okay that's actually important, don't skip it 💀
  • --fromtabfile — like --fromfile, tree reads a directory tree from a text file where the files are tab indented in a tree like format to indicate the directory nesting level. tab indentation is the whole vibe here 🎀
  • --fflinks — processes symbolic link information found in a file, as from the output of 'tree -fi --noreport'. only the first occurrence of the string ' -> ' is used to denote the separation of the filename from the link. first one only, periodt ✨

🧚 MISC OPTIONS 🧚

  • --opt-toggle — enables option "toggling". turns on the ability to toggle options such as -a, -h, etc. useful to add to an alias when you wish to disable options enabled in the alias. iconic little uno-reverse feature tbh 🔥
  • --help — outputs a verbose usage listing. help bestie 🫶
  • --version — outputs the version of tree. 💜
  • -- — option processing terminator. no further options will be processed after this. that's it, that's the line, we're done here 🚪

💖 .INFO FILES 💖

.info files are similar to .gitignore files, if a .info file is found while scanning a directory it is read and added to a stack of .info information. noted. stacked. archived. 📚

Each file is composed of comments (lines starting with hash marks (#),) or wild-card patterns which may match a file relative to the directory the .info file is found in.

If a file should match a pattern, the tab indented comment that follows the pattern is used as the file comment. a comment is terminated by a non-tab indented line. multiple patterns, each to a line, may share the same comment. so efficient of them ✨

🌸 FILES 🌸

  • /etc/DIR_COLORS — System color database.
  • ~/.dircolors — Users color database.
  • .gitignore — Git exclusion file
  • $GIT_DIR/info/exclude — Global git file exclusion list
  • .info — File comment file
  • /usr/share/finfo/global_info — Global file comment file

🦋 ENVIRONMENT 🦋

  • LS_COLORS — Color information created by dircolors
  • TREE_COLORS — Uses this for color information over LS_COLORS if it is set.
  • TREE_CHARSET — Character set for tree to use in HTML mode.
  • CLICOLOR — Enables colorization even if TREE_COLORS or LS_COLORS is not set.
  • CLICOLOR_FORCE — Always enables colorization (effectively -C)
  • NO_COLOR — Disable colorization (effectively -n) (see https://no-color.org/)
  • LC_CTYPE — Locale for filename output.
  • LC_TIME — Locale for timefmt output, see strftime(3).
  • TZ — Timezone for timefmt output, see strftime(3).
  • STDDATA_FD — Enable the stddata feature, optionally set descriptor to use.

👑 AUTHOR 👑

  • Steve Baker (Steve.Baker.llc@gmail.com)
  • HTML output hacked by Francesc Rocher (rocher@econ.udg.es)
  • Charsets and OS/2 support by Kyosuke Tokoro (NBG01720@nifty.ne.jp)

legends, all of them 🫶

💀 BUGS AND NOTES 💀

okay bestie, this is the section where we get real. no cap, read it.

  • Tree does not prune "empty" directories when the -P and -I options are used by default. use the --prune option. 👈
  • The -h and --si options round to the nearest whole number unlike the ls implementations which rounds up always. different math, same vibe 😭
  • Pruning files and directories with the -I, -P and --filelimit options will lead to incorrect file/directory count reports. the numbers will lie to you, and that's just how it is 💀
  • The --prune and --du options cause tree to accumulate the entire tree in memory before emitting it. for large directory trees this can cause a significant delay in output and the use of large amounts of memory. so like, be careful with your giant monorepo, she's hungry 🍓
  • The timefmt expansion buffer is limited to a ridiculously large 255 characters. output of time strings longer than this will be undefined, but are guaranteed to not exceed 255 characters. undefined behaviour, my beloved 🙈
  • XML/JSON trees are not colored, which is a bit of a shame. the jq utility can colorize the JSON however, just not the filenames by file-type ala LS_COLORS. we mourn 🌧️
  • OSC 8 hyperlinks may be poorly supported by your terminal. for my version of Konsole it is necessary to set the schema to file: (no //) and use a null authority. it may also be necessary to spend 3.5 hours finding the option to turn on hyperlinks. 3.5 hours. real. 🔥
  • Probably more. 💅

And also, as of version 2.0.0, in Linux, tree will attempt to automatically output a compact JSON tree on file descriptor 3 (what I call stddata,) if present and the environment variable STDDATA_FD is defined or set to a positive non-zero file descriptor value to use to output on. it is hoped that some day a better Linux/Unix shell may take advantage of this feature, though BSON would probably be a better format for this. manifesting that for them ✨

⭐ SEE ALSO ⭐

dircolors(1), ls(1), find(1), du(1), jq(1), strftime(3), gitignore(5)

go read those too, i believe in you 🧚

okay that's the whole page, bestie 💖 you made it to the end, and honestly? slay. this was Tree 2.3.2 — the TREE(1) manual page, officially complete. now go run tree on something and feel something. bye bye 💅✨🎀
📦 where this page comes from