erdtree (erd)

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

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

你可以将erdtree视为du、tree、find、wc和ls的结合体。

<p align="center"> <img src="https://yellow-cdn.veclightyear.com/2b54e442/6fb36a9a-9006-4142-8161-d81c171d4e95.png?raw=true" alt="加载图片失败" /> </p>

目录

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

使用方法

$ erd --help
erdtree (erd) 是一个跨平台、多线程、通用的文件系统和磁盘使用情况工具。

用法: erd [选项] [目录]

参数:
  [目录]
          要遍历的目录；默认为当前工作目录

选项:
  -c, --config <配置>
          使用命名表而不是.erdtree.toml中的顶级表的配置

  -C, --color <颜色>
          输出着色模式
          
          [默认: auto]

          可能的值:
          - none:  不使用ANSI转义序列纯文本打印
          - auto:  尝试为输出着色
          - force: 始终开启着色

  -d, --disk-usage <磁盘使用>
          打印物理或逻辑文件大小
          
          [默认: physical]

          可能的值:
          - logical:
            文件包含多少字节
          - physical:
            考虑块、稀疏文件和压缩后的实际磁盘字节数
          - line:
            文件包含的总行数
          - word:
            文件包含的总字数
          - block:
            用于存储文件的分配块数

  -f, --follow
          跟随符号链接

  -H, --human
          以人类可读格式打印磁盘使用情况

  -i, --no-ignore
          不遵守.gitignore文件

  -I, --icons
          显示文件图标

  -l, --long
          显示扩展元数据和属性

      --group
          显示文件的组

      --ino
          显示每个文件的inode号

      --nlink
          显示到底层inode的硬链接总数

      --octal
          以八进制数字格式而不是符号格式显示权限

      --time <时间>
          使用哪种时间戳；默认为修改时间

          可能的值:
          - create: 创建时间 (别名: ctime)
          - access: 最后访问时间 (别名: atime)
          - mod:    最后修改时间 (别名: mtime)

      --time-format <时间格式>
          使用哪种时间戳格式；默认为default

          可能的值:
          - iso:
            按照iso8601格式化的时间戳，有轻微差异且省略时区
          - iso-strict:
            严格按照iso8601规范格式化的时间戳
          - short:
            时间戳仅显示日期，格式为YYYY-MM-DD
          - default:
            时间戳以DD MMM HH:MM格式显示

  -L, --level <数字>
          要显示的最大深度

  -p, --pattern <模式>
          用于匹配文件的正则表达式（如果使用'--glob'或'--iglob'则为glob）

      --glob
          启用基于glob的搜索

      --iglob
          启用不区分大小写的基于glob的搜索

  -t, --file-type <文件类型>
          将正则表达式或glob搜索限制为特定文件类型

          可能的值:
          - file: 普通文件
          - dir:  目录
          - link: 符号链接

  -P, --prune
          从输出中移除空目录

  -s, --sort <排序>
          如何排序条目
          
          [默认: size]

          可能的值:
          - name:    按文件名以词典顺序排序
          - rname:   按文件名以反向词典顺序排序
          - size:    按大小从小到大排序，从上到下
          - rsize:   按大小从大到小排序，从下到上
          - access:  按访问日期从新到旧排序
          - raccess: 按访问日期从旧到新排序
          - create:  按创建日期从新到旧排序
          - rcreate: 按创建日期从旧到新排序
          - mod:     按修改日期从新到旧排序
          - rmod:    按修改日期从旧到新排序

      --dir-order <目录顺序>
          在所有其他文件类型之前或之后排序目录
          
          [默认: none]

          可能的值:
          - none:  目录作为普通节点排序
          - first: 将目录排在文件之上
          - last:  将目录排在文件之下

  -T, --threads <线程数>
          要使用的线程数
          
          [默认: 10]

  -u, --unit <单位>
          以二进制或SI单位报告磁盘使用情况
          
          [默认: bin]

          可能的值:
          - bin: 使用二进制前缀显示磁盘使用情况
          - si:  使用SI前缀显示磁盘使用情况

  -x, --one-file-system
          防止遍历到不同文件系统上的目录

  -y, --layout <布局>
          渲染输出时使用的布局类型
          
          [默认: regular]

          可能的值:
          - regular:  输出树，根节点在输出底部
          - inverted: 输出树，根节点在输出顶部
          - flat:     输出平面布局，使用路径而不是ASCII树
          - iflat:    输出反向平面布局，根节点在输出顶部

  -., --hidden
          显示隐藏文件

      --no-git
          在遍历隐藏文件时禁用.git目录的遍历

      --completions <补全>
          将给定shell的补全打印到stdout
          
          [可能的值: bash, elvish, fish, powershell, zsh]

      --dirs-only
          仅打印目录

      --no-config
          不读取配置文件

      --no-progress
          隐藏进度指示器

      --suppress-size
          从输出中省略磁盘使用情况

      --truncate
          截断输出以适应终端模拟器窗口

  -h, --help
          打印帮助信息（使用'-h'查看摘要）

  -V, --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

# 像`du`一样计算文件大小
# 例如 `erd --config du`
[du]
disk_usage = "block"
icons = true
layout = "flat"
no-ignore = true
no-git = true
hidden = true
level = 1

# 执行`ls -l`
# 例如 `erd --config ls`
[ls]
icons = true
human = true
level = 1
suppress-size = true
long = true

# 这个代码库中有多少行Rust代码?
# 例如 `erd --config rs`
[rs]
disk-usage = "line"
level = 1
pattern = "\\.rs$"

.erdtree.toml支持多种配置。顶层表是无需额外参数就会应用的主配置。 如果你想使用单独的配置,创建一个命名表(如上面的du),设置你的参数,然后像这样调用:

$ erd --config du

# 等同于

$ 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系统上:

• $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
      跟随符号链接

当跟随符号链接时,它们的目标(及其后代)将计入总磁盘使用量,否则将报告符号链接本身的大小。 如果符号链接的目标恰好在与符号链接本身相同的文件树中,则目标及其后代不会在总磁盘使用量中重复计算。 当跟随指向目录的符号链接时,其所有后代的框线字符将以不同的颜色绘制,以提供更好的视觉反馈:

<p align="center"> <img src="https://yellow-cdn.veclightyear.com/2b54e442/64423e3e-4372-4a12-8c4e-25eb139fb146.png?raw=true" alt="加载图片失败" /> </p>

磁盘使用量

默认情况下,磁盘使用量报告为存储在磁盘上的物理字节总数。要获得人类可读的形式:

-H, --human
      以人类可读的格式打印磁盘使用量

使用人类可读的形式时,默认报告二进制单位(例如1 KiB = 1024 B)。如果你更喜欢SI单位(1 KB = 1000 B),可以使用以下选项:

-u, --unit <UNIT>
      以二进制或SI单位报告磁盘使用量
      
      [默认: bin]

      可能的值:
      - bin: 使用二进制前缀显示磁盘使用量
      - si:  使用SI前缀显示磁盘使用量

此外,还可以使用各种其他磁盘使用量度量代替物理字节。你可以使用以下度量:

-d, --disk-usage <DISK_USAGE>
      打印物理或逻辑文件大小
      
      [默认: physical]

      可能的值:
      - logical:
        文件包含多少字节
      - physical:
        考虑块、稀疏文件和压缩后的实际磁盘字节数
      - line:
        文件包含的总行数
      - word:
        文件包含的总字数
      - block:
        用于存储文件的分配块数

最后,如果你想在输出中省略磁盘使用量:

--suppress-size
  在输出中省略磁盘使用量

物理大小与逻辑大小

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

匹配du输出

如果你想获得与du完全相同的磁盘使用量报告,可以执行以下操作:

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

或简写为

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

<p align="center"> <img src="https://yellow-cdn.veclightyear.com/2b54e442/395aadd0-cf8d-4b0c-ada1-94982d2afbce.png?raw=true" alt="加载png失败" /> </p>

字数和行数统计

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

此外,目录的字数和行数是其所有后代的字数/行数之和。

布局

erdtree提供四种布局:

-y, --layout <LAYOUT>
      渲染输出时使用的布局类型
      
      [默认: regular]

      可能的值:
      - regular:  输出树,根节点在输出底部
      - inverted: 输出树,根节点在输出顶部
      - flat:     使用路径而不是ASCII树输出平面布局
      - iflat:    输出倒置的平面布局,根在输出顶部

• inverted布局是更传统的tree式布局,根节点位于输出的最顶部。
• regular布局是一棵树,根节点位于输出的底部,便于快速了解总磁盘使用情况。
• flat布局是无树的输出,更接近du。

gitignore

-i, --no-ignore
      不遵守.gitignore文件

默认情况下会遵守.gitignore,但可以使用上述参数忽略它。.gitignore规则也会在每个目录的基础上被遵守,所以 遍历过程中遇到的每个包含.gitignore的目录也会被考虑在内。

如果遵守.gitignore,任何被忽略的文件都不会被包含在总磁盘使用量中。

隐藏文件

-., --hidden
      显示隐藏文件

  --no-git
      在遍历隐藏文件时禁用.git目录的遍历

默认情况下会忽略隐藏文件,但可以使用-., --hidden包含它们。如果选择显示隐藏文件,.git会被包括在内;要排除 它,使用--no-git。

如果忽略隐藏文件,它们不会被包含在总磁盘使用量中。

图标

-I, --icons                      显示文件图标

图标是一个可选功能,因为要正确渲染图标,需要你的终端模拟器所使用的字体包含正确渲染图标所需的字形。

如果你的图标看起来像这样:

<p align="center"> <img src="https://yellow-cdn.veclightyear.com/2b54e442/4a65c907-2674-432e-a5ee-400bb2f55576.png?raw=true" alt="加载png失败" /> </p>

这意味着你正在使用的字体不包含相关字形。要解决这个问题,下载一个NerdFont并将其连接到你的终端模拟器。

最大深度

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

-L, --level <NUM>
      要显示的最大深度

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

修剪空目录

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

-P, --prune
      从输出中删除空目录

排序

提供了各种排序方法:

-s, --sort <SORT>
      如何对条目进行排序
      
      [默认: size]

      可能的值:
      - name:    按文件名的字典顺序对条目进行排序
      - rname:   按文件名的反向字典顺序对条目进行排序
      - size:    按大小从小到大、从上到下对条目进行排序
      - rsize:   按大小从大到小、从下到上对条目进行排序
      - access:  按访问日期从新到旧对条目进行排序
      - raccess: 按访问日期从旧到新对条目进行排序
      - create:  按创建日期从新到旧对条目进行排序
      - rcreate: 按创建日期从旧到新对条目进行排序
      - mod:     按修改日期从新到旧对条目进行排序
      - rmod:    按修改日期从旧到新对条目进行排序

  --dir-order <DIR_ORDER>
      在所有其他文件类型之前或之后对目录进行排序
      
      [默认: none]

      可能的值:
      - none:  目录按照普通节点的方式排序
      - first: 将目录排在文件之上
      - last:  将目录排在文件之下

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

仅目录

你可以只输出目录:

--dirs-only
  只打印目录

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

长视图

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

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

-l, --long
  显示扩展元数据和属性

    --group
      显示文件的组

    --ino
      显示每个文件的ino

    --nlink
      显示指向底层inode的硬链接总数

    --octal
      以数字八进制格式而不是符号格式显示权限

  --time <TIME>
      使用哪种时间戳;默认为修改时间

      可能的值:
      - create: 创建时间(别名: ctime)
      - access: 最后访问时间(别名: atime)
      - mod:    最后修改时间(别名: mtime)
--time-format <时间格式>
      使用哪种格式显示时间戳;默认为 default

      可能的值:
      - iso:
        按照 iso8601 格式化的时间戳,略有不同且省略时区
      - iso-strict:
        严格按照 iso8601 规范格式化的时间戳
      - short:
        时间戳仅显示日期,格式为 YYYY-MM-DD
      - default:
        时间戳以 DD MMM HH:MM 格式显示

默认情况下,从左到右显示的列为:

• 符号表示的权限
• 文件所有者
• 文件最后修改(或创建或最后访问)的日期

正则表达式和通配符

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

-p, --pattern <模式>
      用于匹配文件的正则表达式(如果使用'--glob'或'--iglob'则为通配符)

  --glob
      启用基于通配符的搜索

  --iglob
      启用不区分大小写的基于通配符的搜索

-t, --file-type <文件类型>
      将正则表达式或通配符搜索限制为特定文件类型

      可能的值:
      - file: 普通文件
      - dir:  目录
      - link: 符号链接

如果在过滤时未提供 --file-type,则默认为普通文件(file)。

此外,任何被过滤掉的文件都将从总磁盘使用量中排除。

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

参考:

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

截断输出

在输出不适合终端模拟器窗口的情况下,输出本身可能会显示不连贯:

<p align="center"> <img src="https://yellow-cdn.veclightyear.com/2b54e442/e31d6685-6789-4264-9bb0-01289aa03282.png?raw=true" alt="failed to load picture" /> </p>

在这些情况下,可以使用以下选项:

--truncate
  截断输出以适应终端模拟器窗口

<p align="center"> <img src="https://yellow-cdn.veclightyear.com/2b54e442/46be128e-6673-4e93-a9f2-e22e2c747367.png?raw=true" alt="failed to load picture" /> </p>

重定向输出和着色

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

但是,如果默认行为不符合您的需求,您可以控制着色模式:

-C, --color <颜色>
      输出着色模式
      
      [默认: auto]

      可能的值:
      - none:  不使用 ANSI 转义序列进行纯文本打印
      - auto:  尝试为输出着色
      - force: 始终开启着色

erdtree 还支持 NO_COLOR。

<p align="center"> <img src="https://yellow-cdn.veclightyear.com/2b54e442/c7fcbaed-af83-4c44-ba5f-7291a3fb4034.png?raw=true" alt="failed to load picture" /> </p>

并行性

可以使用以下选项调整 erdtree 使用的线程数:

-T, --threads <线程数>          要使用的线程数 [默认: 3]

为什么使用并行性

一个常见的问题是,当文件系统 I/O 是串行处理时,并行性如何提高磁盘读取性能。

虽然这是事实,但并行性仍然会提高吞吐量,因为磁盘有一个队列深度,当饱和时,允许聚合处理请求,使磁盘保持忙碌,而不是在请求之间等待 erdtree 进行 CPU 绑定处理。此外,这些线程不仅并行化磁盘读取,还并行化检索数据的处理。

但是应该注意,性能作为线程数的函数是渐近的(参见 Amdahl 定律),因此在达到某个线程数阈值后,您很快就会达到收益递减的点,因为您将为管理更大的线程池付出代价,而没有额外的好处。

有关该主题的实证数据,请查看这篇文章。

自动补全

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

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

同一文件系统

如果您正在遍历包含指向其他文件系统的挂载点的目录,且不希望遍历这些目录,请使用以下选项:

-x, --one-file-system
      防止遍历位于不同文件系统上的目录

贡献规则

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

安全策略

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

与类似程序的比较

不言而喻,以下程序都有其独特之处,并对 erdtree 的开发产生了很大影响。虽然以下每个程序都高度专注于作为其 Unix 祖先的现代替代品,但 erdtree 旨在从人们最常用的每个程序中提取一些部分,并将它们组装成一个统一的高度实用的工具。

这里不会说明为什么应该选择 erdtree 而不是 X、Y 或 Z,但由于与以下程序有一些显著的相似之处,值得进行简要比较。

exa

exa 和 erdtree 的相似之处在于它们都有树形视图,并显示有关权限、所有者、组等信息。

然而,exa 的缺点是它不提供目录磁盘使用情况的信息,这也使得按大小对文件排序有些可疑。不过,exa 相对于 erdtree 的优势在于它作为 ls 替代品更加全面。

两个工具是互补的,建议您的工具包中同时拥有这两个工具。

dua

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

dust

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

fd

fd 作为一般查找工具更加全面,提供自己作为 find 的现代替代品。如果您希望在搜索能力上有更多的粒度,超越仅仅通配符、正则表达式和三种基本文件类型(文件、目录和符号链接),那么 fd 是最佳选择。

您可能会有的问题

问:为什么要制作这个?这完全没有必要。

答:无聊。

问:为什么叫 erdtree?

答:这是对 Elden Ring 中一个崇拜对象的引用。

问:它好用吗?

答:是的。

问:为什么没有提到这个项目是用 Rust 编写的,速度极快?它很慢吗?

答:好吧。erdtree 是用 Rust 编写的,速度极快。

<img src="https://yellow-cdn.veclightyear.com/2b54e442/0efba1ea-0b27-45b7-bd09-6961fbda0458.jpg">