119 lines
2.2 KiB
Markdown
119 lines
2.2 KiB
Markdown
# cd-browser
|
|
|
|
`cd-browser` is a terminal-native directory navigator for fast filesystem browsing from the command line.
|
|
|
|
It provides an interactive interface for exploring directories with the keyboard and returns the selected path at the end of the session so shell wrappers can change the current shell directory.
|
|
|
|
|
|
## Documentation
|
|
|
|
See the documentation index:
|
|
|
|
docs/index.md
|
|
|
|
## Features
|
|
|
|
- Interactive terminal directory browser
|
|
- Keyboard-driven navigation
|
|
- Parent directory entry via `..`
|
|
- Expand and collapse directory trees
|
|
- Session navigation history support in the application state
|
|
- Installable CLI command: `cd_browser`
|
|
|
|
## 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`.
|