Debian Codegraph @

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