dirwalker — parallel directory scanner

Parallel, depth-aware directory walker. Used as a library and as a standalone CLI binary by pvdu for Kubernetes PVC usage scanning.

Development

The repository includes a Makefile for common build and verification tasks:

make build       # Build bin/dirwalker
make test        # Run the Go test suite
make test-race   # Run tests with the race detector
make vet         # Run go vet
make check       # Run formatting, tests, race tests, and vet
make mutation    # Run mutation checks for core source files
make install     # Install the CLI with go install
make clean       # Remove build artifacts

Install

go install github.com/NeutryFD/dirwalker/cmd/dirwalker@latest

CLI

dirwalker [path] [flags]
dirwalker /mnt/data -d 3 -w 8 --files --output=table

Flag	Short	Description	Default
--max-depth	-d	Max depth (0 = unlimited)	0
--exclude	-e	Comma-separated paths to exclude	""
--workers	-w	Parallel workers (0 = auto)	0
--files	-f	Report individual file sizes	false
--human		Include formatted human-readable sizes in machine output	false
--output	-o	Output format: table, json, yaml, json-lines	json-lines

Output formats

dirwalker /data -o table     # human-readable table
dirwalker /data -o json      # JSON object with total + entries
dirwalker /data -o yaml      # YAML output
dirwalker /data              # JSON Lines (streaming, default)

Invalid flags, multiple positional paths, and unsupported output formats are usage errors and exit with status 2. Scan failures exit with status 1.

JSON and YAML use the same stable snake_case field names (total_size, total_str, entries, path, size, is_dir, and human). Machine output (JSON, YAML, and JSON Lines) omits the formatted human fields by default; pass --human to include them. Table output stays human-readable regardless of the flag. JSON Lines records are deterministic and always end with one done record.

Library

import "github.com/NeutryFD/dirwalker"

total, err := dirwalker.ScanDirectory("/path", 0, nil, nil, 4, false)

• ScanDirectory(root, maxDepth, excludes, progress, workers, reportFiles) — scans a directory tree in parallel
• Negative maxDepth values and integer-size overflow return errors. Traversal read failures also fail the scan instead of producing an incomplete total.
• Symlinks are never followed. They are reported as zero-size non-directory events only when reportFiles is true.
• ProgressFn func(path string, size int64, isDir bool) — called for each directory/file
• FormatBytes(b int64) string — "1.5 GiB", "500 B"
• FormatBytesShort(b int64) string — "1.5Gi", "500 B"
• RenderTable(summary ScanSummary) string — table output
• RenderJSON(summary ScanSummary) string — JSON output
• RenderYAML(summary ScanSummary) string — YAML output