Metadata-Version: 2.4
Name: structree
Version: 1.0.0
Summary: Directory tree generator — a simple CLI tool for visualising directory structures
Project-URL: Homepage, https://github.com/KaifKol/py-structree
Project-URL: Repository, https://github.com/KaifKol/py-structree
Project-URL: Bug Tracker, https://github.com/KaifKol/py-structree/issues
Author: KaifKol
License: MIT
License-File: LICENSE
Keywords: cli,directory-tree,filesystem,tree
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# structree

`structree` is a lightweight command-line utility written in Python that generates a visual directory tree, similar to the Unix `tree` command. The output can be saved to a file or printed directly to the console.

Works on **Windows**, **macOS**, and **Linux**.

---

## Features

- Generate a directory tree structure
- Ignore specific files or folders (comma-separated)
- Show **only files** or **only directories**
- Output to a file or directly to stdout
- Zero external dependencies — pure Python standard library

---

## Installation

### Via pip / uv (from PyPI)

```bash
pip install structree
# or
uv tool install structree
```

### From source

```bash
git clone https://github.com/KaifKol/py-structree.git
cd structree
uv tool install .
# or for development:
uv sync
```

---

## Usage

```bash
structree -p <path> [options]
```

If run **without any arguments**, the help message is displayed.

### Options

| Option               | Description                                                    |
| -------------------- | -------------------------------------------------------------- |
| `-p`, `--path`       | Target directory (`.` , relative, or full path) **(required)** |
| `-o`, `--out`        | Output file name (default: `tree.txt`)                         |
| `-i`, `--ignore`     | Comma-separated list of files/folders to ignore                |
| `-f`, `--files-only` | Show only files                                                |
| `-d`, `--dirs-only`  | Show only directories                                          |
| `-s`, `--stdout`     | Print output to console instead of writing to a file           |
| `--version`          | Show version number and exit                                   |

---

## Examples

### 1. Generate a tree for the current directory

```bash
structree -p .
```

Creates `tree.txt` inside the target directory.

### 2. Ignore folders like `.git` and `node_modules`

```bash
structree -p . -i .git,node_modules
```

### 3. Print the tree directly to the console

```bash
structree -p . -s
```

### 4. Show only files

```bash
structree -p . -f
```

### 5. Show only directories

```bash
structree -p . -d
```

### 6. Run as a Python module

```bash
python -m structree -p . -s
```

---

## Example Output

Assume the following directory structure:

```
project/
├── main.py
├── utils.py
├── README.md
└── src/
    ├── core.py
    └── helpers.py
```

Running:

```bash
structree -p project -s
```

Will output:

```
project/
├── README.md
├── main.py
├── utils.py
└── src
    ├── core.py
    └── helpers.py
```

---

## Development

```bash
# Clone and enter the project
git clone https://github.com/KaifKol/py-structree.git
cd structree

# Create a virtual environment and install dependencies
uv sync

# Run tests
uv run pytest

# Install as a CLI tool (global)
uv tool install .

# Run with uv (no install needed)
uv run structree -p . -s
```

---

## Publishing to PyPI

```bash
# Build the package
uv build

# Upload to PyPI
uv publish
```

---

## Notes

- The output uses Unicode box-drawing characters (`├──`, `└──`, `│`)
- Permission errors are silently skipped
- When writing to a file, it is created inside the target directory

---

## License

[MIT](LICENSE) © KaifKol
