Skip to content

A modern, cross-platform, multi-threaded, and general purpose filesystem and disk-usage utility that is aware of .gitignore and hidden file rules.

License

Notifications You must be signed in to change notification settings

solidiquis/erdtree

Repository files navigation

erdtree (et)

Build status Crates.io

A modern, vibrant, and multi-threaded file-tree visualizer and disk usage analyzer that respects hidden files and .gitignore rules - basically if tree and du had a baby.

failed to load gif

Table of Contents

Description

erdtree is a modern alternative to the ancient tree command in that it:

  • offers a minimal and user-friendly CLI
  • respects hidden files and .gitignore rules by default
  • displays file sizes in human-readable format by default
  • traverses directories in a parallel manner (4 threads by default)
  • displays files using ANSI colors by default

Usage

$ et -h
erdtree (et) is a multi-threaded filetree visualizer and disk usage analyzer.

Usage: et [OPTIONS] [DIR]

Arguments:
  [DIR]  Root directory to traverse; defaults to current working directory

Options:
  -g, --glob <GLOB>            Include or exclude files using glob patterns
      --iglob <IGLOB>          Include or exclude files using glob patterns; case insensitive
      --glob-case-insensitive  Process all glob patterns case insensitively
  -H, --hidden                 Show hidden files; disabled by default
  -i, --ignore-git-ignore      Ignore .gitignore; disabled by default
  -l, --level <NUM>            Maximum depth to display
  -s, --sort <SORT>            Sort-order to display directory content [default: none] [possible values: name, size, none]
  -S, --follow-links           Traverse symlink directories and consider their disk usage; disabled by default
  -t, --threads <THREADS>      Number of threads to use [default: 4]
  -h, --help                   Print help (see more with '--help')
  -V, --version                Print version

Installation

Cargo

  1. Make sure you have Rust and its toolchain installed.
  2. $ cargo install --tag v1.1.0 --git https://github.com/solidiquis/erdtree
  3. The executable should then be located in $HOME/.cargo/bin/.

Releases

Binaries for common architectures can be downloaded from latest releases.

Other means of installation to come.

Disambiguations

Disk Size

As recommended in IEC 80000-13, this command will report sizes using SI units rather than binary units. As such you can expect 1KB = 1000B and not 1KiB = 1024B.

Additionally:

  • A directory will have a size equal to the sum of the sizes of all of its entries. The size of the directory itself is negligble and isn't taken into account.
  • Files other than directories and regular files (symbolic links, named pipes, sockets, etc.) appear but their memory sizes are not reported as they are negligible.
  • Symbolic links to directories appear but are not traversed nor are their sizes reported by default.
  • Hidden files, files excluded by .gitignore, and files excluded via globbing will be ommitted from the total memory size of their parent directories.

Files Without Read Permissions

Files that don't have read persmissions will appear but won't have their disk sizes reported. If they are directories they will not be traversed. Additionally, their size will not be included in their parent directory's total.

File Coloring

Files are printed in ANSI colors specified according to the LS_COLORS environment variable on GNU/Linux systems. In its absence a default value is used.

Note for MacOS: MacOS uses the LSCOLORS environment variable to determine file colors for the ls command which is formatted very differently from LS_COLORS. MacOS systems will fall back on the aforementioned default value unless the user defines their own LS_COLORS environment variable.

tree Command

This is not a rewrite of the tree command thus it should not be considered a 1-to-1 port. The basic idea is the same: Display the file-tree of the specified directory. There are, however, key fundamental differences under the hood with regard to how file sizes are computed, traversal method, hidden files and .gitignore rules, and printing.

Symlinks to Directories

Symlinks to directories are not traversed nor are their disk usages reported by default. -S, --follow-links enables symlink traversal and reports their disk usages and when printed descendents of the symlink target will have branches of a different color.

failed to load png

Advantages over exa --tree

Exa is a powerful modern equivalent of the ls command which gives the option to print a tree-view of a specified directory, however the primary differences between exa --tree and et are:

  • exa --tree --git-ignore doesn't respect .gitignore rules on a per directory basis whereas et does. With exa the root's .gitignore is considered, but if child directories have their own .gitignore they are disregarded and all of their contents will be printed.
  • et displays the total size of a directory as the sum of all of its entries' sizes whereas exa does not support this. This makes sorting directories in the tree-view by size dubious and unclear. Below are screenshots comparing equivalent usages of et and exa, using long option names for clarity.

exa

failed to load png

erdtree

failed to load png

Rules for Contributing and Feature Requests

Happy to accept contributions but please keep the following in mind:

  • If you're doing some minor refactoring and/or code cleanup feel free to just submit a PR.
  • If you'd like to add a feature and/or make fundamental changes to et's traverse algorithm please open up an issue and get my approval first.
  • Feature adds require tests.

Feature requests in the form of issues in general are welcome.

Special thanks

  • to Reddit user /u/johnm for suggesting that different SI prefixes be colored differently for better visual feedback.
  • to Reddit user /u/lucca_huguet (can be found as luccahuguet on Github) for suggesting that the compiled erdtree binary be shorted to et.
  • to all contributors :]

Questions you might have

Q: Why did you make this? It's totally unnecessary.

A: Ennui.

Q: Why is it called erdtree?

A: It's a reference to Elden Ring.

Q: Is it any good?

A: Yes.

Q: Is it blazingly fast?

A: Should be. I wrote it in Rust.