I have created a few aliases for git in zsh. For example: gch = git checkout, grb = git rebase --committer-date-is-author-date and some more complex useful zsh functions for git commands. But how can I allow these aliases to use zsh git autocompletion?

  • 1
    What happens when you remove oh-my-zsh and instead just zsh -f and then autoload -U compinit and then compinit and then create the aliases?
    – thrig
    Commented Jan 5, 2017 at 18:36
  • My advise is to replace shell aliases like gch, with Git aliases like g ch. This way you get completion for free; in addition, it works for other shells like Bash, Fish, and PowerShell. Commented Oct 8, 2020 at 23:37

4 Answers 4


I've had the same issue. You should check whether the option completealiases is set. It prevents aliases from being internally substituted before completion is attempted. In my case, removing setopt completealiases from my .zshrc resolved the issue. You can try unsetopt completealiases if oh-my-zsh sets it.

  • 2
    This also fixed git-together, which works by aliasing git to its own command.
    – z0r
    Commented Aug 26, 2021 at 4:52

If you open the file which contains the autoloaded function defintion for git completion:
On my ubuntu system, its:


at the top of the file you will see the #compdef declaration

#compdef git git-cvsserver git-receive-pack git-upload-archive git-upload-pack git-shell gitk tig

you can try adding your aliases to the #compdef definition, e.g.

#compdef git git-cvsserver git-receive-pack [...] tig gch grb
                                                      ^^^ ^^^

Then starting a new shell to get that new directive loaded.
Then try invoking completion.

What is /usr/share/zsh/functions/Completion/Unix/_git?

Its the file that contains the autoloaded "function" defining the completion behaviour for the all the commands defined in the #compdef directive, in this case the git family of commands, it lives in fpath and is autoloaded by compinit when the completion system is initialized.

What is #compdef ?

from man zshcompsys

#compdef name ... [ -{p|P} pattern ... [ -N name ... ] ]
The file will be made autoloadable and the function defined in it will be called when completing names, each of which is either the name of a command whose arguments are to be completed or one of a number of special contexts in the form -context- described below.

  • 2
    Is there a nicer way to make this happen so it can fit into my dotfiles? Commented Jan 8, 2017 at 21:24
  • yes there are other ways to script this out but did this work for you? I guess there is no point bothering with improving on this solution if it fundamentally didnt work in the first place. Commented Jan 8, 2017 at 21:27
  • Just tried it and no dice. I apologize for rushing into things. Commented Jan 8, 2017 at 21:50
  • @patrick oh ok sorry. it works for me with functions, however I dont use aliases anymore so I couldnt test on my system Commented Jan 8, 2017 at 21:54

Piling up on the_velour_frog's answer, if you don't want to modify the original completion file. You can use compdef directly:

compdef <completion_function> <function>

For instance

compdef _git gch

I've done something very similar. Are you using oh-my-zsh? If so, make sure you've enabled the zsh-completions plugin in your .zshrc file. I'd also recommend the zsh-autosuggestions plugin.

Once you've done that, you'll need to add the following to your .zshrc file (if it's not already there)

fpath=(~/.zsh/completions $fpath)
autoload -U compinit && compinit
  • Yes, I am oh-my-zsh and I also already have that in the zshrc. Commented Jan 8, 2017 at 21:21

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .