🌳 ディレクトリ構造を簡単テキスト化！nodejs/cliツール「filetree」
✨ はじめに
開発プロジェクトを進めていると、「このプロジェクトのディレクトリ構造をドキュメントに載せたい」「チームメンバーに特定の範囲のファイル構成を伝えたい」といった場面がよくありますよね。そんなとき、手動でツリー構造を書き出すのは手間がかかりますし、ミスも起こりやすいものです 😥
今回ご紹介する @telosh/filetree は、そんな悩みを解決してくれる Node.js 向けの npm パッケージです。指定したディレクトリのファイルやフォルダの構造を、簡単に美しいツリー形式の文字列で出力してくれます！
📦 @telosh/filetree とは？
@telosh/filetree は、Node.js 環境で動作するコマンドラインツールやスクリプト内で、ディレクトリ構造を手軽にテキスト化するためのライブラリです。
開発にあたっては、他の言語で開発されている高機能なファイルツリージェネレーターに触発され、それらに見劣りしない十分な機能を目指しつつ、将来の様々なニーズにも応えられるよう拡張性を高く保つことを目標に、現在も開発を進めています。ぜひ、皆さんのアイデアやコントリビューションをお待ちしています！
主な特徴は以下の通りです。
- シンプルで直感的な API 呼び出し
- 出力する階層の深さ、無視するファイル/フォルダ、隠しファイルの表示/非表示など、柔軟なオプションによるカスタマイズ性
- ファイルサイズや最終更新日時などのメタデータ表示機能
-
.gitignoreファイルに記載されたファイルを自動的に除外する機能 - TypeScript フレンドリー (型定義同梱)
📥 インストール方法
npm を使用して、パッケージをグローバルにインストールします。
npm install -g @telosh/filetree
🛠️ 使い方
@telosh/filetree はコマンドラインから簡単に利用できます。
filetree [dirPath] [options]
-
dirPath: ツリー構造を表示するディレクトリのパス。デフォルトはカレントディレクトリ (.) です。
オプション
利用可能なオプションは以下の通りです。
| Option | Alias | Description | Default |
|---|---|---|---|
--level <depth> |
-L |
表示する階層の深さを指定します。 | Infinity |
--output <filepath> |
-o |
Markdown 形式でファイルに出力します。 | コンソールに出力 |
--exclude <dirs> |
-e |
除外するディレクトリ名をカンマ区切りで指定します。 | node_modules,.git |
--icons |
-i |
ファイルとディレクトリにアイコンを表示します。 | Off |
--metadata |
-m |
ファイルのメタデータ（サイズ、最終更新日時）を表示します。 | Off |
--size-only |
メタデータにファイルサイズのみを表示します（--metadata が必要）。 |
Off | |
--size-unit <unit> |
メタデータのサイズ単位を指定します (B, KB, MB, GB)。 | B |
|
--use-gitignore |
.gitignore に記載されたファイルやディレクトリを自動的に除外します。 |
Off | |
--version |
バージョン番号を表示します。 | ||
--help |
コマンドのヘルプを表示します。 |
特定のディレクトリを除外/含める (詳細)
デフォルトでは、node_modules や .git といったディレクトリは表示から除外されます。これらのディレクトリを意図的に含めたい場合や、除外リストをカスタマイズしたい場合は -e (または --exclude) オプションを使用します。
このオプションは、デフォルトの除外リスト (['node_modules', '.git']) を、あなたが指定した新しいリストで完全に置き換えます。
node_modules を含め、他に何も除外したくない場合:
コマンドラインで -e "" または --exclude "" を指定します。
filetree . -e ""
これにより、デフォルトの除外リスト（node_modules, .git）が無効になり、すべてのファイルとディレクトリが表示対象となります。例えば、通常は除外される node_modules や .git も表示されるようになります。
node_modules を含めつつ、特定の他のディレクトリ (例: dist) を除外したい場合:
コマンドラインで -e "dist" または --exclude "dist" を指定します。
filetree . -e "dist"
この場合、新しい除外リストは ['dist'] のみとなります。node_modules や .git はこの新しいリストに含まれていないため、表示されるようになります。
要するに、-e オプションで指定したディレクトリのリストが唯一の除外対象となります。何も指定しなければデフォルトの ['node_modules', '.git'] が使われますが、何かを指定するとデフォルト設定は無視されます。
この動作は現在のコード (src/tree-cli.ts) で正しく実装されているため、コードの変更は不要です。
使用例
現在のディレクトリのツリー構造を表示:
filetree
特定のディレクトリ (例: src) のツリー構造を表示:
filetree src
最大2階層までのツリー構造を表示:
filetree -L 2
node_modules と dist ディレクトリを除外:
filetree -e node_modules,dist
出力を Markdown ファイル (例: tree.md) に保存:
filetree -o tree.md
アイコン付きでツリー構造を表示:
filetree -i
メタデータ（サイズと最終更新日時）付きでツリー構造を表示:
filetree -m
ファイルサイズのみをKB単位で表示（メタデータオプション併用）:
filetree -m --size-only --size-unit KB
.gitignore の内容に基づいてファイルやディレクトリを除外して表示:
filetree --use-gitignore
💡 ユースケース
- プロジェクトの README にディレクトリ構造を記載する。
- コードレビュー時に、変更範囲のファイル構成を共有する。
- ドキュメント内で、特定の機能に関わるファイル群を視覚的に示す。
📜 ライセンス
このプロジェクトは MIT ライセンスです。詳細は LICENSE ファイルをご確認ください。
🙌 おわりに
@telosh/filetree を使えば、これまで手作業で行っていたディレクトリ構造のテキスト化が、コマンド一つで簡単に実現できます。ぜひ、日々の開発やドキュメンテーション作成にお役立てください！
フィードバックやコントリビューションも歓迎していますので、GitHub リポジトリもチェックしてみてくださいね。
Discussion