A lightweight command-line utility that displays directory tree structures while intelligently respecting .gitignore patterns. Perfect for documenting project structures, exploring codebases, and generating clean directory listings.

• Multiple Output Formats: Text (traditional), JSON (machine-readable), and Markdown (LLM-optimized)
• LLM-Optimized Mode: Special --llm flag for AI agent consumption with sensible defaults
• Gitignore-Aware: Automatically respects .gitignore files at all directory levels
• Hierarchical Patterns: Inherits and combines gitignore rules from parent directories
• Smart Sorting: Organizes output with directories first, then files, then dotfiles (all alphabetically sorted)
• Colorized Output: Beautiful ANSI colors for directories, files, and file types with auto-detection
• Depth Limiting: Control how deep to traverse with -L flag
• File Count Limiting: Limit total files displayed with --max-files flag
• Clean Output: Uses ASCII tree characters (├──, └──, │) for clear visual hierarchy
• Fast & Lightweight: Single binary with minimal dependencies
• Cross-Platform: Works on Linux, macOS, and Windows

go install github.com/datumbrain/dirtree@latest

git clone https://github.com/datumbrain/dirtree.git
cd dirtree
go build

Display the tree structure of the current directory:

dirtree

dirtree [options] [directory]

Options:
  -L int
        Maximum depth of directory tree (0 = unlimited)
  -level int
        Maximum depth of directory tree (0 = unlimited)
  -color string
        Colorize output: auto, always, never (default "auto")
  -format string
        Output format: text, json, markdown (or md) (default "text")
  -o string
        Output format: text, json, markdown (or md) (default "text")
  -max-files int
        Maximum number of files to display (0 = unlimited)
  -llm
        LLM-optimized output (equivalent to: --format markdown --level 3 --max-files 200)

Specify a directory:

dirtree /path/to/directory

Limit depth to 2 levels:

dirtree -L 2

Show only top-level items:

dirtree --level 1

Force colored output:

dirtree --color always

Disable colors:

dirtree --color never

Combine options:

dirtree --color always -L 3 /path/to/directory

Respect NO_COLOR environment variable:

NO_COLOR=1 dirtree

JSON output for programmatic use:

dirtree --format json
# or using the short flag
dirtree -o json

Markdown output for documentation:

dirtree --format markdown
# or using the alias
dirtree -o md

LLM-optimized mode (markdown, depth 3, max 200 files):

dirtree --llm

Limit number of files displayed:

dirtree --max-files 50

Combine format with other options:

dirtree --format json -L 2 --max-files 100

Without colors:

.
├── cmd
│   └── main.go
├── internal
│   ├── config.go
│   └── utils.go
├── pkg
│   └── api
│       └── handler.go
├── go.mod
├── go.sum
├── README.md
└── .gitignore

With colors (uses different colors for directories, files, and file types):

• Directories appear in blue and bold
• Regular files appear in white
• Dotfiles appear in gray
• Markdown/documentation files appear in cyan
• Image files appear in magenta
• Executable files appear in green and bold

dirtree supports three output formats to suit different use cases:

Traditional tree output with ASCII art. Perfect for terminal display and human reading.

dirtree --format text

Output:

.
├── cmd
│   └── main.go
├── pkg
│   └── api
│       └── handler.go
├── README.md
└── go.mod

Machine-readable format ideal for programmatic processing and integration with other tools.

dirtree --format json

Output:

{
  "root": ".",
  "depth": 0,
  "stats": {
    "files": 3,
    "dirs": 3
  },
  "nodes": [
    {"path": "cmd", "type": "dir"},
    {"path": "cmd/main.go", "type": "file"},
    {"path": "pkg", "type": "dir"},
    {"path": "pkg/api", "type": "dir"},
    {"path": "pkg/api/handler.go", "type": "file"},
    {"path": "README.md", "type": "file"},
    {"path": "go.mod", "type": "file"}
  ]
}

Optimized for documentation and LLM consumption. Groups files by directory with clear sections.

dirtree --format markdown

Output:

# Directory Structure: .

## Files
### Root Directory
- `README.md`
- `go.mod`

### cmd/
- `main.go`

### pkg/api/
- `handler.go`

## Directories
- `cmd/`
- `pkg/`
- `pkg/api/`

---
**Total:** 3 files, 3 directories

Special mode optimized for AI agents with sensible defaults:

dirtree --llm

This is equivalent to: --format markdown --level 3 --max-files 200

Benefits for LLM usage:

• Markdown format is easier for LLMs to parse
• Depth limit (3) prevents context overflow
• File limit (200) keeps output manageable
• Grouped structure helps with understanding project organization

dirtree reads .gitignore files at each directory level and respects all standard gitignore patterns:

• Wildcard patterns: *.log, *.tmp
• Directory patterns: node_modules/, build/
• Nested patterns: src/**/*.test.js
• Negation patterns: !important.log

Gitignore rules are inherited from parent directories, just like Git itself handles them.

The following are always excluded from the output:

• .git directory

Files and directories are sorted in the following order:

1. Directories (alphabetically)
2. Regular files (alphabetically)
3. Dotfiles (alphabetically)

This ensures consistent, readable output across different systems.

dirtree uses intelligent color coding to make output easier to scan:

• Directories: Blue and bold
• Regular files: White
• Dotfiles: Gray (dim)
• Executable files: Green and bold
• Image files (.png, .jpg, .gif, etc.): Magenta
• Documentation (.md, .txt, .pdf, etc.): Cyan

Color output respects:

• --color flag (auto, always, never)
• NO_COLOR environment variable (no-color.org)
• Terminal capabilities (auto-detection in auto mode)

Control traversal depth with the -L or --level flag:

dirtree -L 2    # Only show 2 levels deep

This is useful for:

• Getting a quick overview of large projects
• Focusing on top-level structure
• Avoiding deeply nested directories

• Documentation: Generate directory structure for README files (Markdown format) or documentation
• LLM Context: Feed project structure to AI assistants with --llm flag
• Code Review: Quickly understand project organization
• Project Planning: Visualize codebase structure before making changes
• Onboarding: Help new team members understand project layout
• Git-Aware Exploration: See only tracked/relevant files, ignoring build artifacts
• CI/CD Integration: Use JSON format for automated project analysis
• Build Tools: Parse JSON output for custom tooling and scripts

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

# Clone the repository
git clone https://github.com/datumbrain/dirtree.git
cd dirtree

# Run tests
go test -v ./...

# Build
go build

After installation, ensure your Go bin directory is in your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH=$PATH:$(go env GOPATH)/bin

If you encounter permission errors when reading directories, ensure you have read permissions for the target directory.

Make sure your .gitignore file:

• Is named exactly .gitignore (case-sensitive)
• Uses proper gitignore pattern syntax
• Is in the correct directory relative to the files you want to ignore

This project is licensed under the MIT License - see the LICENSE file for details.

• Fahad Siddiqui

• Uses go-gitignore for gitignore pattern matching
• Uses fatih/color for cross-platform colored output
• Inspired by the Unix tree command with Git-awareness added