Linux command: tree

Run ls in a deep project and you get one flat layer at a time. You see the folders, then you step into one, then another, rebuilding the shape of the whole thing in your head. tree does that work for you. It walks the directory downward and draws the entire structure as a single indented diagram, with clean lines showing exactly what sits inside what. One command, and the layout of a whole project is on your screen.

2. Where the Name Comes From

The name is the picture. Draw a directory with its subdirectories branching out and its files hanging off the ends, and you have drawn a tree: a single root at the top, branches that split into more branches, and leaves at the tips. Computer scientists have called this exact structure a "tree" since the earliest days of the field, because it matches the botanical shape turned upside down.

A filesystem is a tree in this precise sense. There is one root, written /, every directory is a branch that can hold more branches, and every plain file is a leaf with nothing below it. The command does not invent the metaphor; it simply draws the tree that was always there. When you run tree, you are looking at the literal data structure your filesystem is built on.

So the name is as direct as a name can be. The tool shows you the tree, and it is called tree. There is no acronym and no hidden joke, just the plainest possible word for the thing on the screen.

4. Simple Use Cases

4.1 The Simplest Possible Use

Run tree with no arguments and it draws the current directory and everything below it:

$ tree
.
├── docs
│   └── guide.md
└── src
    └── main.py

2 directories, 2 files

The single dot . at the top is the starting directory, the same . that means "here" everywhere else in the shell. To draw a different folder, name it as an argument:

$ tree /etc/nginx
/etc/nginx
├── nginx.conf
└── conf.d
    └── default.conf

4.2 Limit How Deep It Goes

On a large project the full tree can scroll for pages. The -L flag (short for level) stops the descent after a set number of levels, which is the most useful flag tree has:

$ tree -L 1        # only the top level, like a quick ls
.
├── docs
├── README.md
├── src
└── tests

3 directories, 1 file

Reach for -L whenever you are exploring something unfamiliar. Start with -L 1 or -L 2 to see the overall shape, then descend into the one branch you care about.

4.3 Show Hidden Files

Like ls, tree hides files whose name begins with a dot by default. The -a flag (short for all) reveals them:

$ tree -a -L 1
.
├── .env
├── .gitignore
├── docs
├── README.md
└── src

This is how you see configuration files like .env and .gitignore, and also the .git folder, which is usually large and rarely something you want to expand. Section 5 shows how to hide it again while keeping the rest.

4.4 Directories Only

When you only care about the skeleton and not the individual files, the -d flag (short for directories) prints folders alone:

$ tree -d
.
├── docs
├── src
└── tests

3 directories

This gives you the map of a project without the clutter of every source file, which is exactly what you want when you are learning your way around a new codebase.

4.5 Turn Off the Summary Line

Every tree ends with the report line, such as 3 directories, 5 files. It is helpful on screen, but it gets in the way when you save a tree into a document or feed it to another tool. The --noreport flag removes it, leaving only the diagram:

$ tree -L 1 --noreport
.
├── docs
├── README.md
├── src
└── tests

Use it whenever the tree is going into a README, an email, or a script, where a trailing count line would only be noise.

6. Advanced Use Cases

6.1 Full Paths for Piping and Scripts

The drawing lines are lovely for human eyes but useless to another program. The -f flag (short for full path) prints the complete path of every entry, and -i (short for indentation off) removes the tree lines, leaving a plain list you can feed elsewhere:

$ tree -if
.
./docs
./docs/guide.md
./src
./src/main.py
./src/utils.py

Combined with -P this becomes a readable, structured alternative to a bare find for quick tasks. For real scripting, however, the structured outputs below are safer.

6.2 Machine-Readable Output: JSON and XML

When another program needs to consume the tree, ask for it in a real data format. The -J flag (short for JSON) prints the structure as JSON, and -X prints XML:

$ tree -J docs
[
  {"type":"directory","name":"docs","contents":[
    {"type":"file","name":"guide.md"}
  ]}
,
  {"type":"report","directories":1,"files":1}
]

The JSON output nests contents arrays exactly like the visual tree nests its branches, so a script can walk the structure directly. Pipe it into a tool like jq to filter or reshape it. This is the correct way to let a program read a directory layout; parsing the drawn lines with the box characters is fragile and best avoided.

6.3 Publish a Tree as a Web Page

The -H flag (short for HTML) writes a complete HTML page, with each entry turned into a clickable link relative to the base address you give it:

$ tree -H '.' -o index.html      # write a browsable listing to a file

The -o flag (short for output) sends the result to a file instead of the screen. Point a browser at that file and you get a navigable index of the directory, the same feature that once made tree a quick way to publish a download folder.

6.4 Extra Detail: Permissions, Owners, and Type Marks

tree can annotate each entry with the same metadata ls -l shows. The -p flag (short for permissions) prints the mode string, -u (short for user) prints the owner, -g (short for group) prints the group, and -F (short for file type, matching ls -F) appends a marker such as / for a directory or * for an executable:

$ tree -pF docs
docs
└── [-rw-rw-r--]  guide.md

With these flags tree becomes a recursive ls -l that keeps the shape, which is handy when you are auditing permissions across a whole subtree at once.

6.5 When the Lines Look Like Garbage

The connecting lines are drawn with special box characters. If your terminal, font, or file encoding cannot show them, you get broken symbols like M-bM-^T instead of clean corners. The --charset option tells tree which character set to draw with, and plain ascii falls back to ordinary keyboard characters that render everywhere:

$ tree --charset=ascii docs
docs
`-- guide.md

Here the corners become `-- and the branches become |--. It is less pretty but perfectly portable, which is exactly what you want when you paste a tree into an email, a ticket, or a document that must survive any encoding.

6.6 Following Symbolic Links

By default tree shows a symbolic link but does not step through it. It prints the link and where it points, with an arrow, and stops there:

$ tree
.
├── link_to_real -> real
└── real
    └── inside
        └── file.txt

The -l flag (short for follow links) tells tree to treat a linked directory like a real one and descend into it, so its contents appear under the link as well:

$ tree -l
.
├── link_to_real -> real
│   └── inside
│       └── file.txt
└── real
    └── inside
        └── file.txt

Following links is powerful but risky, because a link can point back up to a folder that contains it, creating an endless loop. tree guards against this: it tracks each directory it has already visited and, when a link would send it somewhere it has been, it marks the entry and refuses to recurse rather than spinning forever:

$ tree -l
.
└── loopback -> ..  [recursive, not followed]

The lesson is to use -l deliberately, only when you actually want linked directories expanded, and to trust the [recursive, not followed] note as a sign that the safety net did its job.

8. Best Practices

• Start shallow with -L. On any unfamiliar directory, run tree -L 2 first to see the shape, then descend into the one branch you care about.
• Hide the noise. Add -I 'node_modules|.git|__pycache__' so a real project's tree stays readable instead of drowning in dependencies.
• Use --gitignore in a repository. It shows the files that actually belong to the project without you having to list every junk folder by hand.
• Quote your patterns. Write tree -P '*.log', not tree -P *.log, or the shell expands the glob before tree sees it.
• Use --charset=ascii when you share. For an email, ticket, or README, plain ASCII lines survive any encoding; the fancy box characters may not.
• Reach for -J for scripts. Never parse the drawn lines in a program; ask for JSON and let a proper parser read it.
• Remember it may not be installed. tree is not part of coreutils, so a fresh server or container often needs apt install tree first.

When you need the full detail, the documentation is one command away:

$ man tree        # the full manual with every option
$ tree --help     # a quick summary of every flag

10. Summary

The tree command draws a directory and everything below it as a single indented diagram, turning the invisible shape of a project into a picture you can read at a glance.

• tree recurses into every subdirectory and connects items with lines: │ continues a branch, ├── marks an item with more siblings, and └── marks the last one.
• It is a separate package, not part of coreutils, so install it with apt, dnf, or pacman if it is missing.
• Control the view with -L (depth), -a (hidden files), -d (directories only), and --prune (drop empty branches).
• Filter with -P (keep matches), -I (hide matches), and --gitignore (respect the project's ignore rules).
• Add detail with -h and --du for sizes, -p -u -g for permissions and owners, and -F for type marks.
• For machines, use -J for JSON or -X for XML; for sharing, use --charset=ascii so the lines render anywhere.

This is the quick reference worth keeping:

tree                       draw the current directory and everything below
tree -L 2                  stop after two levels deep
tree -a                    include hidden dotfiles
tree -d                    directories only, no files
tree -P '*.py' --prune     keep only .py files, drop empty folders
tree -I 'node_modules|.git'  hide noisy folders
tree --gitignore           respect the project's .gitignore
tree -h --du               human-readable sizes with directory totals
tree -pug                  show permissions, owner, and group
tree -J                    output as JSON for scripts
tree --charset=ascii       portable lines for email and tickets
man tree                   the full manual

Once tree is in your toolkit, a strange directory stops being a maze you explore one cd at a time and becomes a map you can take in at a glance. If your servers have grown into a tangle that no one can quite picture anymore, drawing that out clearly, and keeping it tidy, is exactly the kind of work I help with.