ls-tree 0.2.0

A lightweight, dependency-free clone of the Unix `tree` command, written in Rust.
Documentation

ls-tree

CI License: MIT Rust: stable

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 tree output 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).
  • .gitignore awareness (--git-ignore) — filters entries matching root-level .gitignore rules.
  • 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-depth to limit how far down the tree is printed.

Installation

From source (recommended)

git clone https://github.com/NefaroXX/ls-tree.git
cd ls-tree
cargo install --path .

From crates.io

cargo install ls-tree

Build locally

cargo build --release
./target/release/ls-tree

Usage

ls-tree [OPTIONS] [PATH]

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
ls-tree

# Specific path
ls-tree ./src

# Include hidden files, two levels deep
ls-tree -a -L 2 /etc

# JSON output with sizes
ls-tree --json --size ./src

# Git-ignore aware, sorted by size
ls-tree --git-ignore --sort=size

# Human-readable sizes with prune and icons
ls-tree -h --prune --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

cargo build
cargo test
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings

Contributions are welcome — see CONTRIBUTING.md and please follow the Code of Conduct.

License

Licensed under the MIT License.