233 lines
6.1 KiB
Markdown
233 lines
6.1 KiB
Markdown
# cd-browser
|
|
|
|
**Stop typing paths. Browse them.**
|
|
|
|
`cd-browser` is a fast keyboard-driven directory navigator for the terminal.
|
|
It lets you explore directory trees visually and jump to any folder instantly.
|
|
|
|
|
|
|
|
Repository (full demo + docs): https://gitea.sakydogalo.es/saky/cd-browser
|
|
|
|
## Why cd-browser?
|
|
|
|
Working in the terminal often means:
|
|
|
|
- typing long directory paths
|
|
- navigating deep folder trees
|
|
- repeating `cd ..` multiple times
|
|
|
|
`cd-browser` provides an **interactive terminal UI** that allows you to browse directories with the keyboard and return the selected path directly to your shell.
|
|
|
|
## Features
|
|
|
|
- ⌨️ Fully keyboard-driven workflow (`↑` / `↓` / `←` / `→`)
|
|
- 🌲 Expand and collapse directories (`→` to expand/enter, `←` to collapse/back)
|
|
- 📜 Persistent history between sessions (`h` history mode, `b` back, `f` forward)
|
|
- 🔎 Incremental filter mode (`/`, type to filter, `Backspace`, `Esc`)
|
|
- 🧭 History filter mode (`/` inside history) with most-recent-first ordering
|
|
- 📄 Toggle file visibility (`a`) to switch between directories-only and mixed view
|
|
- ⚡ Fast jumps in large lists (`PgUp`/`PgDn`, `Home`/`End`, `g`/`G` in normal mode)
|
|
- 🚀 Contextual `open with` menu (`o`) with app detection based on your environment
|
|
- 🔁 Blocking terminal editors restore the UI state when they exit (`nvim`, `nano`, `less`, `bat`)
|
|
- 🧩 Configurable app menu via `config.toml` with automatic template creation
|
|
- 🛠 Development snapshot in header + detailed info panel (`i`)
|
|
- 👀 Toggle hidden entries with `.`
|
|
- 🖥 Native terminal interface
|
|
- 🔁 Works with Bash, Zsh and other shells
|
|
- ⚡ Returns the selected path to the shell (`Enter` to confirm, `Esc` to cancel)
|
|
|
|
## Controls
|
|
|
|
Normal mode:
|
|
|
|
- `↑` / `↓`: Move selection
|
|
- `→`: Expand directory, or enter when already expanded
|
|
- `←`: Collapse directory, or go to parent
|
|
- `Enter`: Confirm selected path and exit
|
|
- `Esc`: Cancel and return the original path
|
|
- `h`: Toggle history mode
|
|
- `b` / `f`: Back / forward in navigation history
|
|
- `.`: Toggle hidden entries
|
|
- `a`: Toggle file visibility
|
|
- `/`: Enter filter mode
|
|
- `o`: Open selected entry with an app
|
|
- `i`: Toggle development info panel
|
|
- `PgUp` / `PgDn`: Page jump
|
|
- `Home` / `End`: Jump to first/last entry
|
|
- `g` / `G`: Jump to first/last entry
|
|
|
|
Filter mode:
|
|
|
|
- Type text: Filter visible entries in real time (case-insensitive)
|
|
- `↑` / `↓`: Move inside filtered results
|
|
- `Enter`: Apply filter and perform contextual action:
|
|
- Directory: navigate into it without exiting `cd_`
|
|
- File: open app selection menu
|
|
- `Esc`: Exit filter mode and clear query
|
|
- `Backspace`: Remove last filter character
|
|
|
|
History mode:
|
|
|
|
- `↑` / `↓`: Move through history entries (most recent at top)
|
|
- `Enter`: Jump to selected history path
|
|
- `Esc` or `h`: Exit history mode
|
|
- `PgUp` / `PgDn`, `Home` / `End`: Fast history navigation
|
|
- `/`: Enter history filter mode
|
|
|
|
History filter mode:
|
|
|
|
- Type text: Filter history entries in real time (case-insensitive)
|
|
- `↑` / `↓`: Move inside filtered history results
|
|
- `Enter`: Jump to selected history path
|
|
- `Esc`: Exit history filter mode and clear query
|
|
- `Backspace`: Remove last filter character
|
|
|
|
Open with menu (`o`):
|
|
|
|
- `↑` / `↓`: Move between app options
|
|
- `Enter`: Launch selected app
|
|
- `Esc`: Cancel
|
|
|
|
The menu only shows apps available in your system (`PATH`) and context:
|
|
|
|
- GUI options (when GUI is available): `code`, system `open`/`xdg-open`
|
|
- Terminal options: `antigravity`, `opencode`, `nvim`, `nano`, `less`, `bat` (as applicable)
|
|
|
|
## Opener Configuration
|
|
|
|
`cd-browser` reads opener settings from:
|
|
|
|
- macOS/Linux: `~/.config/cd-browser/config.toml`
|
|
- Windows: `%APPDATA%/cd-browser/config.toml`
|
|
|
|
If the file does not exist, `cd-browser` creates it automatically with defaults.
|
|
|
|
Example:
|
|
|
|
```toml
|
|
[open_with]
|
|
files = ["code", "open", "antigravity", "nvim", "nano", "less", "bat"]
|
|
directories = ["code", "opencode", "antigravity", "nvim"]
|
|
```
|
|
|
|
You can reorder or remove entries to customize app priority.
|
|
|
|
## Quick Demo
|
|
|
|
Run:
|
|
|
|
```bash
|
|
cd_
|
|
```
|
|
|
|
Browse directories using the arrow keys and press **Enter** to jump directly to the selected folder.
|
|
|
|
## Documentation
|
|
|
|
See the documentation index:
|
|
|
|
```
|
|
docs/index.md
|
|
```
|
|
|
|
## Installation
|
|
|
|
Install the project in user mode:
|
|
|
|
```bash
|
|
pip install cd-browser
|
|
```
|
|
|
|
**Important**: After installation, run this to set up the `cd_` command:
|
|
|
|
```bash
|
|
cd_browser_post_install
|
|
```
|
|
|
|
This interactive script will guide you through enabling `cd_` in your shell.
|
|
|
|
## Shell Integration For `cd_`
|
|
|
|
Because a Python subprocess cannot directly change the parent shell directory, use a shell wrapper that captures the final path printed by `cd_browser`.
|
|
|
|
Bash or Zsh example:
|
|
|
|
```bash
|
|
cd_() {
|
|
local target
|
|
target="$(cd_browser)" || return
|
|
|
|
if [ -n "$target" ] && [ -d "$target" ]; then
|
|
cd "$target"
|
|
fi
|
|
}
|
|
```
|
|
|
|
After adding the function to your shell profile, reload it:
|
|
|
|
```bash
|
|
source ~/.bashrc
|
|
```
|
|
|
|
Or:
|
|
|
|
```bash
|
|
source ~/.zshrc
|
|
```
|
|
|
|
Then use:
|
|
|
|
```bash
|
|
cd_
|
|
```
|
|
|
|
- Inside `cd_browser`, press `.` to toggle hidden entries.
|
|
|
|
## Platform Compatibility
|
|
|
|
Practical conclusion:
|
|
|
|
- Best current support: **macOS and Linux**
|
|
- **Windows is partially supported**, but still needs real-world validation in Windows terminal environments before being considered fully supported
|
|
|
|
## Uninstall
|
|
|
|
If the project was installed with `pip`, remove it with:
|
|
|
|
```bash
|
|
pip uninstall cd-browser
|
|
```
|
|
|
|
**Important**: After uninstalling, remove the `cd_()` function from your shell profile (~/.bashrc or ~/.zshrc) to clean up completely.
|
|
|
|
## Developer Setup
|
|
|
|
Recommended setup:
|
|
|
|
```bash
|
|
make dev
|
|
```
|
|
|
|
Run the application in development mode:
|
|
|
|
```bash
|
|
python -m app.main
|
|
```
|
|
|
|
Useful development commands:
|
|
|
|
```bash
|
|
make fix
|
|
make quality
|
|
make run
|
|
```
|
|
|
|
## Template Origin
|
|
|
|
This project was created from the Python AI Dev Template.
|
|
|
|
The original template documentation has been preserved in `README_TEMPLATE.md` so the project-specific README can focus on `cd-browser` usage and development.
|
|
|
|
For the original template setup, conventions, and generic workflow notes, see `README_TEMPLATE.md`.
|