Skip to content

Commit a5180e0

Browse files
lumipallo-labslumipallo-labs
committed
Prepare v0.5.0 release
1 parent 282aaf2 commit a5180e0

3 files changed

Lines changed: 178 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Development Guidelines
2+
3+
Guidelines for contributing to DiskDive.
4+
5+
## Platform Support
6+
7+
All features must work on macOS 12+, Windows 10+, and modern Linux distributions. Use build tags (`_darwin.go`, `_windows.go`, `_other.go`) for platform-specific implementations.
8+
9+
## Architecture
10+
11+
```
12+
internal/
13+
core/ # Pure business logic - no UI dependencies
14+
controller.go # Main application controller
15+
state.go # State types (ScanState, FreedState)
16+
events.go # Event types for UI communication
17+
18+
ui/tui/ # Terminal UI (Bubble Tea + Lipgloss)
19+
app.go # Main TUI application
20+
tree.go # Tree panel component
21+
treemap.go # Treemap visualization
22+
styles.go # Colors and styles
23+
24+
scanner/ # Filesystem scanning
25+
model/ # Data structures (Node, Drive)
26+
watcher/ # Filesystem change monitoring
27+
stats/ # Usage statistics persistence
28+
```
29+
30+
The `core` package contains all business logic and can be used by alternative frontends (GUI, web, etc.).
31+
32+
## Code Quality
33+
34+
### Principles
35+
36+
- **Keep it simple.** Write the minimum code that solves the problem.
37+
- **No duplication.** Extract shared logic into functions. DRY.
38+
- **Single responsibility.** Each file/struct/function has one clear purpose.
39+
- **Readable over clever.** Clarity beats brevity.
40+
- **Fix root causes.** Don't add workarounds that mask bugs.
41+
42+
### Go Conventions
43+
44+
- Use existing solutions before writing custom code (stdlib, lipgloss, bubbletea)
45+
- Prefer specific parameters over passing entire structs
46+
- Use pointer receivers for methods that modify state
47+
- Value receivers for read-only methods
48+
49+
### TUI Guidelines
50+
51+
- Use lipgloss for all styling and layout
52+
- Use `lipgloss.Width()` for measuring rendered text width
53+
- Use `lipgloss.Place()`/`JoinHorizontal()`/`JoinVertical()` for layout
54+
- Only use `strings.Repeat()` for visual elements (progress bars), not layout spacing
55+
56+
### Treemap Rules
57+
58+
- All blocks must be large enough to show a label (minimum 8×3 characters)
59+
- The "N more items" block must always be visible when items are grouped
60+
- Show as many items as possible while maintaining readability
61+
62+
## Development
63+
64+
### Building
65+
66+
```bash
67+
go build .
68+
go test ./...
69+
```
70+
71+
### Running
72+
73+
```bash
74+
# Scan current directory
75+
go run . ./
76+
77+
# Scan specific path
78+
go run . /path/to/scan
79+
80+
# With debug logging
81+
DEBUG=1 go run . ./
82+
```
83+
84+
### Testing Changes
85+
86+
After making changes, verify:
87+
1. `go build .` succeeds
88+
2. `go test ./...` passes
89+
3. Manual testing with both small directories and full drives

‎README.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# DiskDive
2+
3+
A fast, terminal-based disk space analyzer with treemap visualization.
4+
5+
![DiskDive Screenshot](https://placeholder-for-screenshot.png)
6+
7+
## Features
8+
9+
- **Fast parallel scanning** - Scans large drives quickly using concurrent workers
10+
- **Treemap visualization** - See disk usage at a glance with proportional blocks
11+
- **Real-time deletion tracking** - Monitors filesystem and shows freed space
12+
- **Cross-platform** - Works on macOS, Windows, and Linux
13+
- **Vim-style navigation** - Navigate with arrow keys or hjkl
14+
15+
## Installation
16+
17+
```bash
18+
go install github.com/samuli/diskdive@latest
19+
```
20+
21+
Or clone and build:
22+
23+
```bash
24+
git clone https://github.com/samuli/diskdive.git
25+
cd diskdive
26+
go build .
27+
```
28+
29+
## Usage
30+
31+
```bash
32+
# Scan a drive (interactive drive selector)
33+
diskdive
34+
35+
# Scan a specific directory
36+
diskdive /path/to/directory
37+
```
38+
39+
### macOS
40+
41+
**From Finder:** Double-click `DiskDive.app` - opens in Terminal automatically.
42+
43+
**From Terminal:** The binary is inside the app bundle:
44+
```bash
45+
# Run directly
46+
/Applications/DiskDive.app/Contents/MacOS/diskdive
47+
48+
# Or create a symlink for convenience
49+
ln -s /Applications/DiskDive.app/Contents/MacOS/diskdive /usr/local/bin/diskdive
50+
```
51+
52+
### Keyboard Controls
53+
54+
#### Navigation
55+
| Key | Action |
56+
|-----|--------|
57+
| `↑↓←→` or `hjkl` | Navigate |
58+
| `PgUp/PgDn` | Scroll faster |
59+
| `g/G` | Jump to top/bottom |
60+
| `Tab` | Switch between tree and treemap panels |
61+
62+
#### Actions
63+
| Key | Action |
64+
|-----|--------|
65+
| `Enter` | Expand/zoom into directory |
66+
| `Esc` or `Backspace` | Go back / collapse |
67+
| `Space` | Preview file (Quick Look on macOS) |
68+
| `e` | Select different drive |
69+
| `o` | Open in file manager |
70+
| `r` | Rescan current drive |
71+
72+
#### Other
73+
| Key | Action |
74+
|-----|--------|
75+
| `?` | Show help |
76+
| `q` | Quit |
77+
78+
## Requirements
79+
80+
- macOS 12+ / Windows 10+ / Linux
81+
82+
## License
83+
84+
Apache License 2.0. See [LICENSE](LICENSE) for details.
85+
86+
## Development
87+
88+
See [DEVELOPMENT.md](DEVELOPMENT.md) for build instructions, architecture overview, and contribution guidelines.

‎VERSION‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
0.5.0

0 commit comments

Comments
 (0)