file-system-tree-viewer 1.0.0
A CLI tool for generating a clear, hierarchical view of a file system.
Requires Python: >=3.9
Keywords: cli, file-tree, tree-view, filesystem, directory-visualization, file-explorer, devtools

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoyEshel/file-system-tree-viewer/main/assets/logo-dark-mode.png">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/RoyEshel/file-system-tree-viewer/main/assets/logo-light-mode.png">
    <img src="https://raw.githubusercontent.com/RoyEshel/file-system-tree-viewer/main/assets/logo-light-mode.png" alt="File-System Tree Viewer Logo" width=175 style="width: 175px; max-width: 80%">
  </picture>
</p>

<h1 align="center">🌳 File-System Tree Viewer</h1>

<p align="center">
  <a href="https://pypi.org/project/file-system-tree-viewer/">
    <img src="https://img.shields.io/pypi/v/file-system-tree-viewer.svg" alt="PyPI Version">
  </a>
  <a href="https://pypi.org/project/file-system-tree-viewer/">
    <img src="https://img.shields.io/pypi/pyversions/file-system-tree-viewer.svg" alt="Python Versions">
  </a>
  <a href="https://github.com/RoyEshel/file-system-tree-viewer/blob/main/LICENSE.txt">
    <img src="https://img.shields.io/github/license/RoyEshel/file-system-tree-viewer" alt="License">
  </a>
</p>

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.**

<details>
  <summary><strong>📑 Table of Contents</strong></summary>

  - [🚀 Features](#features)
  - [🧩 Installation](#installation)
  - [💻 Usage](#usage)
  - [🛠️ Options](#options)
  - [🎨 Color Options](#color-options)
  - [🪵 Example Output](#example-output)
  - [⚖️ License](#license)
  - [🧑🏻‍💻 Maintainer](#maintainer)

</details>


<a id="features"></a>

## 🚀 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.


<a id="installation"></a>

## 🧩 Installation

Install via **pip**:

```bash
pip install file-system-tree-viewer
```

Or clone manually:

```bash
git clone https://github.com/RoyEshel/file-system-tree-viewer.git
cd file-system-tree-viewer
pip install .
```


<a id="usage"></a>

## 💻 Usage

After installation, run the CLI command:

```bash
fs-tree [OPTIONS]
```

Example:

```bash
fs-tree --root-dir . --exclude "*.pyc" "node_modules" "*-env" --dir-color red --file-color 255,255,0 --output-path output/tree.txt
```


<a id="options"></a>

## 🛠️ 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` |


<a id="color-options"></a>

## 🎨 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.


<a id="example-output"></a>

## 🪵 Example Output

```
project-root
├── src
│   ├── main.py
│   └── utils
│       └── helpers.py
├── tests
│   └── test_main.py
└── README.md
```


<a id="license"></a>

## ⚖️ License

This project is licensed under the **GNU General Public License v3 or later**.  
See the [LICENSE.txt](LICENSE.txt) file for details.


<a id="maintainer"></a>

## 🧑🏻‍💻 Maintainer

**Roy Eshel**  
🔗 [GitHub: RoyEshel](https://github.com/RoyEshel)  
📬 Preferably contact via [GitHub Issues](https://github.com/RoyEshel/file-system-tree-viewer/issues) for questions, bug reports, or feature requests.