erdtree (erd)

erdtree 是一个现代、跨平台、多线程的通用文件系统和磁盘使用工具，它能够识别 .gitignore 和隐藏文件规则。以下是一些特性亮点：

• 使用多种指标报告磁盘使用情况：字节（逻辑或物理）、块（仅限 Unix）、单词计数或行计数。
• 支持类似 ls -l 的视图，包含所有者、组、文件权限等信息（仅限 Unix）。
• 默认遵守隐藏文件和 gitignore 规则。
• 支持基于正则表达式和 glob 的按文件类型搜索。
• 提供多种布局：反转树输出、类似 tree 的输出或类似 du 的输出。
• 细粒度排序能力。
• 支持图标。
• 使用 LS_COLORS 着色。

您可以将 erdtree 视为 du、tree、find、wc 和 ls 的一点点结合。

目录内容

• 用法
• 安装
• 文档
  • 配置文件
    • Toml 文件
    • .erdtreerc
  • 硬链接
  • 符号链接
  • 磁盘使用
    • 物理与逻辑
    • 匹配 du 输出
    • 单词和行计数
  • 布局
  • gitignore
  • 隐藏文件
  • 图标
  • 最大深度
  • 修剪空目录
  • 排序
  • 仅目录
  • 长视图
  • 正则表达式和 globbing
  • 截断输出
  • 重定向输出和着色
  • 并行处理
  • 补全
  • 相同文件系统
• 与类似程序的比较
  • exa
  • dua
  • dust
  • fd
• 贡献规则
• 安全策略
• 你可能有的问题

用法

$ 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 以及所有相关参数目前在 Windows 上不可用，但计划支持 Windows 版本。

安装

crates.io (非 Windows)

请确保您已安装 Rust 及其工具链。

$ cargo install erdtree

crates.io (Windows)

Windows 版本依赖于一些实验性功能以正确支持硬链接检测。如果您想从 crates.io 构建的话，您需要先安装 nightly 工具链，然后再安装 erdtree。

$ rustup toolchain install nightly-2023-06-11

之后

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

Homebrew-core

$ brew install erdtree

Scoop

$ scoop install erdtree

NetBSD

$ pkgin install erdtree

版本发布

可以从最新版本中下载适用于常见架构的二进制文件。

最新非发布版本

如果您想使用 master 上的最新功能，但这些功能尚未作为版本的一部分包含在内

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

其他安装方式即将推出。

文档

配置文件

如果 erdtree 的默认设置不符合您特定的要求，您可以使用配置文件设置自己的默认设置。

配置文件目前有两种格式：.erdtreerc（即将弃用）和 .erdtree.toml。如果您两者都有，.erdtreerc 将优先考虑，而 .erdtree.toml 将被忽略，但请注意 .erdtreerc 将在不久的将来被弃用。没有必要两者都保留。

TOML 文件

erdtree 将在以下位置之一查找 .erdtree.toml

在 Unix 系统

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

在 Windows

%APPDATA%\erdtree\.erdtree.toml

这里 以及以下是一个有效的 .erdtree.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 支持多个配置。顶层表是主配置，将不添加额外参数而应用。如果您想使用单独的配置，创建一个命名表，如上例中的 du，设置您的参数，并按如下方式调用它

$ erd --config du

# equivalent to

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

关于参数，您需要了解以下三条规则

1. .erdtree.toml 只接受带前缀的短名称参数。
2. 类型被强制执行，所以数字应该是数字，布尔值应该是布尔值，字符串应该是字符串，依此类推。
3. snake_case 和 kebap-case 都有效。

.erdtreerc

erdtree 将在以下位置之一查找配置文件

在 Linux/Mac/Unix-like

• $ERDTREE_CONFIG_PATH
• $XDG_CONFIG_HOME/erdtree/.erdtreerc
• $XDG_CONFIG_HOME/.erdtreerc
• $HOME/.config/erdtree/.erdtreerc
• $HOME/.erdtreerc

在 Windows

• $ERDTREE_CONFIG_PATH
• %APPDATA%\erdtree\.erdtreerc

配置文件的格式如下

• 每一行都是一个 erdtree 选项/参数。
• 以 # 开头的行被视为注释，因此会被忽略。

命令行中传递给 erdtree 的参数将覆盖 .erdtreerc 中的参数。

点击这里 查看一个 .erdtreerc 示例。

如果您想忽略某个配置而不删除它，可以使用 --no-config。

硬链接

如果在同一文件树中有多个指向同一inode的硬链接，它们都将包含在输出中，但在计算总磁盘使用量时只考虑一个。

符号链接

-f, --follow
      Follow symlinks

当跟随符号链接时，其目标（及其子代）将被计入总磁盘使用量，否则将报告符号链接本身的大小。如果符号链接的目标恰好与符号链接本身位于同一文件树中，则目标及其子代不会被重复计入总磁盘使用量。当跟随目录符号链接时，其子代的所有框绘制字符将以不同的颜色绘制，以提供更好的视觉反馈。

磁盘使用

默认情况下，磁盘使用量报告为存储在磁盘上的物理字节数量。要获取可读形式

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

当使用可读形式时，默认情况下会报告二进制单位（例如 1 KiB = 1024 B）。如果您更喜欢SI单位（1 KB = 1000 B），可以使用以下命令

-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

此外，可以使用各种其他磁盘使用量指标代替物理字节数。您有以下指标可供选择

-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

最后，如果您想从输出中省略磁盘使用量

--suppress-size
  Omit disk usage from output

物理与逻辑

实际大小考虑了压缩、稀疏文件和分配给特定文件的实际块。逻辑大小仅报告文件中的总字节数。

匹配 du 输出

如果您想得到与 du 相同的磁盘使用量报告，可以这样做

$ erd --layout flat --disk-usage block --no-ignore --hidden --level

或简写为

$ erd -y flat -d block -i -.

单词和行计数

当选择以单词和行数报告磁盘使用量时，与 wc 不同，erdtree 不会尝试计算无法编码为UTF-8字符串的文件（如JPEG文件）的单词或行数。对于这些情况，行或总单词数将仅显示为空。

此外，目录的单词和行数是其所有子代的行/单词数的总和。

布局

erdtree 提供了四种布局

-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

• inverted 布局是一种更传统的类似 tree 的布局，其中根节点位于输出的最顶部。
• regular 布局是一种树形结构，根节点位于输出的底部，可以快速了解总磁盘使用量。
• flat 布局是一种无树的输出，更类似于 du。

gitignore

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

.gitignore 默认受尊重，但可以使用上述参数忽略。每个目录的 .gitignore 规则也受尊重，因此每个在遍历时遇到的具有 .gitignore 的目录也将被考虑。

如果尊重 .gitignore，则忽略的任何文件将不会包括在总磁盘使用量中。

隐藏文件

-., --hidden
      Show hidden files

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

隐藏文件默认被忽略，但可以使用 -., --hidden 包括。如果选择显示隐藏文件，则包括 .git；要排除它，请使用 --no-git。

如果忽略隐藏文件，则它不会包括在总磁盘使用量中。

图标

-I, --icons                      Display file icons

图标是可选功能，因为为了正确渲染图标，您连接到终端模拟器的字体必须包含必要的符号。

如果您的图标看起来像这样

这意味着您使用的字体不包含相关的符号。要解决这个问题，请下载一个 NerdFont 并将其连接到您的终端模拟器。

最大深度

默认情况下，将完全遍历目录。要限制最大深度

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

限制要显示的最大深度不会影响总磁盘使用量报告或文件计数报告。

修剪空目录

有时输出中可能会出现空目录。要删除它们

-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

--dir-order 和 --sort 可以独立使用。

仅目录

您只能输出具有

--dirs-only
  Only print directories

这不会影响总磁盘使用量。

长视图

目前仅在类Unix平台上可用。计划支持Windows。

erdtree 支持类似于 ls -l 的长视图

-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

默认情况下，显示的列从左到右的顺序是

• 权限 以符号表示法
• 文件所有者
• 文件最后修改日期（或创建日期或最后访问日期）

正则表达式和 globbing

使用以下方式支持通过正则表达式或通配符过滤特定文件

-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

如果在过滤时未提供 --file-type，则默认为常规文件（file）。

此外，任何被过滤掉的文件将不会计入总磁盘使用量。

最后，当将正则表达式或通配符应用于目录时，无论文件类型如何，其所有后代都会包含在输出中。如果您只想显示目录，可以使用 --dirs-only。

参考

• 通配符规则
• 正则表达式

截断输出

在输出不适合终端模拟器窗口的情况下，输出本身可能会变得不连贯

在这种情况下，可以使用以下方法

--truncate
  Truncate output to fit terminal emulator window

重定向输出和着色

默认情况下，如果发现 stdout 是一个 tty，则启用输出着色。如果输出不是一个 tty，例如将输出重定向到文件或将输出管道传输到另一个命令，则禁用着色。

然而，如果默认行为不适合您的需求，您可以控制着色的模式

-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

erdtree 还支持 NO_COLOR。

并行处理

可以通过以下方式调整 erdtree 使用的线程数

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

为什么需要并行处理

人们常常问的一个问题是，当文件系统I/O以串行方式处理时，并行处理是如何在磁盘读取中受益的。

虽然这是真的，但并行处理仍然由于磁盘有一个 队列深度，当饱和时，允许请求以聚合方式处理，从而使磁盘保持忙碌，而不是等待 erdtree 在请求之间进行CPU密集型处理。此外，这些线程不仅仅并行处理磁盘读取，还并行处理检索到的数据。

然而，需要注意的是，性能作为线程数的一个函数，其性质是渐近的（参见 Amdahl定律），因此您会在达到一定线程数阈值后迅速达到收益递减的点，因为您会为管理更大的线程池付出代价，而没有任何额外的收益。

关于该主题的实证数据，请参阅 这篇文章。

补全

--completions 用于为常用shell生成自动补全，以便 tab 键可以尝试完成您的命令或提供提示；您放置输出的位置高度依赖于您的shell以及您的配置。在我的环境中，我使用 zshell 与 oh-my-zsh，我会这样安装补全

$ et --completions zsh > ~/.oh-my-zsh/completions/_erd
$ source ~/.zshrc

相同文件系统

如果你正在遍历包含其他文件系统挂载点的目录，而这些挂载点是你不想遍历的，请使用以下方法

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

贡献规则

有关如何贡献的规则，请参阅CONTRIBUTING.md。

安全策略

有关erdtree的安全策略以及如何报告安全漏洞的信息，请参阅SECURITY_POLICY.md。

与类似程序的比较

以下程序本身都非常出色，并且在erdtree的开发中产生了深远的影响。虽然以下每个程序都高度专业化，作为Unix前辈的现代替代品，但erdtree的目标是收集人们最常使用的一些功能，将它们组装成一个统一且高度实用的工具。

这里不会详细说明为什么erdtree比X、Y或Z更好，但由于它与以下程序有一些显著相似之处，因此值得简要比较。

exa

exa和erdtree都相似，因为它们都提供树状视图，并显示有关权限、所有者、组等信息。

然而，exa的缺点是它不提供有关目录磁盘使用情况的信息，这也使得按大小排序文件有些令人怀疑。但是，exa与erdtree相比的优势在于，exa作为一个ls替代品更为全面。

这两个工具是互补的，建议您将它们都纳入您的工具箱。

dua

dua是一款出色的交互式磁盘使用工具，是ncdu的现代替代品。如果您想要一个交互式且仅关注磁盘使用的工具，那么dua可能更适合您。如果您对文件权限感兴趣，并想在不启动整个交互式UI的情况下快速进行磁盘使用静态分析，那么可能需要考虑使用erdtree。

dust

dust是另一款出色的工具，它在血统上更接近传统的du命令。如果您严格寻找du的现代替代品，那么dust是一个不错的选择。

fd

fd作为一个通用的查找工具更为全面，它本身可以作为一个现代的find替代品。如果您在搜索时需要更多的粒度，而不仅仅是globbing、正则表达式以及三种基本文件类型（文件、目录和符号链接），那么fd是最佳选择。

你可能有的问题

问：你为什么要做这个？这完全是多余的。

答：无聊。

问：为什么叫erdtree？

答：这是对《艾尔登法环》中一个崇拜对象的引用。

问：它好吗？

答：是的。

问：为什么没有提到这个项目速度极快或用Rust编写的？是不是很慢？

答：好吧，好吧。 erdtree是用Rust编写的，速度极快。