Metadata-Version: 2.4
Name: dirgo
Version: 1.2.1
Summary: Fast, interactive terminal disk usage analyzer (TUI) for macOS, Linux and Windows
Author: Mohsin Kaleem
License-Expression: MIT
Project-URL: Homepage, https://github.com/mohsinkaleem/dirgo
Project-URL: Repository, https://github.com/mohsinkaleem/dirgo
Project-URL: Issues, https://github.com/mohsinkaleem/dirgo/issues
Project-URL: Documentation, https://mohsinkaleem.github.io/dirgo/
Project-URL: Changelog, https://github.com/mohsinkaleem/dirgo/releases
Keywords: terminal,directory,disk-usage,disk-space,du,ncdu,cli,tui,file-manager
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Other
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# dirgo

[![CI](https://github.com/mohsinkaleem/dirgo/actions/workflows/ci.yml/badge.svg)](https://github.com/mohsinkaleem/dirgo/actions/workflows/ci.yml)
[![Release](https://github.com/mohsinkaleem/dirgo/actions/workflows/release.yml/badge.svg)](https://github.com/mohsinkaleem/dirgo/actions/workflows/release.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/mohsinkaleem/dirgo/blob/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/dirgo)](https://pypi.org/project/dirgo/)

A fast, minimal and interactive terminal disk usage analyzer built with Go and [Bubble Tea](https://github.com/charmbracelet/bubbletea). Visualize disk usage, explore directories and files, and find what's eating your disk space — all from your terminal, on macOS, Linux, and Windows.

![dirgo screenshot](https://raw.githubusercontent.com/mohsinkaleem/dirgo/main/.github/dirgo-view.png)

## Features

- **Instant directory listing** — files appear immediately; directory sizes compute in the background
- **Proportional size bars** — color-coded percentage bars for quick visual scanning
- **Efficient directory scanning** — uses `os.ReadDir` + manual recursion to minimize syscalls; parallel stat with bounded concurrency
- **Smart refresh** — checks directory modtime before rescanning; skips unchanged directories
- **LRU cache** — bounded in-memory cache (100 entries) for instant back-navigation within a session
- **Line counting** — automatic line count for the selected text file; batch count all with `s`
- **Hex view** — built-in hex dump for binary files (`xxd` on macOS, `hexdump` fallback on Linux)
- **Large file protection** — prevents accidentally opening very large blob files
- **Fuzzy search** — filter entries in real time with subsequence matching
- **Symlink detection** — symlinks shown with `→` / `⇢` indicators
- **Move to trash** — safely delete files/directories with `d`
- **Cross-platform** — works on macOS, Linux, and Windows (Quick Look, file open, trash, and hex view adapt per OS)
- **CPU profiling** — built-in `--profile` flag for performance analysis

## How it compares

dirgo is in the same family as [ncdu](https://dev.yorhel.nl/ncdu), [gdu](https://github.com/dundee/gdu), and [dust](https://github.com/bootandy/dust). The differences:

- **No up-front scan.** ncdu and gdu scan the whole tree before you can browse; dirgo lists the current directory immediately and fills in sizes as they're computed. dust prints a one-shot report rather than an interactive view.
- **File-level tools, not just sizes.** Line counts, hex view, Quick Look / open, and move to trash are one key away, so you can inspect and clean up without leaving the browser.
- **Installs everywhere.** One static binary via Homebrew, pip/uv, `go install`, or the release archives.

## Install

### Homebrew (macOS / Linux)

```bash
brew install mohsinkaleem/tap/dirgo
```

### pip / uv (any platform)

```bash
pip install dirgo
```

```bash
uv tool install dirgo
```

### Go install

```bash
go install github.com/mohsinkaleem/dirgo@latest
```

### From source

```bash
git clone https://github.com/mohsinkaleem/dirgo.git
cd dirgo
make build
```

## Usage

```bash
# Analyze current directory
dirgo

# Analyze a specific path
dirgo ~/Documents

# Print version
dirgo --version

# Enable CPU profiling
dirgo --profile /path/to/dir
```

## Keybindings

| Key | Action |
|---|---|
| `↑` / `k` | Move cursor up |
| `↓` / `j` | Move cursor down |
| `←` / `Backspace` | Go to parent directory |
| `→` / `l` / `Enter` | Open selected directory / file |
| `Space` | Quick Look preview (macOS `qlmanage`, Linux `xdg-open`, Windows `explorer`) |
| `g` | Jump to top |
| `G` | Jump to bottom |
| `PgUp` / `Ctrl+U` | Page up |
| `PgDn` / `Ctrl+D` | Page down |
| `r` | Smart refresh (skips if unchanged) |
| `t` | Toggle top 10 view |
| `o` | Open in Finder / file manager |
| `/` | Search / filter |
| `Esc` | Clear search filter / exit top 10 / close help |
| `h` | Toggle hidden files |
| `f` | Cycle filter (all → dirs only → files only) |
| `s` | Count lines for all files |
| `c` | cd to path |
| `x` | Hex view (binary files) |
| `d` | Move to trash |
| `?` | Help |
| `q` / `Ctrl+C` | Quit |

## Architecture

For a full walkthrough of the design — component breakdown, message flow, the scanning pipeline, and a deep dive on the concurrency model — see the [architecture guide](https://mohsinkaleem.github.io/dirgo/architecture.html).

Prefer to learn by doing? The [interactive tour](https://mohsinkaleem.github.io/dirgo/explore.html) lets you drive a working replica of the TUI in your browser, step through the message loop one frame at a time, and run the concurrent scanner with adjustable core counts.

```
main.go        Entry point, --profile/--version flags, Bubble Tea program setup
model.go       Application state, Update loop, message handling
scanner.go     Directory scanning with os.ReadDir + manual recursion, bounded concurrency
cache.go       Bounded in-memory LRU cache with eviction
entry.go       FileEntry data model, sorting, filtering, fuzzy match
render.go      Row rendering, header/footer, help overlay
keys.go        Key bindings
styles.go      Lipgloss color and style definitions (pre-defined bar color styles)
utils.go       Formatting, line counting (bytes.Count + sync.Pool), helpers
```

### Scanning Pipeline

1. `scanDirectory()` calls `os.ReadDir` to read the directory in a single syscall, immediately stats files, and separates directories from files.
2. Directory sizes are computed in parallel using `dirSizeRecursive()` — a manual recursive function using `os.ReadDir` that avoids the overhead of `filepath.WalkDir`. Bounded concurrency is enforced via a semaphore (CPU count, max 16).
3. File stat is parallelised for directories with 20+ files to leverage multi-core CPUs.

### Caching

- **In-memory**: LRU cache holding up to 100 directory scan results. Accessed on navigation; updated on scan completion.
- **On-disk**: Not implemented as of now. Wanted to keep it simple and deterministic.

### Smart Refresh

Pressing `r` compares the directory's current modtime against the cached value. If unchanged, the rescan is skipped entirely (~microseconds). If changed, a full rescan is triggered.

## Development

```bash
# Run tests
make test

# Run benchmarks
make bench

# CPU profile a benchmark
make profile-cpu

# Memory profile
make profile-mem

# Build cross-platform release binaries
make release
```

## Requirements

- Go 1.25+ (only needed to build from source or `go install`)
- macOS / Linux / Windows

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](https://github.com/mohsinkaleem/dirgo/blob/main/CONTRIBUTING.md) for the development setup, and please follow the [code of conduct](https://github.com/mohsinkaleem/dirgo/blob/main/CODE_OF_CONDUCT.md). To report a security issue, see [SECURITY.md](https://github.com/mohsinkaleem/dirgo/blob/main/SECURITY.md).

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

## License

[MIT](https://github.com/mohsinkaleem/dirgo/blob/main/LICENSE)
