ls-tree
A lightweight clone of the Unix tree command, written in Rust. Point it at a
directory and it recursively prints the folders and files as a visual hierarchy
with optional JSON output, file sizes, colouring, sorting, and more.
$ ls-tree ./src
src
├── lib.rs
└── main.rs
2 directories, 2 files
Features
- Classic
treeoutput using├──,└──, and│connectors. - JSON output (
--json) — machine-readable for AI shells and OS tools. - File sizes (
-s/--size) with human-readable (-h) formatting. - Colour support — directories, executables, and symlinks are ANSI-coloured
automatically (respects
NO_COLOR, auto-detects terminal). .gitignoreawareness (--git-ignore) — filters entries matching root-level.gitignorerules.- Sorting (
--sort=name/size/time) — order entries within each directory. - Prune (
--prune) — omit empty directories from the output. - Directories only (
--dirs-only) — hide regular files. - File-type icons (
--icons) — Unicode icons for directories, symlinks, and file types. - Total size (
--total-size) — show recursive directory sizes. - Robust error handling — unreadable directories print
[Access Denied]and the traversal continues instead of crashing. - Symlink-safe — symlinks are shown (with their target) but never descended into, so symlink cycles cannot hang the program.
- Hidden-file aware — dotfiles are hidden by default (like
tree), with a flag to reveal them. --max-depthto limit how far down the tree is printed.
Installation
From source (recommended)
From crates.io
Build locally
Usage
If PATH is omitted, ls-tree prints the current directory (.).
Options
| Flag | Description |
|---|---|
-a, --all |
Show hidden entries (names starting with .). |
-L, --max-depth N |
Descend at most N directory levels. |
--dirs-only |
Display directories only. |
-s, --size |
Show file sizes. |
-h, --human-readable |
Print sizes in human-readable format (implies --size). |
--json |
Output JSON instead of the classic tree. |
--git-ignore |
Respect .gitignore rules. |
--sort=<field> |
Sort entries by name (default), size, or time. |
--prune |
Omit empty directories from the output. |
--icons |
Show Unicode file-type icons. |
--total-size |
Show recursive directory sizes (implies --size). |
--color |
Force colour output (auto-detected by default). |
--no-color |
Disable colour output. |
--help |
Print the help message and exit. |
-V, --version |
Print version information and exit. |
Examples
# Current directory
# Specific path
# Include hidden files, two levels deep
# JSON output with sizes
# Git-ignore aware, sorted by size
# Human-readable sizes with prune and icons
Exit codes
| Code | Meaning |
|---|---|
0 |
Success (including when some subdirectories were unreadable). |
1 |
The path does not exist, is not a directory, or could not be accessed. |
How it works
ls-tree reads the provided path, then recursively walks the directory tree with
std::fs::read_dir and std::path::PathBuf, emitting an indented hierarchy.
Strings and paths are passed through the recursive walk as borrowed &Path
values with owned PathBufs only where ownership is genuinely needed, keeping
the borrow checker happy.
Edge cases handled explicitly:
- Hidden files / folders — skipped by default, shown with
-a. - Restricted permissions — an unreadable directory prints
[Access Denied]inline and traversal continues. - Symlink cycles — symlinks are displayed but never descended into.
Development
Contributions are welcome — see CONTRIBUTING.md and please follow the Code of Conduct.
License
Licensed under the MIT License.