path: root/README.md

# erdtree (erd)

[![Build status](https://github.com/solidiquis/erdtree/actions/workflows/ci.yml/badge.svg)](https://github.com/solidiquis/erdtree/actions)
[![Crates.io](https://img.shields.io/crates/v/erdtree.svg)](https://crates.io/crates/erdtree)
[![Packaging status](https://repology.org/badge/tiny-repos/erdtree.svg)](https://repology.org/project/erdtree/versions)
[![Crates.io](https://img.shields.io/crates/d/erdtree)](https://crates.io/crates/erdtree)

`erdtree` is a modern, cross-platform, multi-threaded, and general purpose filesystem and disk-usage utility that is aware of `.gitignore` and hidden file rules.
The following are some feature highlights:
* Reports disk usage using a variety of metrics: bytes (logical or physical), blocks (Unix-only), word-count, or line-count.
* Supports an `ls -l`-like view with information about owners, group, file permission, etc. (Unix-only).
* Respects hidden file and gitignore rules by default.
* Supports regular expressions and glob based searching by file-type.
* Comes with several layouts: a reverse tree output, a `tree`-like output, or a `du`-like output.
* Granular sorting capabilities.
* Supports icons.
* Colorized with `LS_COLORS`.

You can think of `erdtree` as a little bit of `du`, `tree`, `find`, `wc` and `ls`.

<p align="center">
  <img src="https://github.com/solidiquis/erdtree/blob/master/assets/top_showcase.png?raw=true" alt="failed to load picture" />
</p>

## Table of Contents

* [Usage](#usage)
* [Installation](#installation)
* [Documentation](#documentation)
  - [Configuration file](#configuration-file)
      - [Toml file](#toml-file)
      - [.erdtreerc](#erdtreerc)
  - [Hardlinks](#hardlinks)
  - [Symlinks](#symlinks)
  - [Disk usage](#disk-usage)
      - [Physical vs logical](#physical-vs-logical)
      - [Matching `du` output](#matching-du-output)
      - [Word and line count](#word-and-line-count)
  - [Layouts](#layouts)
  - [gitignore](#gitignore)
  - [Hidden files](#hidden-files)
  - [Icons](#icons)
  - [Maximum depth](#maximum-depth)
  - [Pruning empty directories](#pruning-empty-directories)
  - [Sorting](#sorting)
  - [Directories only](#directories-only)
  - [Long view](#long-view)
  - [Regular expressions and globbing](#regular-expressions-and-globbing)
  - [Truncating output](#truncating-output)
  - [Redirecting output and colorization](#redirecting-output-and-colorization)
  - [Parallelism](#parallelism)
  - [Completions](#completions)
  - [Same filesystem](#same-filesystem)
* [Comparisons against similar programs](#comparisons-against-similar-programs)
  - [exa](#exa)
  - [dua](#dua)
  - [dust](#dust)
  - [fd](#fd)
* [Rules for contributing](#rules-for-contributing)
* [Security policy](#security-policy)
* [Questions you might have](#questions-you-might-have)

## Usage

```
$ erd --help
erdtree (erd) is a cross-platform, multi-threaded, and general purpose filesystem and disk usage utility.

Usage: erd [OPTIONS] [DIR]

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

Options:
  -c, --config <CONFIG>
          Use configuration of named table rather than the top-level table in .erdtree.toml

  -C, --color <COLOR>
          Mode of coloring output
          
          [default: auto]

          Possible values:
          - none:  Print plainly without ANSI escapes
          - auto:  Attempt to colorize output
          - force: Turn on colorization always

  -d, --disk-usage <DISK_USAGE>
          Print physical or logical file size
          
          [default: physical]

          Possible values:
          - logical:
            How many bytes does a file contain
          - physical:
            How many actual bytes on disk, taking into account blocks, sparse files, and compression
          - line:
            How many total lines a file contains
          - word:
            How many total words a file contains
          - block:
            How many blocks are allocated to store the file

  -f, --follow
          Follow symlinks

  -H, --human
          Print disk usage in human-readable format

  -i, --no-ignore
          Do not respect .gitignore files

  -I, --icons
          Display file icons

  -l, --long
          Show extended metadata and attributes

      --group
          Show file's groups

      --ino
          Show each file's ino

      --nlink
          Show the total number of hardlinks to the underlying inode

      --octal
          Show permissions in numeric octal format instead of symbolic

      --time <TIME>
          Which kind of timestamp to use; modified by default

          Possible values:
          - create: Time created (alias: ctime)
          - access: Time last accessed (alias: atime)
          - mod:    Time last modified (alias: mtime)

      --time-format <TIME_FORMAT>
          Which format to use for the timestamp; default by default

          Possible values:
          - iso:
            Timestamp formatted following the iso8601, with slight differences and the time-zone omitted
          - iso-strict:
            Timestamp formatted following the exact iso8601 specifications
          - short:
            Timestamp only shows date without time in YYYY-MM-DD format
          - default:
            Timestamp is shown in DD MMM HH:MM format

  -L, --level <NUM>
          Maximum depth to display

  -p, --pattern <PATTERN>
          Regular expression (or glob if '--glob' or '--iglob' is used) used to match files

      --glob
          Enables glob based searching

      --iglob
          Enables case-insensitive glob based searching

  -t, --file-type <FILE_TYPE>
          Restrict regex or glob search to a particular file-type

          Possible values:
          - file: A regular file
          - dir:  A directory
          - link: A symlink

  -P, --prune
          Remove empty directories from output

  -s, --sort <SORT>
          How to sort entries
          
          [default: size]

          Possible values:
          - name:    Sort entries by file name in lexicographical order
          - rname:   Sort entries by file name in reversed lexicographical order
          - size:    Sort entries by size smallest to largest, top to bottom
          - rsize:   Sort entries by size largest to smallest, bottom to top
          - access:  Sort entries by newer to older Accessing Date
          - raccess: Sort entries by older to newer Accessing Date
          - create:  Sort entries by newer to older Creation Date
          - rcreate: Sort entries by older to newer Creation Date
          - mod:     Sort entries by newer to older Alteration Date
          - rmod:    Sort entries by older to newer Alteration Date

      --dir-order <DIR_ORDER>
          Sort directories before or after all other file types
          
          [default: none]

          Possible values:
          - none:  Directories are ordered as if they were regular nodes
          - first: Sort directories above files
          - last:  Sort directories below files

  -T, --threads <THREADS>
          Number of threads to use
          
          [default: 10]

  -u, --unit <UNIT>
          Report disk usage in binary or SI units
          
          [default: bin]

          Possible values:
          - bin: Displays disk usage using binary prefixes
          - si:  Displays disk usage using SI prefixes

  -x, --one-file-system
          Prevent traversal into directories that are on different filesystems

  -y, --layout <LAYOUT>
          Which kind of layout to use when rendering the output
          
          [default: regular]

          Possible values:
          - regular:  Outputs the tree with the root node at the bottom of the output
          - inverted: Outputs the tree with the root node at the top of the output
          - flat:     Outputs a flat layout using paths rather than an ASCII tree
          - iflat:    Outputs an inverted flat layout with the root at the top of the output

  -., --hidden
          Show hidden files

      --no-git
          Disable traversal of .git directory when traversing hidden files

      --completions <COMPLETIONS>
          Print completions for a given shell to stdout
          
          [possible values: bash, elvish, fish, powershell, zsh]

      --dirs-only
          Only print directories

      --no-config
          Don't read configuration file

      --no-progress
          Hides the progress indicator

      --suppress-size
          Omit disk usage from output

      --truncate
          Truncate output to fit terminal emulator window

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version
```

`-l, --long` and all of its arguments are currently not available on Windows, but support for a Windows variant is planned.

## Installation

### crates.io (non-Windows)

Make sure you have [Rust and its toolchain](https://www.rust-lang.org/tools/install) installed.

```
$ cargo install erdtree
```

### crates.io (Windows)

The Windows version relies on some experimental features in order to properly support hard-link detection. If you want to build from `crates.io` you'll first need to install the nightly toolchain before installing `erdtree`:

```
$ rustup toolchain install nightly-2023-06-11
```

Thereafter:

```
$ cargo +nightly-2023-06-11 install erdtree
```

### Homebrew-core

```
$ brew install erdtree
```

### Scoop

```
$ scoop install erdtree
```

### NetBSD

```
$ pkgin install erdtree
```

### Releases

Binaries for common architectures can be downloaded from latest releases.

### Latest non-release

If you'd like the latest features that are on `master` but aren't yet included as part of a release:

```
$ cargo install --git https://github.com/solidiquis/erdtree --branch master
```

Other means of installation to come.

## Documentation

### Configuration file

If `erdtree`'s out-of-the-box defaults don't meet your specific requirements, you can set your own defaults using a configuration file.

The configuration file currently comes in two flavors: `.erdtreerc` (to be deprecated) and `.erdtree.toml`. If you have both,
`.erdtreerc` will take precedent and `.erdtree.toml` will be disregarded, but please **note that `.erdtreerc` will be deprecated in the near future.** There is
no reason to have both.

#### TOML file

`erdtree` will look for `.erdtree.toml` in any of the following locations:

On Unix-systems:

```
$ERDTREE_TOML_PATH
$XDG_CONFIG_HOME/erdtree/.erdtree.toml
$XDG_CONFIG_HOME/.erdtree.toml
$HOME/.config/erdtree/.erdtree.toml
$HOME/.erdtree.toml
```

On Windows:

```
%APPDATA%\erdtree\.erdtree.toml
```

[Here](example/.erdtree.toml) and below is an example of a valid `.erdtree.toml`:

```toml
icons = true
human = true

# Compute file sizes like `du`
# e.g. `erd --config du`
[du]
disk_usage = "block"
icons = true
layout = "flat"
no-ignore = true
no-git = true
hidden = true
level = 1

# Do as `ls -l`
# e.g. `erd --config ls`
[ls]
icons = true
human = true
level = 1
suppress-size = true
long = true

# How many lines of Rust are in this code base?
# e.g. `erd --config rs`
[rs]
disk-usage = "line"
level = 1
pattern = "\\.rs$"
```

`.erdtree.toml` supports multiple configurations. The top-level table is the main config that will be applied without additional arguments.
If you wish to use a separate configuration, create a named table like `du` above, set your arguments, and invoke it like so:

```
$ erd --config du

# equivalent to

$ erd --disk-usage block --icons --layout flat --no-ignore --no-git --hidden --level 1
```

As far as the arguments go there are only three rules you need to be aware of:
1. `.erdtree.toml` only accepts long-named arguments without the preceding "--".
2. Types are enforced, so numbers are expected to be numbers, booleans are expected to be booleans, strings are expected to be strings, and so on and so forth.
3. `snake_case` and `kebap-case` works.

#### .erdtreerc

`erdtree` will look for a configuration file in any of the following locations:

On Linux/Mac/Unix-like:
- `$ERDTREE_CONFIG_PATH`
- `$XDG_CONFIG_HOME/erdtree/.erdtreerc`
- `$XDG_CONFIG_HOME/.erdtreerc`
- `$HOME/.config/erdtree/.erdtreerc`
- `$HOME/.erdtreerc`

On Windows:
- `$ERDTREE_CONFIG_PATH`
- `%APPDATA%\erdtree\.erdtreerc`

The format of a config file is as follows:
- Every line is an `erdtree` option/argument.
- Lines starting with `#` are considered comments and are thus ignored.

Arguments passed to `erdtree` on the command-line will override those found in `.erdtreerc`.

[Click here](example/.erdtreerc) for an example `.erdtreerc`.

**If you have a config that you would like to ignore without deleting you can use `--no-config`.**

### Hardlinks

If multiple hardlinks that point to the same inode are in the same file-tree, all will be included in the output but only one is considered when computing overall disk usage.

### Symlinks

```
-f, --follow
      Follow symlinks
```

Symlinks when followed will have their targets (and descendants) counted towards total disk usage, otherwise the size of the symlink itself will be reported.
If a symlink's target happens to be in the same file-tree as the symlink itself, the target and its descendants will not be doubl