printree – 超軽量ディレクトリツリー & Git差分ビューア

Table of Contents

• 概要
• インストール
• 使い方
  • ツリー出力
  • Git差分モード
• 開発・テスト
• リリースフロー
• パフォーマンスとアーキテクチャ
• 既知の注意
• ライセンス

概要

• DFS による逐次ストリーム出力で巨大ツリーでも低メモリ。

• メタデータは各エントリにつき1回だけ取得し、サイズや更新時刻をキャッシュ。

• plain/json/ndjson/csv/yaml/html など複数フォーマットへ同一パイプラインから出力。

• glob/regex/type/size/mtime/perm など柔軟なフィルタを組み合わせてディレクトリを絞り込み。

• Git ステータスとリネーム検出をオプションで表示、差分モードも搭載。

• --jobs で並列メタデータ収集、--warn-depth で深すぎるツリーを警告。

• Windows ACL 属性の整形表示とルート外へ抜けるシンボリックリンクの遮断で安全性を確保。

インストール

cargo install --path .
printree --help

使い方

ツリー出力

printree [OPTIONS] [PATH]

Note	PATH を省略するとカレントディレクトリを対象にします。オプションは前後どちらに配置しても構いません。

主なオプション:

オプション	説明
--max-depth <N>	探索の最大深さ。1 はルートのみ。
--hidden	ドットファイルも表示。
--follow-symlinks	シンボリックリンクを辿る（ルート外へ抜けるリンクは遮断）。
--sort name|none	名前順ソート。--dirs-first と組み合わせ可。
--include/--exclude <PATTERN>	パターンで絞り込み。複数指定可。
--pattern-syntax glob|regex	include/exclude の構文を選択。
--match-mode name|path	パターンをファイル名/パスのどちらに適用するか。
--filter-regex <REGEX>	正規表現で追加フィルタリング。
--filter-size <COND>	>1MB, ⇐10k, ==0 などのサイズ条件。
--filter-mtime <WINDOW>	3d, 10m, 2h といった更新時刻ウィンドウ。
--filter-perm <OCTAL>	UNIX パーミッション（例 755）。Windows では警告のみ。
--type file|dir|symlink	表示する種類を限定（複数指定で合成）。
--gitignore on|off	.gitignore を適用するか。off が既定。
--git-status	Git の変更状態を表示。
--git-rename	Git リネーム検出を有効化（コスト増。--git-status を暗黙有効化）。
--color auto|always|never	カラー出力の制御。
--format plain|json|ndjson|csv|yaml|html|toon	出力形式。plain/ndjson/csv は逐次書き出し。
--encoding utf8|utf8bom|utf16le|sjis|auto	文字エンコーディング。
--jobs <N>	メタデータ取得を N 並列で実行。1 でシングルスレッド。
--warn-depth <N>	深さが N を超えたら STDERR に警告（0 で無効）。

Note	すべてのフィルタは AND 条件です。正規表現や数値条件が無効な場合は起動時にエラー終了します。

出力フォーマット

• plain: 罫線付きツリー。ディレクトリは子のサイズを集計して表示し、Git ステータスを色付きで表現。

• json: 全ノードを JSON 配列として出力。

• ndjson: 1 行 1 エントリの JSON。ストリーム処理向き。

• csv: path,name,kind,size,mtime などの列を CSV で逐次出力。

• yaml: 完全なネスト構造を保持。全エントリを一旦収集してから出力。

• html: JSON を埋め込んだ単一 HTML ドキュメントを生成。

• toon: TOON(Token-Oriented Object Notation) 互換の表形式。entries[<len>]{path,…​}: のヘッダで列名を一度だけ宣言し、各行をカンマ区切りで出力してトークン数を圧縮。

例:

root:.
entries[3]{path,depth,kind,size,mtime,perm,symlink_target,loop_detected,error,git_status}:
.,0,dir,-,-,-,-,0,-,-
src,1,dir,-,-,-,-,0,-,-
src/main.rs,2,file,120,-,rw-r--r--,-,0,-,-

Git 連携

• .git が見つからない場合は --git-status/--git-rename を自動的に無効化し、警告のみ表示。

• ステータスは [M], [A], [D], [R] を用い、plain では色付きで表示。

• リネーム検出を有効にすると [warn] rename detection enabled (slow) が STDERR に出力されます。

並列化と安全性

• --jobs でメタデータ取得を Rayon プールに委譲。--jobs 0 やマイナス値はエラーになります。

• 深すぎるツリーを巡回する際は --warn-depth に達すると一度だけ警告を表示。

• ルートディレクトリの正規化パスを保持し、ルート外へ抜けるシンボリックリンクは遮断して loop_detected/[security] を出力。

• Windows では windows-sys を使用し、隠し属性や読み取り専用などの ACL 情報を整形表示します。

Git差分モード

printree diff --rev-a <HASH|REF> --rev-b <HASH|REF> [--path SUBDIR] [--format plain|json]

• 2 リビジョン間のファイル追加/削除/変更をツリー形式で表示。

• --include/--exclude や --pattern-syntax はツリー表示と同じく利用可能。

• 出力形式は plain または json。その他のフォーマットを指定するとエラーになります。

開発・テスト

• cargo test でユニットテストを実行します。

• CLI の挙動確認は tests/run_all.sh を使うと、リリースビルドを一度だけ生成して smoke/diff/tree スクリプトをまとめて実行できます。

./tests/run_all.sh

リリースフロー

• main ブランチに Cargo.toml を含む変更をプッシュすると Build, Package & Release printree ワークフローが走り、未作成なら v<version> タグを打ったうえで GitHub Release に成果物をアップロードします。

• 配布物は dist/ に集約され、tar.gz/zip/deb/rpm/exe といった配布専用ファイルのみをアップロード対象にして README や Cargo.toml を単独で再投稿しないようにしています。アーカイブ内には README.adoc と LICENSE のみを同梱し、余計なソースメタデータは含めません。

パフォーマンスとアーキテクチャ

• 逐次 DFS で探索順序は安定化済みソート後に固定。

• 各エントリのメタデータは 1 回だけ取得してキャッシュし、再利用します。

• フォーマッタは共通の Entry 表現を受け取り、必要な情報のみをシリアライズ。

既知の注意

• .gitignore モードでは厳密な罫線位置が通常モードと異なる場合があります（インデントは保証）。

• Windows の --filter-perm は属性体系の差異により警告のみで無効です。

ライセンス

MIT