git-fzf

A fuzzy finder for Git. Browse local repositories, jump between worktrees, open directories, and manage stale branches — without leaving the terminal.

Requirements

• Bash 4.4+ (bash)
• fzf (fzf)
• Gum (gum)
• fd (fd) (required for repo command)

macOS (Homebrew):

brew install bash fzf gum fd

Nix:

nix profile install nixpkgs#bash nixpkgs#fzf nixpkgs#gum nixpkgs#fd

Installation

Nix (recommended)

Run directly without installing:

nix run github:git-extensions/git-fzf -- repo

Or install into your profile:

nix profile install github:git-extensions/git-fzf

Zsh Plugin

The plugin adds git-fzf to your $PATH so git discovers it as a custom command (git fzf).

Note: Bash 4.4+ is still required. On macOS: brew install bash.

zinit light git-extensions/git-fzf

Manual

Symlink the git-fzf script onto your $PATH so git discovers it as a custom command:

ln -s /path/to/git-extensions/git-fzf/git-fzf /usr/local/bin/git-fzf

Then use it as git fzf <command>.

Usage

git fzf [fzf-flags] <command>
git fzf --version
git fzf --help

Pass any fzf flags before the command — they are forwarded directly:

git fzf --tmux repo # open in a tmux popup
git fzf --tmux "80%,80%" repo # custom popup size
git fzf --height 50% repo # fixed height

Repositories

Browse local repositories under your configured projects directory. Selecting one and pressing Enter prints the path to stdout.

git fzf repo

Keybindings

Key	Action
ctrl-o	Open repository directory in file manager (open / xdg-open)
ctrl-r	Reload repository list
enter	Open repository in a new tmux session (requires tmux)
alt-enter	Open repository in a new tmux window (requires tmux)
alt-h	Toggle keyboard shortcut preview
ESC	Exit

Configuration

Set the root directory scanned by git fzf repo (default: ~/Projects):

# git config (persistent)
git config --global fzf.repoPath ~/Work
# Environment variable (takes precedence over git config)export GIT_FZF_REPO_PATH=~/Work

Worktrees

Browse all worktrees interactively. Selecting one and pressing Enter prints the path to stdout.

git fzf worktree

Keybindings

Key	Action
ctrl-o	Open worktree directory in file manager (open / xdg-open)
ctrl-r	Reload worktree list
alt-x	Remove selected worktree (git worktree remove)
alt-X	Force-remove selected worktree (git worktree remove -f)
alt-p	Prune stale worktrees (git worktree prune) + reload
enter	Open worktree in a new tmux session (requires tmux)
alt-enter	Open worktree in a new tmux window (requires tmux)
alt-h	Toggle keyboard shortcut preview
ESC	Exit

Configuration

fzf options

Override fzf options per command via environment variables:

Variable	Scope	Description
GIT_FZF_FLAGS	All commands	Set automatically from CLI fzf flags
GIT_FZF_REPO_OPTS	Repository only	Override any fzf option for repos
GIT_FZF_WORKTREE_OPTS	Worktree only	Override any fzf option for worktrees

Precedence: Defaults < GIT_FZF_FLAGS < GIT_FZF_<COMMAND>_OPTS

The format is the same as FZF_DEFAULT_OPTS: space-separated fzf options, with shell quoting for values that contain spaces or special characters.

# Simple flagsexport GIT_FZF_WORKTREE_OPTS="--height=90%"export GIT_FZF_WORKTREE_OPTS="--tmux=80%,80%"# Key bindings — quote the bind valueexport GIT_FZF_WORKTREE_OPTS="--bind 'alt-O:execute(code {})'"# Multiple optionsexport GIT_FZF_WORKTREE_OPTS="--height=90% --bind 'alt-O:execute(code {})'"

Development

A Nix dev shell provides all required tools (bash, git, fzf, gum, fd, bats, shellcheck):

nix develop

Run tests:

bats tests/

Run shellcheck:

shellcheck -x --source-path=SCRIPTDIR git-fzf scripts/*.sh

Enable debug trace:

DEBUG=1 git fzf repo
DEBUG=1 git fzf worktree

The git-extensions Ecosystem

Repo	What it provides
git-ai	AI-powered commit messages for git
git-fzf ← you are here	Fuzzy finder for git

License

MIT