Debian Codegraph @

upstream/debian-unstable/man1/tree.1

raw
1 .\" $Copyright: $
2 .\" Copyright (c) 1996 - 2026 by Steve Baker
3 .\" All Rights reserved
4 .\"
5 .\" This program is free software; you can redistribute it and/or modify
6 .\" it under the terms of the GNU General Public License as published by
7 .\" the Free Software Foundation; either version 2 of the License, or
8 .\" (at your option) any later version.
9 .\"
10 .\" This program is distributed in the hope that it will be useful,
11 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
12 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 .\" GNU General Public License for more details.
14 .\"
15 .\" You should have received a copy of the GNU General Public License
16 .\" along with this program; if not, write to the Free Software
17 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 .\"
19 .TH TREE 1 "" "Tree 2.3.2"
20 .SH NAME
21 tree \- list contents of directories in a tree-like format.
22 .SH SYNOPSIS
23 \fBtree\fP
24 [\fB-acdfghilnpqrstuvxACDFJQNSUX\fP]
25 [\fB-L\fP \fIlevel\fP [\fB-R\fP]]
26 [\fB-H\fP [-]\fIbaseHREF\fP]
27 [\fB-T\fP \fItitle\fP]
28 [\fB-o\fP \fIfilename\fP]
29 [\fB-P\fP \fIpattern\fP]
30 [\fB-I\fP \fIpattern\fP]
31 [\fB--gitignore\fP]
32 [\fB--gitfile\fP[\fB=\fP]\fIfile\fP]
33 [\fB--matchdirs\fP]
34 [\fB--metafirst\fP]
35 [\fB--ignore-case\fP]
36 [\fB--nolinks\fP]
37 [\fB--hintro\fP[\fB=\fP]\fIfile\fP]
38 [\fB--houtro\fP[\fB=\fP]\fIfile\fP]
39 [\fB--inodes\fP]
40 [\fB--device\fP]
41 [\fB--sort\fP[\fB=\fP]\fIname\fP]
42 [\fB--dirsfirst\fP]
43 [\fB--filesfirst\fP]
44 [\fB--filelimit\fP[\fB=\fP]\fI#\fP]
45 [\fB--si\fP]
46 [\fB--du\fP]
47 [\fB--prune\fP]
48 [\fB--charset\fP[\fB=\fP]\fIX\fP]
49 [\fB--timefmt\fP[\fB=\fP]\fIformat\fP]
50 [\fB--fromfile\fP]
51 [\fB--fromtabfile\fP]
52 [\fB--fflinks\fP]
53 [\fB--info\fP]
54 [\fB--infofile\fP[\fB=\fP]\fIfile\fP]
55 [\fB--noreport\fP]
56 [\fB--hyperlink\fP]
57 [\fB--scheme\fP[\fB=\fP]\fIschema\fP]
58 [\fB--authority\fP[\fB=\fP]\fIhostname\fP]
59 [\fB--opt-toggle\fP]
60 [\fB--acl\fP]
61 [\fB--selinux\fP]
62 [\fB--condense\fP]
63 [\fB--compress\fP[\fB=\fP]\fI#\fP]
64 [\fB--version\fP]
65 [\fB--help\fP]
66 [\fB--\fP] [\fIdirectory\fP ...]
67
68 .br
69 .SH DESCRIPTION
70 \fITree\fP is a recursive directory listing program that produces a depth
71 indented listing of files, which is colorized ala \fIdircolors\fP if the
72 \fBLS_COLORS\fP environment variable is set and output is to tty. With no
73 arguments, \fItree\fP lists the files in the current directory. When directory
74 arguments are given, \fItree\fP lists all the files and/or directories found in
75 the given directories each in turn. Upon completion of listing all
76 files/directories found, \fItree\fP returns the total number of files and/or
77 directories listed.
78
79 By default, when a symbolic link is encountered, the path that the symbolic
80 link refers to is printed after the name of the link in the format:
81 .br
82
83 name -> real-path
84 .br
85
86 If the `\fB-l\fP' option is given and the symbolic link refers to an actual
87 directory, then \fItree\fP will follow the path of the symbolic link as if
88 it were a real directory.
89 .br
90
91 .SH OPTIONS
92 \fITree\fP understands the following command line switches:
93
94 .SH LISTING OPTIONS
95
96 .TP
97 .B -a
98 All files are printed. By default tree does not print hidden files (those
99 beginning with a dot `.'). In no event does tree print the file system
100 constructs `.' (current directory) and `..' (previous directory).
101 .PP
102 .TP
103 .B -d
104 List directories only.
105 .PP
106 .TP
107 .B -l
108 Follows symbolic links if they point to directories, as if they were
109 directories. Symbolic links that will result in recursion are avoided when
110 detected.
111 .PP
112 .TP
113 .B -f
114 Prints the full path prefix for each file.
115 .PP
116 .TP
117 .B -x
118 Stay on the current file-system only. Ala \fBfind \fI-xdev\fP.
119 .PP
120 .TP
121 .B -L \fIlevel\fP
122 Max display depth of the directory tree.
123 .PP
124 .TP
125 .B -R
126 Recursively cross down the tree each \fIlevel\fP directories (see \fB-L\fP
127 option), and at each level outputting to a file named \fB00Tree.html\fP
128 (ala \fB-o\fP).
129 .PP
130 .TP
131 .B -P \fIpattern\fP
132 List only those files that match the wild-card \fIpattern\fP. You may have
133 multiple -P options. Note: you must use the \fI-a\fP option to also consider
134 those files beginning with a dot `.' for matching. Valid wildcard operators
135 are `*' (any zero or more characters), `**` (any zero or more characters as
136 well as null /'s, i.e. /**/ may match a single /), `?' (any single character),
137 `[...]' (any single character listed between brackets (optional - (dash) for
138 character range may be used: ex: [A-Z]), and `[^...]' (any single character
139 not listed in brackets) and `|' separates alternate patterns. A '/' at the
140 end of the pattern matches directories, but not files.
141 .PP
142 .TP
143 .B -I \fIpattern\fP
144 Do not list those files or directories that match the wild-card \fIpattern\fP.
145 You may have multiple -I options. See \fI-P\fP above for information on
146 wildcard patterns.
147 .PP
148 .TP
149 .B --gitignore
150 Uses git \fB.gitignore\fP files for filtering files and directories. Also
151 attempts to walk up the directory tree from the given path(s) searching for
152 \fB.gitignore\fP files as it goes, stopping at \fB/\fP or a directory containing
153 a \fB.git\fP directory. If a \fB.git\fP directory is found it will add the
154 \fB.git/info/exclude\fP file as well. Also uses \fB$GIT_DIR/info/exclude\fP if
155 present.
156 .PP
157 .TP
158 .B --gitfile\fR[\fB=\fR]\fIfile\fP
159 Use \fIfile\fP explicitly as a gitignore file.
160 .PP
161 .TP
162 .B --ignore-case
163 If a match pattern is specified by the \fB-P\fP or \fB-I\fP option, this will
164 cause the pattern to match without regard to the case of each letter.
165 .PP
166 .TP
167 .B --matchdirs
168 If a match pattern is specified by the \fB-P\fP option, this will cause the
169 pattern to be applied to directory names (in addition to filenames). In the
170 event of a match on the directory name, matching is disabled for the directory's
171 contents. If the \fB--prune\fP option is used, empty folders that match the
172 pattern will not be pruned.
173 .PP
174 .TP
175 .B --metafirst
176 Print the meta-data information at the beginning of the line rather than
177 after the indentation lines.
178 .PP
179 .TP
180 .B --prune
181 Makes tree prune empty directories from the output, useful when used in
182 conjunction with \fB-P\fP or \fB-I\fP. See \fBBUGS AND NOTES\fP below for
183 more information on this option.
184 .PP
185 .TP
186 .B --info
187 Prints file comments found in .info files. See \fB.INFO FILES\fP below
188 for more information on the format of .info files.
189 .PP
190 .TP
191 .B --infofile\fR[\fB=\fR]\fIfile\fP
192 Use \fIfile\fP explicitly as a info file.
193 .PP
194 .TP
195 .B --noreport
196 Omits printing of the file and directory report at the end of the tree
197 listing.
198 .PP
199 .TP
200 .B --charset\fR[\fB=\fR]\fIcharset\fP
201 Set the character set to use when outputting HTML and for line drawing.
202 .PP
203 .TP
204 .B --filelimit\fR[\fB=\fR]\fI#\fP
205 Do not descend directories that contain more than \fI#\fP entries.
206 .PP
207 .TP
208 .B --condense
209 Condenses the output of directory 'singletons' -- directories that themselves
210 only contain a single directory, onto a single line and does so recursively.
211 Note that any meta-information printed will be for the first directory shown.
212 .TP
213 .B -o \fIfilename\fP
214 Send output to \fIfilename\fP.
215 .PP
216
217 .SH FILE OPTIONS
218
219 .TP
220 .B -q
221 Print non-printable characters in filenames as question marks instead of the
222 default.
223 .PP
224 .TP
225 .B -N
226 Print non-printable characters as is instead of as escaped octal numbers.
227 .PP
228 .TP
229 .B -Q
230 Quote the names of files in double quotes.
231 .PP
232 .TP
233 .B -p
234 Print the file type and permissions for each file (as per ls -l).
235 .PP
236 .TP
237 .B -u
238 Print the username, or UID # if no username is available, of the file.
239 .PP
240 .TP
241 .B -g
242 Print the group name, or GID # if no group name is available, of the file.
243 .PP
244 .TP
245 .B -s
246 Print the size of each file in bytes along with the name.
247 .PP
248 .TP
249 .B -h
250 Print the size of each file but in a more human readable way, e.g. appending a
251 size letter for kilobytes (K), megabytes (M), gigabytes (G), terabytes (T),
252 petabytes (P) and exabytes (E).
253 .PP
254 .TP
255 .B --si
256 Like \fB-h\fP but use SI units (powers of 1000) instead.
257 .PP
258 .TP
259 .B --du
260 For each directory report its size as the accumulation of sizes of all its files
261 and sub-directories (and their files, and so on). The total amount of used
262 space is also given in the final report (like the 'du -c' command.) This option
263 requires tree to read the entire directory tree before emitting it, see
264 \fBBUGS AND NOTES\fP below. Implies \fB-s\fP.
265 .PP
266 .TP
267 .B -D
268 Print the date of the last modification time or if \fB-c\fP is used, the last
269 status change time for the file listed.
270 .PP
271 .TP
272 .B --timefmt\fR[\fB=\fR]\fIformat\fP
273 Prints (implies -D) and formats the date according to the format string
274 which uses the \fBstrftime\fP(3) syntax.
275 .PP
276 .TP
277 .B -F
278 Append a `/' for directories, a `=' for socket files, a `*' for executable
279 files, a `>' for doors (Solaris) and a `|' for FIFO's, as per ls -F
280 .PP
281 .TP
282 .B --inodes
283 Prints the inode number of the file or directory
284 .PP
285 .TP
286 .B --device
287 Prints the device number to which the file or directory belongs
288 .PP
289 .TP
290 .B --acl (Linux only)
291 Prints the permissions, and if an ACL is present on the file appends + to the
292 list of permissions. Implies the \fB-p\fP option.
293 .PP
294 .TP
295 .B --selinux (Linux only)
296 Prints the SELinux label for a file if one is present for it.
297 .PP
298
299 .SH SORTING OPTIONS
300
301 .TP
302 .B -v
303 Sort the output by version.
304 .PP
305 .TP
306 .B -t
307 Sort the output by last modification time instead of alphabetically.
308 .PP
309 .TP
310 .B -c
311 Sort the output by last status change instead of alphabetically. Modifies the
312 \fB-D\fP option (if used) to print the last status change instead of
313 modification time.
314 .PP
315 .TP
316 .B -U
317 Do not sort. Lists files in directory order. Disables \fB--dirsfirst\fP.
318 .PP
319 .TP
320 .B -r
321 Sort the output in reverse order. This is a meta-sort that alters the above sorts.
322 This option is disabled when \fB-U\fP is used.
323 .PP
324 .TP
325 .B --dirsfirst
326 List directories before files. This is a meta-sort that alters the above sorts.
327 This option is disabled when \fB-U\fP is used.
328 .PP
329 .TP
330 .B --filesfirst
331 List files before directories. This is a meta-sort that alters the above sorts.
332 This option is disabled when \fB-U\fP is used.
333 .PP
334 .TP
335 .B --sort\fR[\fB=\fR]\fItype\fR
336 Sort the output by \fItype\fR instead of name. Possible values are:
337 \fBctime\fR (\fB-c\fP),
338 \fBmtime\fR (\fB-t\fB), \fBsize\fR, \fBversion\fR (\fB-v\fR) or \fBnone\fR
339 (\fB-U\fR).
340
341 .SH GRAPHICS OPTIONS
342
343 .TP
344 .B -i
345 Makes tree not print the indentation lines, useful when used in conjunction
346 with the \fB-f\fP option. Also removes as much whitespace as possible when used
347 with the \fB-J\fP or \fB-X\fP options.
348 .PP
349 .TP
350 .B -A
351 Turn on ANSI line graphics hack when printing the indentation lines. This option
352 is now equivalent to `\fB--charset=ANSI\fP`.
353 .PP
354 .TP
355 .B -S
356 Turn on CP437 line graphics (useful when using Linux console mode fonts). This
357 option is now equivalent to `\fB--charset=IBM437\fP' and may eventually be depreciated.
358 .PP
359 .TP
360 .B -n
361 Turn colorization off always, over-ridden by the \fB-C\fP option, however
362 overrides CLICOLOR_FORCE if present.
363 .PP
364 .TP
365 .B -C
366 Turn colorization on always, using built-in color defaults if the LS_COLORS or
367 TREE_COLORS environment variables are not set. Useful to colorize output to a
368 pipe.
369 .PP
370 .TP
371 .B --compress\fR[\fB=\fR]\fI#\fR
372 Compresses the indentation lines. The argument may be a positive number from 1
373 (normal) to 3 (a single character) or -1 to -3 which removes the additional
374 space at each indentation level. Greater compression levels turn off indentation
375 lines (i.e. \fB-i\fR).
376 .PP
377
378 .SH XML/JSON/HTML/HYPERLINKS OPTIONS
379
380 .TP
381 .B -X
382 Turn on XML output. Outputs the directory tree as an XML formatted file.
383 .PP
384 .TP
385 .B -J
386 Turn on JSON output. Outputs the directory tree as a JSON formatted array.
387 .PP
388 .TP
389 .B -H [-]\fIbaseHREF\fP
390 Turn on HTML output, including HTTP references. Useful for ftp sites.
391 \fIbaseHREF\fP gives the base ftp location when using HTML output. That is, the
392 local directory may be `/local/ftp/pub', but it must be referenced as
393 `ftp://hostname.organization.domain/pub' (\fIbaseHREF\fP should be
394 `ftp://hostname.organization.domain'). If \fIbaseHREF\fP begins with a dash
395 (\fB-\fP), then the dash is removed and indicates that tree should remove the
396 first directory name from the href URL. Hint: don't use ANSI lines with this
397 option, and don't give more than one directory in the directory list. If you
398 wish to use colors via CSS style-sheet, use the -C option in addition to this
399 option to force color output.
400 .PP
401 .TP
402 .B --hintro\fR[\fB=\fR]\fIfile\fP
403 Use \fIfile\fP as the HTML intro in place of the default one. Use an empty
404 file or \fI/dev/null\fP to eliminate the intro altogether.
405 .PP
406 .TP
407 .B --houtro\fR[\fB=\fR]\fIfile\fP
408 Use \fIfile\fP as the HTML outro in place of the default one. Use an empty
409 file or \fI/dev/null\fP to eliminate the outro altogether.
410 .PP
411 .TP
412 .B -T \fItitle\fP
413 Sets the title and H1 header string in HTML output mode.
414 .PP
415 .TP
416 .B --nolinks
417 Turns off hyperlinks in HTML output.
418 .PP
419 .TP
420 .B --hyperlink
421 Enable OSC 8 terminal hyperlinks for terminals that support them. See \fBBUGS
422 AND NOTES\fR below.
423 .PP
424 .TP
425 .B --scheme\fR[\fB=\fR]\fIschema\fP
426 Sets the schema used in the OSC 8 hyperlinks. The default schema is '\fBfile://\fR'.
427 If the schema omits the colon (:), then \fB://\fR will be appended to the schema.
428 .TP
429 .B --authority\fR[\fB=\fR]\fIhostname|authority\fP
430 Sets the authority (hostname) to use for the OSC 8 hyperlinks. By default the
431 local hostname of the machine as returned by gethostname() is used as the
432 authority. A dot (\fB.\fP) or a set of ""'s, sans '=', (i.e. the empty string)
433 can be used to indicate a null authority.
434 .PP
435
436 .SH INPUT OPTIONS
437
438 .TP
439 .B --fromfile
440 Reads a directory listing from a file rather than the file-system. Paths
441 provided on the command line are files to read from rather than directories to
442 search. The dot (.) directory indicates that tree should read paths from
443 standard input. NOTE: this is only suitable for reading the output of a program
444 such as find, not 'tree -fi' as symlinks are not distinguished from files that
445 simply contain ' -> ' as part of the filename unless the \fB--fflinks\fP option
446 is used.
447 .PP
448 .TP
449 .B --fromtabfile
450 Like \fB--fromfile\fP, tree reads a directory tree from a text file where the
451 files are tab indented in a tree like format to indicate the directory nesting
452 level.
453 .PP
454 .TP
455 .B --fflinks
456 Processes symbolic link information found in a file, as from the output of
457 \fB'tree -fi --noreport'\fP. Only the first occurrence of the string \fB' -> '\fP
458 is used to denote the separation of the filename from the link.
459 .PP
460
461 .SH MISC OPTIONS
462
463 .TP
464 .B --opt-toggle
465 Enables option "toggling". Turns on the ability to toggle options such as -a,
466 -h, etc. Useful to add to an alias when you wish to disable options enabled in
467 the alias.
468 .PP
469 .TP
470 .B --help
471 Outputs a verbose usage listing.
472 .PP
473 .TP
474 .B --version
475 Outputs the version of tree.
476 .PP
477 .TP
478 .B --
479 Option processing terminator. No further options will be processed after this.
480 .PP
481
482 .SH .INFO FILES
483
484 \fB.info\fP files are similar to \.gitignore files, if a .info file is found
485 while scanning a directory it is read and added to a stack of .info
486 information. Each file is composed of comments (lines starting with hash marks
487 (#),) or wild-card patterns which may match a file relative to the directory
488 the \.info file is found in. If a file should match a pattern, the tab indented
489 comment that follows the pattern is used as the file comment. A comment is
490 terminated by a non-tab indented line. Multiple patterns, each to a line, may
491 share the same comment.
492
493 .br
494 .SH FILES
495 \fB/etc/DIR_COLORS\fP System color database.
496 .br
497 \fB~/.dircolors\fP Users color database.
498 .br
499 \fB.gitignore\fP Git exclusion file
500 .br
501 \fB$GIT_DIR/info/exclude\fP Global git file exclusion list
502 .br
503 \fB.info\fP File comment file
504 .br
505 \fB/usr/share/finfo/global_info\fP Global file comment file
506
507
508 .SH ENVIRONMENT
509 \fBLS_COLORS\fP Color information created by dircolors
510 .br
511 \fBTREE_COLORS\fP Uses this for color information over LS_COLORS if it is set.
512 .br
513 \fBTREE_CHARSET\fP Character set for tree to use in HTML mode.
514 .br
515 \fBCLICOLOR\fP Enables colorization even if TREE_COLORS or LS_COLORS is not set.
516 .br
517 \fBCLICOLOR_FORCE\fP Always enables colorization (effectively -C)
518 .br
519 \fBNO_COLOR\fP Disable colorization (effectively -n) (see \fBhttps://no-color.org/\fP)
520 .br
521 \fBLC_CTYPE\fP Locale for filename output.
522 .br
523 \fBLC_TIME\fP Locale for timefmt output, see \fBstrftime\fP(3).
524 .br
525 \fBTZ\fP Timezone for timefmt output, see \fBstrftime\fP(3).
526 .br
527 \fBSTDDATA_FD\fP Enable the stddata feature, optionally set descriptor to use.
528
529 .SH AUTHOR
530 Steve Baker ([email protected])
531 .br
532 HTML output hacked by Francesc Rocher ([email protected])
533 .br
534 Charsets and OS/2 support by Kyosuke Tokoro ([email protected])
535
536 .SH BUGS AND NOTES
537 Tree does not prune "empty" directories when the -P and -I options are used by
538 default. Use the --prune option.
539
540 The -h and --si options round to the nearest whole number unlike the ls
541 implementations which rounds up always.
542
543 Pruning files and directories with the -I, -P and --filelimit options will
544 lead to incorrect file/directory count reports.
545
546 The --prune and --du options cause tree to accumulate the entire tree in memory
547 before emitting it. For large directory trees this can cause a significant delay
548 in output and the use of large amounts of memory.
549
550 The timefmt expansion buffer is limited to a ridiculously large 255 characters.
551 Output of time strings longer than this will be undefined, but are guaranteed
552 to not exceed 255 characters.
553
554 XML/JSON trees are not colored, which is a bit of a shame. The jq utility
555 can colorize the JSON however, just not the filenames by file-type ala LS_COLORS.
556
557 OSC 8 hyperlinks may be poorly supported by your terminal. For my version of
558 Konsole it is necessary to set the schema to file: (no //) and use a null
559 authority. It may also be necessary to spend 3.5 hours finding the option to
560 turn on hyperlinks.
561
562 Probably more.
563
564 As of version 2.0.0, in Linux, tree will attempt to automatically output a
565 compact JSON tree on file descriptor 3 (what I call stddata,) if present and the
566 environment variable STDDATA_FD is defined or set to a positive non-zero file
567 descriptor value to use to output on. It is hoped that some day a better
568 Linux/Unix shell may take advantage of this feature, though BSON would probably
569 be a better format for this.
570
571 .SH SEE ALSO
572 .BR dircolors (1),
573 .BR ls (1),
574 .BR find (1),
575 .BR du (1),
576 .BR jq (1),
577 .BR strftime (3),
578 .BR gitignore (5)