If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/solidiquis/erdtree shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 9 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 88% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live solidiquis/erdtree repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/solidiquis/erdtree.

What it runs against: a local clone of solidiquis/erdtree — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in solidiquis/erdtree | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 748 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of solidiquis/erdtree. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/solidiquis/erdtree.git
#   cd erdtree
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of solidiquis/erdtree and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "solidiquis/erdtree(\\.git)?\\b" \\
  && ok "origin remote is solidiquis/erdtree" \\
  || miss "origin remote is not solidiquis/erdtree (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/tree/mod.rs" \\
  && ok "src/tree/mod.rs" \\
  || miss "missing critical file: src/tree/mod.rs"
test -f "src/context/mod.rs" \\
  && ok "src/context/mod.rs" \\
  || miss "missing critical file: src/context/mod.rs"
test -f "src/render/mod.rs" \\
  && ok "src/render/mod.rs" \\
  || miss "missing critical file: src/render/mod.rs"
test -f "src/disk_usage/mod.rs" \\
  && ok "src/disk_usage/mod.rs" \\
  || miss "missing critical file: src/disk_usage/mod.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 748 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~718d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/solidiquis/erdtree"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

erdtree (erd) is a Rust-based filesystem traversal and disk-usage analyzer that combines features of du, tree, find, wc, and ls into a single cross-platform utility. It respects .gitignore and hidden file rules by default, supports multi-threaded traversal, and can report disk usage in multiple metrics (bytes, blocks, word-count, line-count) with colorized output using LS_COLORS. Single-binary Rust project with modular context-based architecture: src/context/ handles CLI args, colors, columns, sorting, and layout; src/disk_usage/ abstracts different size metrics (bytes, blocks, line_count); src/ansi.rs handles terminal output. Configuration loaded from .erdtree.toml or .erdtreerc files (src/context/config/toml/mod.rs and rc.rs) using the config crate.

Systems administrators and developers who need to understand disk usage patterns across large codebases or filesystems, particularly those working in Git repositories who want analysis that respects .gitignore rules without writing custom shell scripts.

Actively maintained and production-ready. Currently at v3.1.2 with Rust MSRV 1.70.0, has CI/CD pipelines (.github/workflows/ci.yml, test.yml, publish.yml), comprehensive documentation, and is distributed on crates.io. Last activity appears recent based on CHANGELOG.md and structured release process.

Low risk for stability: single primary maintainer (solidiquis) with small dependency footprint (ignore crate for gitignore support, clap for CLI, crossterm for terminal handling). No obvious breaking-change history in CHANGELOG.md. Primary risk is maintainer availability for security patches, though it's MIT-licensed so community forks are viable.

No specific PR or milestone data visible in provided file list, but repo maintains active workflow pipelines (test.yml, ci.yml, publish.yml) suggesting continuous integration practices. CHANGELOG.md exists indicating version tracking discipline. Project accepts contributions via CONTRIBUTING.md.

Clone the repo, ensure Rust 1.70.0+, and build: git clone https://github.com/solidiquis/erdtree.git && cd erdtree && cargo build --release. Binary will be at target/release/erd. Run tests with cargo test. Shell completions available via clap_complete integration.

Daily commands: For development: cargo build produces debug binary in target/debug/erd. For released build: cargo build --release. Binary runs as: erd [OPTIONS] [DIR] where DIR defaults to current directory. View options with erd --help. Shell completions generate via erd --generate <SHELL> (bash|zsh|fish|powershell supported by clap_complete).

• src/main.rs — Entry point orchestrating CLI argument parsing, context setup, and the main filesystem traversal loop; essential to understand how the application boots.
• src/tree/mod.rs — Core tree-building and traversal logic that respects .gitignore and hidden files; the heart of filesystem scanning.
• src/context/mod.rs — Central configuration context aggregating CLI args, color settings, and sorting rules; defines the state passed through the entire pipeline.
• src/render/mod.rs — Output rendering orchestrator that selects and applies layout strategies (tree, flat, inverted) and styling; bridges tree data to user display.
• src/disk_usage/mod.rs — Abstraction for multiple disk-usage metrics (bytes, blocks, line-count, word-count); critical for cross-metric reporting.
• src/fs/mod.rs — Filesystem abstraction wrapping file metadata, permissions, inodes, and xattr; provides normalized access to platform-specific details.
• Cargo.toml — Declares all dependencies and binary target; required reading to understand external libraries and minimum Rust version (1.70.0).

Add a new disk-usage metric

1. Define a new measurement type struct in src/disk_usage/file_size/ (e.g., new_metric.rs) implementing trait logic for computing size from a file (src/disk_usage/file_size/new_metric.rs)
2. Add the new variant to the FileSize enum in src/disk_usage/file_size/mod.rs (src/disk_usage/file_size/mod.rs)
3. Implement the dispatch match arm in src/disk_usage/mod.rs to handle the new metric during tree traversal (src/disk_usage/mod.rs)
4. Add CLI flag and config field in src/context/args.rs to allow users to select the new metric (src/context/args.rs)
5. Add unit formatting rules in src/disk_usage/units.rs if the metric requires special human-readable output (src/disk_usage/units.rs)

Add a new output layout

1. Create a new layout module in src/render/layout/ (e.g., custom_layout.rs) implementing the layout trait (src/render/layout/custom_layout.rs)
2. Add the new variant to the Layout enum in src/render/layout/mod.rs (src/render/layout/mod.rs)
3. Update the dispatcher in src/render/mod.rs to handle the new layout variant (src/render/mod.rs)
4. Add CLI option in src/context/args.rs to allow users to select the new layout (src/context/args.rs)
5. Test the layout with src/render/grid/ or src/render/long/ cell formatting utilities as needed (src/render/grid/cell.rs)

Add support for a new file attribute (e.g., selinux context)

1. Extend the filesystem node in src/fs/mod.rs to capture and store the new attribute (src/fs/mod.rs)
2. If Unix-specific, implement attribute extraction in src/tree/node/unix.rs (src/tree/node/unix.rs)
3. Add a new column type in src/context/column.rs to represent the attribute (src/context/column.rs)
4. Update long-form rendering in src/render/long/mod.rs to display the new column (src/render/long/mod.rs)
5. Add CLI flag in src/context/args.rs to control visibility of the new column (src/context/args.rs)

Add a new sorting criterion

1. Define the new sort variant in src/context/sort.rs enum or struct (src/context/sort.rs)
2. Implement the comparison logic in src/tree/node/cmp.rs or src/tree/node/mod.rs (src/tree/node/cmp.rs)
3. Add CLI flag parsing in src/context/args.rs to accept the new sort option (src/context/args.rs)
4. Ensure tree traversal in src/tree/mod.rs applies the sort criterion when building children (src/tree/mod.rs)

• Rust + Cargo — Provides memory safety, zero-cost abstractions, and cross-platform support without garbage collection

Terminal width detection via terminal_size crate can fail silently on some platforms; code must handle None gracefully. Unix-only features (blocks, file owners, permissions) use conditional compilation with #[cfg(unix)] and libc bindings—Windows builds will skip these. .gitignore respect depends on ignore crate's behavior, which respects global gitignore and .git/info/exclude. Config file precedence: .erdtreerc (legacy shell format) vs .erdtree.toml (newer); ensure tests cover both formats (see src/context/config/toml/test.rs). Multi-threaded traversal with crossterm output requires careful synchronization to avoid garbled ANSI codes.

• .gitignore-aware traversal — erdtree's core differentiator is respecting .gitignore rules without manual filtering; the ignore crate abstracts VCS rule parsing and must be understood to modify filtering behavior
• Multi-threaded filesystem traversal — erdtree handles large directory trees efficiently; understanding how Rust async/threading handles recursive directory walking prevents deadlocks and data races in custom traversal logic
• LS_COLORS environment variable parsing — erdtree respects system color preferences via lscolors crate; modifying output colors requires understanding how LS_COLORS format maps ANSI escape codes to file types
• Indextree arena allocation — erdtree uses indextree crate for filesystem tree representation; understanding arena-based allocation avoids memory-safety issues when building and traversing the tree structure
• Cross-platform terminal handling with crossterm — erdtree's output works on Windows, macOS, and Linux; crossterm abstracts platform differences for cursor control and ANSI escape support, critical for layout and color features
• Clap derive macros for CLI — erdtree's extensive CLI flags (--depth, --layout, --sort, --icons, etc.) are defined via clap's derive API in src/context/args.rs; understanding this pattern is essential for adding new flags
• [TOML configuration deserialization](https://toml.io/en/ and https://docs.rs/config/) — erdtree supports .erdtree.toml files deserialized via serde + config crate; modifying configuration handling requires understanding TOML schema mapping and serde derive attributes

• sharkdp/fd — Fast filesystem search tool mentioned in README comparisons; uses ignore crate like erdtree for .gitignore-aware filtering
• bootandy/dust — Alternative disk-usage analyzer mentioned in README comparisons; similar use case but different traversal approach
• Peltoche/lsd — Modern ls replacement in Rust; shares colorization (LS_COLORS support) and platform-conditional Unix/Windows bindings patterns
• BurntSushi/ripgrep — Rust CLI tool using ignore crate for .gitignore support; demonstrates idiomatic Rust filesystem filtering patterns
• ogham/exa — Alternative ls/tree tool mentioned in README comparisons; shares multi-column output and icon support goals

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for src/context/config/toml/mod.rs TOML parsing logic

The TOML configuration parsing module (src/context/config/toml/mod.rs) has a corresponding test file (src/context/config/toml/test.rs), but based on the complexity of configuration handling (supporting both .erdtree.toml and .erdtreerc files as shown in example/), there are likely missing edge cases. This PR would add tests for malformed TOML, missing required fields, type mismatches, and config merging scenarios to prevent regressions in user configurations.

• [ ] Review src/context/config/toml/mod.rs and src/context/config/toml/test.rs to identify untested code paths
• [ ] Add test cases for invalid TOML syntax, missing fields, type validation, and config inheritance
• [ ] Add integration tests in src/context/config/toml/test.rs that test realistic .erdtree.toml files from the example/ directory
• [ ] Run cargo test to ensure all tests pass

Add unit tests for src/fs/permissions/mod.rs permission parsing across Unix and Windows

The permissions module (src/fs/permissions/mod.rs) handles cross-platform file permissions and has a test file (src/fs/permissions/test.rs), but the current CI only runs on Linux/macOS/Windows without dedicated permission tests per platform. Adding comprehensive tests for edge cases like special bits (setuid, setgid, sticky), Windows ACLs, and permission denial scenarios would improve reliability of the --permissions feature.

• [ ] Review src/fs/permissions/mod.rs, class.rs, and file_type.rs to understand current permission handling
• [ ] Add tests for Unix special permission bits (setuid, setgid, sticky bit) in src/fs/permissions/test.rs
• [ ] Add Windows-specific tests for permission edge cases using cfg(windows) guards
• [ ] Add tests for permission parsing errors and edge cases in src/fs/permissions/error.rs
• [ ] Verify tests pass with cargo test --all

Add missing unit tests for src/disk_usage/file_size/mod.rs and its sub-modules

The disk usage file_size module has multiple sub-modules (block.rs, byte.rs, line_count.rs, word_count.rs) for calculating different metrics, but there's no visible test file in the structure. These metrics are core to erdtree's value proposition (as highlighted in README), so comprehensive tests for unit conversions, edge cases (zero bytes, empty files, huge files), and correct calculation across all metrics would prevent regressions and improve maintainability.

• [ ] Check if tests exist in src/disk_usage/file_size/ modules (block.rs, byte.rs, line_count.rs, word_count.rs)
• [ ] Create src/disk_usage/file_size/test.rs or add #[cfg(test)] modules to each file
• [ ] Add tests for unit conversions (bytes to KB/MB/GB), physical vs logical blocks, line/word counting accuracy
• [ ] Add edge case tests: zero-byte files, huge files, symlinks, sparse files
• [ ] Verify accuracy matches du/wc commands with cargo test

• Add integration tests for .erdtreerc parsing: src/context/config/rc.rs exists but no dedicated test file visible; add tests in src/context/config/ that validate .erdtreerc format parsing against example/.erdtreerc sample
• Expand disk-usage metrics: add percent-of-parent column: New metric type under src/disk_usage/file_size/ that shows each entry as % of parent directory; useful for relative size analysis; follow byte.rs pattern
• Document configuration file precedence and merge logic: Add section to README.md explaining when .erdtree.toml vs .erdtreerc is used, what happens if both exist, and how CLI args override config files; include example/.erdtreerc and example/.erdtree.toml in docs

The erdtree project demonstrates generally good security practices as a filesystem utility written in Rust. The codebase avoids common web vulnerabilities (SQL injection, XSS) and uses memory-safe Rust for most operations. Primary security concerns are: (1) outdated dependencies that should be audited for CVEs, (2) potential path traversal via configuration file parsing, (3) ReDoS risk from unvalidated regex patterns, and (4) platform-specific FFI code that requires careful validation. The project maintains a security policy and provides a responsible disclosure process. Recommended improvements include automated dependency scanning in CI/CD, enhanced input validation for configuration and command-line arguments, and comprehensive security testing for edge cases in path handling.

• Medium · Outdated Dependencies with Potential Vulnerabilities — Cargo.toml. Several dependencies are pinned to older versions that may contain known security vulnerabilities. Specifically: chrono 0.4.24 (released 2023), clap 4.1.1 (released 2023), and config 0.13.3 are significantly outdated. These dependencies should be reviewed against the CVE database for known issues. Fix: Run 'cargo audit' to identify known vulnerabilities. Update dependencies to latest patched versions: chrono >= 0.4.31, clap >= 4.4.x, and config >= 0.13.4. Implement automated dependency scanning in CI/CD pipeline.
• Low · Unix/Windows Platform-Specific Dependencies — Cargo.toml (libc 0.2.141, winapi 0.3.9). The codebase uses libc and winapi for platform-specific operations without visible abstraction or sandboxing. While legitimate for a filesystem utility, improper use of these low-level APIs could lead to privilege escalation or information disclosure vulnerabilities. Fix: Ensure all unsafe code blocks using libc/winapi are thoroughly audited and documented. Use the unsafe keyword appropriately and provide safety comments. Consider using higher-level abstractions where possible. Maintain an audit log of all FFI calls.
• Low · Potential Path Traversal via Configuration Files — src/context/config/toml/mod.rs, src/context/config/rc.rs. The application supports reading configuration from .erdtree.toml and .erdtreerc files (as seen in example/ directory). If user input from config files isn't properly validated, this could lead to path traversal vulnerabilities when processing filesystem paths. Fix: Implement strict path validation for all paths specified in configuration files. Use canonicalization and ensure paths are within intended directories. Add security tests for malicious path patterns (e.g., '../../../etc/passwd').
• Low · Regular Expression Denial of Service (ReDoS) Potential — src/context/args.rs, Cargo.toml (regex 1.7.3). The codebase uses the 'regex' crate (1.7.3) with user-supplied patterns based on file structure. Unvalidated regex patterns from command-line arguments or config files could cause ReDoS attacks. Fix: Implement regex pattern validation and complexity limits. Set timeouts on regex operations. Update regex to latest version (1.10.x). Document regex pattern constraints in user-facing documentation.
• Low · Insecure Temporary File Handling — Cargo.toml (tempfile 3.4.0). The dev-dependency 'tempfile' is used, but there's no visible evidence in the source that production code properly handles temporary files with secure permissions on Unix systems. Fix: If temporary files are used in production code, ensure they're created with mode 0600 (Unix) to prevent information leakage. Use tempfile crate's secure defaults and verify temporary directory location. Consider removing temporary files after use.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.