file-system-tree-viewer 1.0.0

A CLI tool for generating a clear, hierarchical view of a file system.

🌳 File-System Tree Viewer

A lightweight command-line tool for generating a clear, hierarchical view of a file system — combining the familiarity of the Unix tree command with rich colorization, glob-pattern exclusions, directory depth control, and cross-platform flexibility.

📑 Table of Contents

• 🚀 Features
• 🧩 Installation
• 💻 Usage
• 🛠️ Options
• 🎨 Color Options
• 🪵 Example Output
• ⚖️ License
• 🧑🏻‍💻 Maintainer

🚀 Features

• 📂 Recursive tree output for viewing nested directories and files.
• 📏 Adjustable depth to limit how many directory levels are shown.
• 🚫 Pattern exclusion to hide items using glob patterns (*.pyc, venv).
• 🎨 Colorization support with named colors and 24-bit RGB.
• ✨ Bold tree branches for enhanced readability in the terminal.
• 📁 Directory-only mode to omit files from the view.
• 💾 File export support to save your tree as a .txt file.
• ✅ Cross-platform for Windows, macOS, and Linux.

🧩 Installation

Install via pip:

pip install file-system-tree-viewer

Or clone manually:

git clone https://github.com/RoyEshel/file-system-tree-viewer.git
cd file-system-tree-viewer
pip install .

💻 Usage

After installation, run the CLI command:

fs-tree [OPTIONS]

Example:

fs-tree --root-dir . --exclude "*.pyc" "node_modules" "*-env" --dir-color red --file-color 255,255,0 --output-path output/tree.txt

🛠️ Options

Option	Description	Default
--root-dir	Root directory from which the tree traversal begins	.
--depth	Maximum number of directory levels to show, including their contents (0 = show all levels)	0
--exclude	Space-separated list of glob patterns to exclude files or directories by name	None
--dirs-only	Show only directories	False
--indent	Number of spaces per indentation level	4
--bold	Use bold box-drawing characters for branches	False
--dir-color	Color for directory names	None
--file-color	Color for file names	None
--output-path	Directory or .txt file path for writing the tree output instead of printing to the terminal	None

🎨 Color Options

Directory and file names can be colorized using either:

• Named colors:
  black, red, green, yellow, blue, magenta, cyan, white

• RGB values in the form R,G,B (no quotes needed):
  Example: --file-color 255,128,0

Note:
Colorization is disabled automatically when writing output to a file.
Some terminals may not support 24-bit RGB sequences.

🪵 Example Output

project-root
├── src
│   ├── main.py
│   └── utils
│       └── helpers.py
├── tests
│   └── test_main.py
└── README.md

⚖️ License

This project is licensed under the GNU General Public License v3 or later.
See the LICENSE.txt file for details.

🧑🏻‍💻 Maintainer

Roy Eshel
🔗 GitHub: RoyEshel
📬 Preferably contact via GitHub Issues for questions, bug reports, or feature requests.