Debian Codegraph @

upstream/fedora-44/man1/tree.1

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