Guide · git
Git branch autocomplete in zsh on the Mac
Last checked 19 November 2026
In short: type git checkout and Termhint's popup lists your branches at the cursor, the current one marked, before you press Tab. The same goes for tags, remotes, stashes and your git aliases. Termhint reads them from the repository's files; it never runs git to get them.
What you type, what the popup lists
| You type | The popup lists |
|---|---|
git checkout | Local branches, then remote branches by their own name, then tags |
git switch , git branch -d , git rebase | Local branches |
git merge | Local branches, then remote branches |
git push , git fetch | Remotes, each with its URL |
git push origin | Local branches |
git stash pop , git stash apply | stash@{0}, stash@{1}… with each stash's message, newest first |
git tag -d | Tags |
git and the start of a name | Your git aliases beside git's own subcommands, with what each one runs |
Recently changed branches come first: the branch whose ref changed last leads. Branches git has packed (after git gc) follow in name order. The current branch reads "Current branch".
Real output of termhint complete, the command the popup is built from, in an example repository (files and options left out):
$ termhint complete "git checkout "
arg feature/login Branch
arg main Current branch
arg feature/signup Remote branch · origin
arg - Switch to the last used branch
arg v1.4.0 Tag
$ termhint complete "git push "
arg origin https://github.com/example/app.git
$ termhint complete "git stash pop "
arg stash@{0} On main: WIP login form
$ termhint complete "git l"
subcommand lg log --oneline --graph
subcommand ls-remote List references in a remote repository
subcommand log Show commit logs
Subcommands and options come from the git completion spec, with a description for each, like the other zsh autocomplete suggestions.
Aliases complete like what they stand for
- Shell aliases. With
alias gco='git checkout'in your.zshrc,gcolists branches just asgit checkoutdoes. The aliases Oh My Zsh's git plugin defines work the same way. - git aliases. The
[alias]entries of~/.gitconfig,~/.config/git/config(or$XDG_CONFIG_HOME/git/config) and the repository's own config show among the subcommands, with their expansion as the description. A repository's alias wins over a global one of the same name. - Command names. The popup also suggests the command itself:
gioffersgit, along with your aliases and functions.
Read from the files, never by running git
Fig's git completions ran git branch, git tag and friends. Termhint doesn't: a repository's config can make git run another program (core.fsmonitor, for one), and a cloned or unpacked repository isn't necessarily yours. So Termhint reads what git would read:
HEADfor the current branch;refs/heads,refs/remotes,refs/tagsandpacked-refsfor branches and tags;- the repository's
configfor remotes and aliases, with any user name or token cut from anhttps://orssh://remote URL (an scp-styleuser@host:pathkeeps its user); logs/refs/stashfor stashes: only the message, never who made the stash.
It finds the nearest .git above the folder you are in, follows linked worktrees and submodules to where their refs live, and keeps what it read until one of those files changes, so a keystroke costs a few file checks. Files are read only when they are regular files under a size limit.
Limits
- An
includein a git config file is not followed, so aliases kept in an included file don't show. - Arguments of a git alias (
git co) don't complete as the command it runs; a shell alias such asgcodoes. - Branches, tags and remotes come from the folder you are in: outside a repository there are none, only global git aliases.
Where it works
Termhint is a Mac app (macOS 14 or later, Apple silicon) for zsh. The popup shows in the terminals on the terminals page, and inside tmux, its split panes too. The same popup lists ssh hosts, Docker containers and images and Makefile targets. If you mostly want history suggestions, see Termhint and zsh-autosuggestions.
FAQ
Does Termhint run git to list my branches?
No. It reads the repository's files itself: HEAD, the ref folders, packed-refs, the config and the stash log. A repository's config can make git run another program, so Termhint never starts git for these lists.
Do my shell aliases complete branches?
Yes. An alias completes like what it stands for: with alias gco='git checkout', typing gco and a space lists your branches. That holds for aliases you wrote and for the ones a plugin such as Oh My Zsh's git plugin defines.
Does it work in git worktrees and submodules?
Yes. Termhint follows the .git file of a linked worktree or a submodule to the folder where the refs live, so the branches are the repository's own.
Does Termhint keep my branch names?
No. The lists are read when you type and stay in memory on your Mac. What the popup learns for ranking keeps only command, subcommand and option names, never arguments such as branches.
What it costs
Every feature works for 7 days with no account and no card. After that, a one-time license: $11.99 for 1 Mac, $19.99 for 3, $29.99 for 5, plus VAT or sales tax where it applies (pricing).