KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

fzf-navigator

★ 94 Open GitHub ↗

fzf-navigator is an interactive file system navigator that uses fzf.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# fzf-navigator

`fzf-navigator` is an interactive file system navigator that uses [fzf](https://github.com/junegunn/fzf). It provides a speedy alternative to `cd` + `ls` with previews, toggles, history navigation and contextual command-line insertion.

![](https://raw.githubusercontent.com/benward2301/fzf-navigator/main/fzf-navigator.gif)

## Installation

Download `fzf-navigator.sh` and source it in your shell rc file.

Example:

```bash
curl -o ~/.config/fzf-navigator.sh https://raw.githubusercontent.com/benward2301/fzf-navigator/main/fzf-navigator.sh
echo 'source ~/.config/fzf-navigator.sh' >> ~/.${SHELL##*/}rc
```

### Dependencies

- [fzf](https://github.com/junegunn/fzf) ≥ 0.45.0
- [eza](https://github.com/eza-community/eza) - Optional (required for icons), falls back to `ls`
- [bat](https://github.com/sharkdp/bat) - Optional (required for colorized file previews), falls back to `cat`

## Usage

Press `ctrl-space` to open the navigator.

### Bindings

| Key | Action | Description |
|-----|--------|-------------|
| `space` | `open` | Enter directory / edit file |
| `ctrl-o` | `open_and_exit` | Enter directory / edit file and exit navigator |
| `ctrl-space` | `exit` | Exit navigator (and `cd` to current directory if locked) |
| `enter` | `insert_selection` | Insert path(s) at cursor |
| `ctrl-y` | `copy_selection` | Copy path(s) to clipboard |
| `esc` | `cancel` | Exit, or reset path if locked |
| `ctrl-d` | `go_to_parent` | Go to parent directory |
| `ctrl-alt-o` | `go_back` | Go back in history |
| `ctrl-alt-i` | `go_forward` | Go forward in history |
| `[` | `go_to_session_start` | Go to session starting directory |
| `\` | `go_home` | Go to home directory |
| `/` | `go_to_root` | Go to root directory |
| `ctrl-l` | `toggle_locked` | Toggle locked mode (navigation doesn't change shell CWD) |
| `alt-h` | `toggle_hidden_files` | Toggle hidden files |
| `alt-i` | `toggle_ignored_files` | Toggle git-ignored files (`eza` only) |
| `ctrl-g` | `toggle_file_details` | Toggle file details (`-l`) |
| `ctrl-r` | `toggle_recent_first` | Toggle recent-first sort |
| `alt-r` | `reload` | Reload the current directory listing |
| `?` | `toggle_help` | Toggle help |

## Configuration

| Variable | Description |
|----------|-------------|
| `FZF_NAVIGATOR_KEY` | Keybinding to launch navigator |
| `FZF_NAVIGATOR_SHOW_HIDDEN` | Show hidden files by default if set |
| `FZF_NAVIGATOR_SHOW_IGNORED` | Show git-ignored files by default if set (`eza` only) |
| `FZF_NAVIGATOR_LOCK_CWD` | Start in locked mode if set (navigation doesn't change shell CWD) |
| `FZF_NAVIGATOR_HIDE_HELP` | Hide the "? for help" hint if set |
| `FZF_NAVIGATOR_LS_FORMAT` | Comma-separated: `icons`, `color`, `classify`, or `plain` (default: `icons,color`) |
| `FZF_NAVIGATOR_BINDINGS` | Custom keybindings: `"key:action,key:action,..."` |
| `FZF_NAVIGATOR_OPTS` | Additional `fzf` options |
| `FZF_NAVIGATOR_FILE_PREVIEW_COMMAND` | Custom file preview command (receives path as `$1`) |
| `FZF_NAVIGATOR_DIR_PREVIEW_COMMAND` | Custom directory preview command (receives path as `$1`) |

## Truecolor icons

When using `eza`, you can enable truecolor file icons (if your terminal supports it) by copying [theme.yml](theme.yml) to your eza config directory:

```bash
curl -o "${EZA_CONFIG_DIR:-$HOME/.config/eza}/theme.yml" https://raw.githubusercontent.com/benward2301/fzf-navigator/main/theme.yml
```

![](https://raw.githubusercontent.com/benward2301/fzf-navigator/main/fzf-navigator-truecolor.png)

## Compatibility

- **Shells**: `zsh`, `bash` ≥ 5.0
- **Platforms**: Linux, macOS
- **ls variants**: `eza`, GNU/BSD `ls`

fzf-navigator

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README