Debian Codegraph @

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