144 lines
2.6 KiB
Markdown
144 lines
2.6 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.
|
|
|
|
|
|
|
|
## 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
|
|
|
|
- 🚀 Fast visual navigation of directory trees
|
|
- ⌨️ Fully keyboard-driven workflow
|
|
- 🌲 Expand and collapse directories
|
|
- 📜 Navigation history inside the session
|
|
- 🖥 Native terminal interface
|
|
- 🔁 Works with Bash, Zsh and other shells
|
|
- ⚡ Returns the selected path to the shell
|
|
|
|
## 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 .
|
|
```
|
|
|
|
For editable local development:
|
|
|
|
```bash
|
|
pip install -e '.[dev]'
|
|
```
|
|
|
|
After installation, the application command is:
|
|
|
|
```bash
|
|
cd_browser
|
|
```
|
|
|
|
When the interactive session exits, the program prints the final selected directory path.
|
|
|
|
## 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_
|
|
```
|
|
|
|
## Uninstall
|
|
|
|
If the project was installed with `pip`, remove it with:
|
|
|
|
```bash
|
|
pip uninstall cd-browser
|
|
```
|
|
|
|
If you also added the `cd_` shell wrapper, remove that function from your shell profile and reload the shell configuration.
|
|
|
|
## 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`.
|