treex

Git-aware directory tree utility

Command-line directory tree utility with metadata and Git ignore support.

• Development: GitHub
• Releases: PyPI
• License: MIT
• Copyright: © 2026 Corey Goldberg

About

treex recursively scans a directory and displays its contents as a tree, including file and directory metadata. It respects .gitignore rules inside Git repositories and provides additional options for filtering and customizing the output.

Features

• Respects .gitignore rules inside Git repositories
• Displays human-readable file sizes
• Displays recursive directory sizes
• Displays line counts for text files
• Identifies binary and unreadable files by type
• Optionally displays modification timestamps
• Optionally includes or excludes paths using glob patterns
• Optionally includes or excludes paths using regular expressions
• Optionally limits the depth of the displayed tree

Status

Latest Version
Tests
Supported Python Versions

Requirements

• Python 3.13+
• UTF-8-compatible terminal

Installation

Install treex from PyPI using your preferred Python package manager:

• pip: pip install treex-cli
• pipx: pipx install treex-cli
• uv: uv tool install treex-cli

Prebuilt wheels are available for common platforms. See Platform Support for details.

Git ignore support

treex uses Gitoxide (gix), a native Rust implementation of Git functionality, to evaluate .gitignore rules without invoking the Git executable. Git does not need to be installed for ignore matching to work.

When the specified directory is inside a Git working tree, treex respects applicable .gitignore rules by default. Outside a Git working tree, Git ignore filtering is disabled. Use --all to include files ignored by Git.

Usage

usage: treex [-h] [-V] [-a] [-m] [-q] [-d] [-s] [-i PATTERN] [-e PATTERN]
             [-I PATTERN] [-E PATTERN] [-D DEPTH]
             [directory]

List directory contents as a tree with file and directory metadata.

positional arguments:
  directory                    directory to scan (default: current directory)

options:
  -h, --help                   show this help message and exit
  -V, --version                show version information and exit
  -a, --all                    show all files, including those ignored by Git
  -m, --modified               show file modification times
  -q, --quiet                  don't show file metadata
  -d, --dirs                   show directories only
  -s, --summary                show summary only
  -i, --include PATTERN        include paths matching a glob pattern
  -e, --exclude PATTERN        exclude paths matching a glob pattern
  -I, --include-regex PATTERN  include paths matching a regular expression
  -E, --exclude-regex PATTERN  exclude paths matching a regular expression
  -D, --depth DEPTH            limit levels displayed below starting directory

Filtering paths

Use --include and --exclude to filter paths by glob pattern:

treex --include '*.py'
treex --exclude 'tests/*.py'
treex --include '*.py' --exclude 'test_*.py'

Use --include-regex and --exclude-regex to filter paths by regular expression:

treex --include-regex '^src/'
treex --exclude-regex '(^|/)tests/'
treex --include-regex '\.py$' --exclude-regex '(^|/)test_[^/]*\.py$'

Patterns match paths relative to the starting directory, using forward slashes as separators. Matching is case-sensitive. Glob patterns use * to match any characters, including directory separators. Regular expressions use Python's regex syntax. Exclusions take precedence over inclusions.

Note: quote glob and regex patterns to prevent the shell from interpreting them before treex receives them.

Screenshot

Platform support

Prebuilt wheels are available for Python 3.13+ on the following platforms:

These prebuilt binary wheels let you install the treex-cli package without compiling the Rust extension yourself.

Installing on other platforms

If a prebuilt binary is not available for your platform, you can install the package from the source distribution on PyPI or directly from the source repository. This requires a Rust toolchain.

For more information about installing Rust, see the official Rust installation guide