Add zsh completions to homebrew formula

[sandr01d]

Check list

• I have read through the README
• I have the latest version of forgit
• I have searched through the existing issues

Noticed the homebrew formula installs completions for bash, but not zsh. As I don't use homebrew myself, I currently don't have a setup to test this, maybe someone else is interested in doing this?

[cjappl]

Pinging @carlfriedrich as the original master of the homebrew stuff.

I'd love to learn how to run and test this stuff, if you want to document it somewhere I can help next time.

[carlfriedrich]

@sandr01d I actually set up forgit in homebrew once and never updated it. I was planning to add a GitHub action to update it automatically with each release, just like we do with AUR, but I didn't have time for it, yet, and furthermore I don't have access to a Mac in order to test the homebrew stuff.
@cjappl Homebrew is actually well documented. I had to check it out myself in order to implement forgit in there, because I haven't used it before, so you might give it a try as well?

[cjappl]

Happy to investigate this. I think I can also try to get it automated. it'd be nice to have our freshest up all the time.

[cjappl]

Alright, there are multiple rounds we have to go through here, as our completions aren't exactly working still. I think we need to change them on our side of the fence.

To get the ball rolling, I submitted a cleanup PR:
Homebrew/homebrew-core#161025

This was mostly to get my feet wet in the homebrew world so I could do the meatier change of fixing the completions. Check it out if you get a chance.

[carlfriedrich]

@cjappl Great, thanks for taking this over!

[cjappl]

@carlfriedrich could you walk me (an idiot, who doesn't understand zsh) how do use our completions?

Like very explicitly:

1. Copy file to x
2. run this command
3. ga <tab> should look like ...

I cannot get them to work, but I 100% expect user error. Please be as explicit as possible, as I don't have any zsh experience.

What I have now:

Git forgit is on my path and runs as expected:

 % git forgit add
Nothing to add.
topher@tMBP forgit % ga
Nothing to add.

following these instructions at the top of the completions:

#
# forgit completions for zsh plugin
#
# When using forgit via the shell plugin, place completions/_git-forgit in your
# $fpath (e.g. /usr/share/zsh/site-functions) and source this file after
# forgit.plugin.zsh to enable tab completion for shell functions and aliases.

I have an $fpath (no idea what that is) that looks like:

% echo $fpath
/opt/homebrew/share/zsh/site-functions /usr/local/share/zsh/site-functions /usr/share/zsh/site-functions /usr/share/zsh/5.9/functions

I have placed this file in /opt/homebrew/share/zsh/site-functions:

% ls /opt/homebrew/share/zsh/site-functions
...
_black                  _delta                  _git                    _j                      _ninja                  _tig                    tig-completion.bash
_brew                   _docker                 _git-forgit             _jj                     _rg                     _tldr

I have tried to source it:

topher@tMBP forgit % source /opt/homebrew/share/zsh/site-functions/_git-forgit
(eval):1: no matches found: *:globbed-files
_tags:comptags:36: can only be called from completion function
_tags:comptry:55: can only be called from completion function
_tags:comptags:60: can only be called from completion function
_tags:comptags:67: can only be called from completion function

I have tried to autocomplete, assuming I'll get something:

% forgit::add <TAB>
LICENSE             README.md           bin/                completions/        conf.d/             forgit.plugin.sh@   forgit.plugin.zsh*

These files are not changed, I do not get suggested any flags for git add or similar

[carlfriedrich]

Pinging @sandr01d who implemented the zsh completions.

[sandr01d]

@cjappl sounds like compsys (zsh's completion system) is not initialized. Let me walk you through the setup and try to provide a bit of background information that might come in handy.
For completions in zsh to work, compsys has to be explicitly loaded and initialized in your .zshrc. The most common way to do so is to place the following snippet somewhere at the top of your .zshrc, before you load any plugins:

autoload -Uz compinit
compinit

$fpath is a variable similar to the $PATH environment variable, but specific to zsh completion functions. Compinit will scan files in in the directories present in $fpath and dump a bit of information about the functions defined in these files in ~/.zcompdump. In case you want to check whether compinit correctly finds your completion functions, this is a good place to start. The first time you try to use a completion for a command, compsys will check whether a completion function has been noted in your compdump and, if so, will load and cache the completion function from the corresponding completion file. So you have to place completions/_git-forgit in a directory that is listed in your $fpath as you seem to have done correctly. /opt/homebrew/share/zsh/site-functions is not part of $fpath by default. I suspect that homebrew is adding this directory to the $fpath for plugins installed with homebew. I think this should work fine, but in case you're having issues you might want to test one of the other directories from your $fpath, /usr/local/share/zsh/site-functions would usually be a good start.
Of course you also have to source forgit as usual from your .zshrc, but I'm suspecting you already do so. At this point you should get completions for forgit as a git subcommand, e.g.

git forgit <TAB>

should print a list of available commands.
For the completions to also work with forgits aliases and functions, you have to source completions/git-forgit.zsh after sourcing forgit, e.g.:

source /path/to/forgit.plugin.zsh
source /path/to/completions/git-forgit.zsh

Let me know whether things are working out for you and whether anything I've provided is unclear and I will do my best to help sort it out.
In general the man page for zshcompsys and sometimes zshmisc are usually a good resource.

[cjappl]

Thank you. Very helpful.

Could you explain the difference between our two files:
https://github.com/wfxr/forgit/blob/master/completions/_git-forgit

and
https://github.com/wfxr/forgit/blob/master/completions/git-forgit.zsh

Which file should be sourced? are the names important? Do they both need to be on $fpath? (again, any additional info greatly appreciated)

EDIT: forgive me for not RTFM. From what I understand is that _git-forgit controls the sub command form, aka git forgit foo. This file, if placed in $fpath will automatically provide autocompletions when a user git forgit <TAB>

The other file, git-forgit.zsh provides autocompletion for the aliases and functions, such as ga forgit::log etc. The user does not need this in the fpath, just needs to source this file after the plugin is loaded.

I have played around with this a bit in #340