bigH/git-fuzzy: an fzf-driven CLI for git add, branch, log and diff

Who git-fuzzy is for, and the git ergonomics it replaces

Plain git asks you to remember hashes, paths and flags before you can look at anything. git-fuzzy inverts that: you run a menu, type a substring, and the listing filters as you type in the usual fzf style. The README frames the project as "a CLI interface to git that relies heavily on fzf", and that framing is accurate. The audience is people who already use fzf for file and history selection and want the same interaction for staging, resetting and committing. Three behaviours matter most. In status you can stage or reset by selecting or cursoring, and commit interactively. In diff you can search the diff from the query bar while the right-hand diff highlights the match. In log, a pipe character splits the query: the left side is sent to log, the right side to diff, so one query searches both the commit list and the patch. That pipe convention is the one piece of syntax you have to learn, and the README does not offer an alternative spelling for it.

The sub-commands and how a query reaches git

Every menu entry has a CLI equivalent, so `git fuzzy <command>` is the real interface and the menu is a convenience layer. The README lists status, branch, log, show, reflog, stash, diff and pr. Several commands forward extra arguments to the underlying git invocation: `git fuzzy diff a b -- XYZ` uses the supplied arguments in both the listing and the preview. Whenever git output appears in a listing or preview, git-fuzzy prints a header with the command it ran, which is useful for copy-pasting or for understanding what happened; the README says debugging switches can reveal other background commands and how commands are routed. `git fuzzy show <commit> [-- <pathspec>...]` browses the files changed by one commit, and the README notes that root commits and merge commits are shown with `git show --first-parent`. That is a deliberate simplification: you see the first-parent side of a merge, not the full combined diff.

Installing git-fuzzy and running the first menu

fzf is required, at version 0.71.0 or higher, and the README's install instruction is a Homebrew line:

brew install fzf

There is no package-manager install for git-fuzzy itself. You clone the repository and put its bin directory on your PATH. The Bash recipe appends an export to ~/.bashrc:

git clone https://github.com/bigH/git-fuzzy.git

# add the executable to your path
echo "export PATH=\"$(pwd)/git-fuzzy/bin:\$PATH\"" >> ~/.bashrc

Zsh users append the same line to ~/.zshrc, and the Fish recipe writes a set -x PATH line into ~/.config/fish/config.fish. Plugin managers are also documented: antibody bundle bigH/git-fuzzy path:bin kind:path, znap install bigH/git-fuzzy, zplug with as:command and use:"bin/git-fuzzy", and zinit with as"program" pick"bin/git-fuzzy". After the PATH line is sourced, running `git fuzzy` opens the menu and you can pick status, branch, log, reflog, stash, diff or pr. If nothing happens, the first thing to check is that fzf resolves on the same PATH.

Environment variables, and the quoting trap underneath them

Configuration is entirely environment variables, and several of them are documented as subject to string splitting, which means you must quote them adequately or the value will be torn apart by the shell. GF_PREFERRED_PAGER decorates diffs; if it is unset, diff-so-fancy is tried, then delta, then raw diffs. The README's example carries a __WIDTH__ placeholder:

export GF_PREFERRED_PAGER="delta --theme=gruvbox --highlight-removed -w __WIDTH__"

GF_GREP_COLOR changes the highlight used by `git fuzzy diff`, for example GF_GREP_COLOR='1;30;48;5;15'. GF_BAT_STYLE and GF_BAT_THEME adjust bat for git-fuzzy only, while BAT_STYLE and BAT_THEME apply to every bat instance. GF_DIFF_SEARCH_DEFAULTS changes patch search in diff, show and single-commit show; the default is -G, and the README's example swaps in --pickaxe-regex -S. GF_LOG_MENU_PARAMS and GF_REFLOG_MENU_PARAMS override the pretty formats, defaulting to --pretty=oneline --abbrev-commit. GF_BASE_REMOTE and GF_BASE_BRANCH set the merge-base remote and branch, and the README states the default is origin/main. GF_BRANCH_SKIP_REMOTE_BRANCHES hides remote branches from the branch menu, and any non-empty value works, including the string no. That last detail is a genuine footgun: a value you would read as false turns the feature off.

The remote HEAD footgun and the base-branch default

git-fuzzy assumes origin/main as the merge-base. In a repository that renamed its default branch after your initial clone, that assumption breaks, and the README flags it as a FOOTGUN. The prescribed fix is `git remote set-head <remote name> <branch name>`, and you can inspect the current value with `git symbolic-ref -q "refs/remotes/<remote name>/HEAD"`. This is the least forgiving part of the tool for anyone working across many repositories with mixed main and master conventions, because the failure is not a crash: you get a listing built against the wrong base. If you prefer a different upstream entirely, GF_BASE_REMOTE and GF_BASE_BRANCH move the base without touching the repository, which is the cleaner fix when you routinely work from a fork. Neither variable is documented as having a per-repository override, so the setting is effectively per-shell.

Optional tools that change what you actually see

git-fuzzy works without any of the optional tools, but the README is explicit that they are part of the ideal experience. delta or diff-so-fancy improves diff rendering, bat is a colorized alternative to cat, eza is a git-enabled alternative to ls, and fswatch on macOS or inotifywait on Linux auto-reloads `git fuzzy status` when files change. That last one is the most interesting: without a watcher the status view is a snapshot, and the README does not describe a manual refresh key. The dependency chain is also implicit rather than enforced. If delta is installed but you dislike its output, GF_PREFERRED_PAGER is the override, and it is tried before diff-so-fancy and delta, so the variable is the only reliable way to pin a specific renderer. Nothing here is bundled; each tool is resolved from PATH, which means two machines with the same git-fuzzy checkout can behave differently.

Where git-fuzzy is the wrong tool, and what to use instead

The hard requirement is fzf 0.71.0 or higher, and the entire interface is a shell script that shells out to git. That rules it out for anyone who needs a graphical client, and it makes it a poor fit on Windows unless your environment provides fzf and a POSIX shell. The README documents Bash, Zsh and Fish setups only. The project is also a wrapper, not a git reimplementation: anything git cannot express, git-fuzzy cannot express either. If your need is reviewing pull requests, `git fuzzy pr` opens and diffs GitHub pull requests, but the README does not describe GitLab, Bitbucket or other forges. A real alternative in a different shape is lazygit, a terminal UI with its own rendering and its own keybindings rather than fzf menus layered over git output. The difference is architectural: lazygit owns the screen and defines the interaction, while git-fuzzy delegates filtering to fzf and printing to git, which is why its output is copy-pasteable commands and its configuration is environment variables. If you want a self-contained binary with a fixed keymap, lazygit is the closer match; if you want fzf's query syntax and git's own formatting flags, git-fuzzy is the closer match.

Maintenance, licence and what upgrading costs you

The repository is not archived, and the last push was on 2026-06-19. There are no retrieved releases, which fits the shape of the project: installation is a clone, so there is no version to pin and no changelog to read. Upgrades mean pulling the branch and re-sourcing your shell, or letting your plugin manager do it. The cost of that is real, because the interface is environment variables and the README warns repeatedly that several of them are subject to string splitting; a pull that changes how a variable is parsed can break a working configuration silently. The licence is MIT, which permits use, modification and redistribution provided the copyright notice and permission notice are included. That is a statement about the licence text, not legal advice for your situation. Because bin/ and lib/ are shell, you can read the routing yourself before trusting it, and the README points at debugging switches for exactly that purpose.

Editorial conclusion

Adopt git-fuzzy if you already live in fzf and want staging, branch checkout, log search and diff browsing without leaving the terminal; the install is a clone plus one PATH line, and the whole thing is shell you can read. Skip it if your team needs a GUI, a Windows-native toolchain, or anything that works without fzf on the PATH, and skip it if you cannot tolerate environment variables that are subject to string splitting. Before rolling it out, verify that fzf is at version 0.71.0 or higher, run git symbolic-ref -q refs/remotes/origin/HEAD to confirm your remote HEAD matches the branch you actually use, and try GF_PREFERRED_PAGER with your own delta invocation to see whether the quoting survives your shell.

Frequently asked questions

Official sources

1. bigH/git-fuzzy on GitHub
2. Issues
3. License: MIT
4. README