trxd 25.10.0

A modern Python command-line tool for listing directory contents with advanced filtering and metadata support

ls-tree

A modern Python command-line tool for listing directory contents with advanced filtering and metadata support. Similar to tree but with more features and better performance.

Features

• Multiple output formats: Tree (with emojis), ASCII tree, flat list, JSON, and YAML
• Advanced filtering: Exclude files and directories using glob patterns
• Metadata support: File sizes, modification dates, and directory statistics
• Memory efficient: Uses generators for large directory structures
• Cross-platform: Works on Windows, macOS, and Linux
• Modern Python: Built with pathlib and type hints

Installation

Using pip

pip install ls-tree

From source

git clone https://github.com/your-username/ls-tree.git
cd ls-tree
pip install -e .

Using uv (recommended)

uv add ls-tree

Usage

Basic usage

# List current directory in tree format
ls-tree

# List specific directory
ls-tree /path/to/directory

# List with emoji icons (default)
ls-tree --format tree

# List with ASCII characters (no emojis)
ls-tree --format tree --no-emoji

# List with ASCII format (same as --no-emoji)
ls-tree --format ascii

Output formats

# Tree format with emojis (default)
ls-tree --format tree

# Tree format with ASCII characters
ls-tree --format ascii

# Flat list format
ls-tree --format flat

# JSON format
ls-tree --format json

# YAML format
ls-tree --format yaml

Filtering options

# Exclude files and directories
ls-tree --exclude "*.pyc" --exclude "__pycache__"

# Exclude only directories
ls-tree --exclude-dir "node_modules" --exclude-dir ".git"

# Exclude only files
ls-tree --exclude-file "*.log" --exclude-file "*.tmp"

# Multiple exclusions
ls-tree -x "*.pyc" -x "*.pyo" -xd "__pycache__" -xd ".git"

Metadata support

# Show file sizes and modification dates
ls-tree --show-metadata

# Combine with different formats
ls-tree --format flat --show-metadata
ls-tree --format json --show-metadata

Examples

Basic directory listing

$ ls-tree src/
📁 src/
├── 📁 components/
│   ├── 🐍 Button.py
│   └── 🐍 Header.py
├── 📁 utils/
│   └── 🐍 helpers.py
└── 🐍 main.py

Tree format without emojis

$ ls-tree --format tree --no-emoji src/
[d] src/
├── [d] components/
│   ├── [f] Button.py
│   └── [f] Header.py
├── [d] utils/
│   └── [f] helpers.py
└── [f] main.py

ASCII tree format

$ ls-tree --format ascii src/
[d] src/
├── [d] components/
│   ├── [f] Button.py
│   └── [f] Header.py
├── [d] utils/
│   └── [f] helpers.py
└── [f] main.py

Tree format with metadata

$ ls-tree --format tree --show-metadata src/
📁 src/ [4 files, 2.1 KB]
├── 📁 components/ [2 files, 922 B]
│   ├── 🐍 Button.py [450 B, 2024-01-15 14:25]
│   └── 🐍 Header.py [472 B, 2024-01-15 14:20]
├── 📁 utils/ [1 file, 800 B]
│   └── 🐍 helpers.py [800 B, 2024-01-15 14:15]
└── 🐍 main.py [1.2 KB, 2024-01-15 14:30]

Mixed file types with emojis

$ ls-tree project/
📁 project/
├── 📁 src/
│   ├── 🐍 main.py
│   ├── 🌐 index.html
│   ├── 🎨 styles.css
│   └── 📜 app.js
├── 📁 docs/
│   ├── 📝 README.md
│   └── 📄 manual.pdf
├── 📋 config.json
├── 🔐 .env
└── 🐳 Dockerfile

Flat format (simple)

$ ls-tree --format flat src/
src
src/main.py
src/components
src/components/Button.py
src/components/Header.py
src/utils
src/utils/helpers.py

Flat format with metadata

$ ls-tree --format flat --show-metadata src/
src [4 files, 2.1 KB]
src/main.py [1.2 KB, 2024-01-15 14:30]
src/components [2 files, 922 B]
src/components/Button.py [450 B, 2024-01-15 14:25]
src/components/Header.py [472 B, 2024-01-15 14:20]
src/utils [1 file, 800 B]
src/utils/helpers.py [800 B, 2024-01-15 14:15]

JSON output (simple)

$ ls-tree --format json src/
{
  "src": {
    "main.py": null,
    "components": {
      "Button.py": null,
      "Header.py": null
    },
    "utils": {
      "helpers.py": null
    }
  }
}

JSON output with metadata

$ ls-tree --format json --show-metadata
{
  "_metadata": {
    "file_count": 4,
    "total_size": 2156,
    "modified": "2024-01-15T14:30:00"
  },
  "src": {
    "type": "directory",
    "file_count": 4,
    "total_size": 2156,
    "modified": "2024-01-15T14:30:00",
    "contents": {
      "main.py": {
        "type": "file",
        "size": 1234,
        "modified": "2024-01-15T14:30:00"
      },
      "components": {
        "type": "directory",
        "file_count": 2,
        "total_size": 922,
        "modified": "2024-01-15T14:25:00",
        "contents": {
          "Button.py": {
            "type": "file",
            "size": 450,
            "modified": "2024-01-15T14:25:00"
          },
          "Header.py": {
            "type": "file",
            "size": 472,
            "modified": "2024-01-15T14:20:00"
          }
        }
      },
      "utils": {
        "type": "directory",
        "file_count": 1,
        "total_size": 800,
        "modified": "2024-01-15T14:15:00",
        "contents": {
          "helpers.py": {
            "type": "file",
            "size": 800,
            "modified": "2024-01-15T14:15:00"
          }
        }
      }
    }
  }
}

YAML output (simple)

$ ls-tree --format yaml src/
src:
  main.py: null
  components:
    Button.py: null
    Header.py: null
  utils:
    helpers.py: null

YAML output with metadata

$ ls-tree --format yaml --show-metadata src/
_metadata:
  file_count: 4
  total_size: 2156
  modified: '2024-01-15T14:30:00'
src:
  type: directory
  file_count: 4
  total_size: 2156
  modified: '2024-01-15T14:30:00'
  contents:
    main.py:
      type: file
      size: 1234
      modified: '2024-01-15T14:30:00'
    components:
      type: directory
      file_count: 2
      total_size: 922
      modified: '2024-01-15T14:25:00'
      contents:
        Button.py:
          type: file
          size: 450
          modified: '2024-01-15T14:25:00'
        Header.py:
          type: file
          size: 472
          modified: '2024-01-15T14:20:00'
    utils:
      type: directory
      file_count: 1
      total_size: 800
      modified: '2024-01-15T14:15:00'
      contents:
        helpers.py:
          type: file
          size: 800
          modified: '2024-01-15T14:15:00'

ASCII format with metadata

$ ls-tree --format ascii --show-metadata src/
[d] src/ [4 files, 2.1 KB]
├── [d] components/ [2 files, 922 B]
│   ├── [f] Button.py [450 B, 2024-01-15 14:25]
│   └── [f] Header.py [472 B, 2024-01-15 14:20]
├── [d] utils/ [1 file, 800 B]
│   └── [f] helpers.py [800 B, 2024-01-15 14:15]
└── [f] main.py [1.2 KB, 2024-01-15 14:30]

Filtering examples

# Exclude Python cache files
$ ls-tree --exclude "*.pyc" --exclude "__pycache__"

# Exclude common build directories
$ ls-tree --exclude-dir "node_modules" --exclude-dir ".git" --exclude-dir "dist"

# Show only source files
$ ls-tree --exclude-file "*.log" --exclude-file "*.tmp" --show-metadata

# Complex filtering example
$ ls-tree --exclude-dir "node_modules" --exclude-dir ".git" --exclude "*.pyc" --exclude "*.pyo" --show-metadata

Real-world usage examples

# List a Python project structure
$ ls-tree --exclude-dir "__pycache__" --exclude-dir ".git" --exclude "*.pyc" --format tree

# Get directory size information
$ ls-tree --show-metadata --format flat | grep "\[.*files"

# Export project structure for documentation
$ ls-tree --format yaml --exclude-dir ".git" --exclude-dir "node_modules" > project-structure.yaml

# Generate JSON for API consumption
$ ls-tree --format json --show-metadata --exclude-dir ".git" > directory-info.json

# Quick file listing without directories
$ ls-tree --format flat --exclude-dir "*" src/

Integration examples

# Use with other tools
$ ls-tree --format flat | grep "\.py$" | wc -l  # Count Python files
$ ls-tree --show-metadata --format json | jq '.src.contents | keys'  # Get directory contents with jq

# Generate reports
$ ls-tree --show-metadata --format json | jq '[.src.contents | to_entries[] | select(.value.type == "file") | {name: .key, size: .value.size}]'

Command-line options

positional arguments:
  path                  Directory path to list (default: current directory)

options:
  -h, --help            Show help message and exit
  --format {tree,ascii,json,yaml,flat}
                        Output format (default: tree)
  -x, --exclude EXCLUDE
                        Pattern to exclude (files and directories)
  -xd, --exclude-dir EXCLUDE_DIR
                        Pattern to exclude (directories only)
  -xf, --exclude-file EXCLUDE_FILE
                        Pattern to exclude (files only)
  -m, --show-metadata   Show metadata (size, modification date)
  --no-emoji           Disable emojis in tree format (use ASCII characters)

Performance

• Memory efficient: Uses generators to process large directory structures without loading everything into memory
• Fast filtering: Uses pathlib's efficient pattern matching
• Lazy evaluation: Metadata is only collected when requested

Requirements

• Python 3.8+
• PyYAML (for YAML output)

Development

Setup development environment

git clone https://github.com/your-username/ls-tree.git
cd ls-tree
uv sync --dev

Run tests

uv run pytest

Run linting

uv run ruff check .
uv run ruff format .

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Changelog

v1.0.0

• Initial release
• Basic tree listing functionality
• Multiple output formats (tree, ascii, flat, json, yaml)
• Advanced filtering options
• Metadata support (file sizes, modification dates)
• Memory-efficient generator-based processing