Enable shell tab completion

Tab on gitrole does nothing useful until your shell loads a completion script. Installing gitrole doesn't edit your shell config, so the command is on PATH and the completions are not. This page turns Tab on for subcommands, flags, and saved role names.

Quick start

The path below is a global npm install on zsh. bash and fish are further down. brew install synthesiseng/tap/gitrole puts gitrole and gitrole-prompt on PATH. The Homebrew formula doesn't install the completion scripts into your shell, and this page doesn't document a Homebrew prefix path for them. If you installed with Homebrew, use the checkout instructions below with an absolute path to this source repository. The npm paths apply only when the npm package is actually installed. You do not need a second CLI installation.

Add the completions directory to fpath before compinit. zsh only loads _gitrole from fpath during compinit, so sourcing the file doesn't register completion. If your startup file already runs compinit, put the fpath line above that call.

completions="$(npm root -g)/gitrole/completions"
fpath=("$completions" $fpath)
autoload -Uz compinit
compinit

The zsh interactive capture was intermittent during verification, so this setup is provided without a completed interactive qualification. Open a new shell. Press Tab at the end of gitrole (with the trailing space). zsh should list subcommands such as add, use, and status. You can stop there. bash, fish, and the other install locations are below.

zsh

There is no oh-my-zsh plugin. Use the same fpath lines as the quick start, with a different directory.

Project install, from that project directory:

completions="$(pwd)/node_modules/gitrole/completions"
fpath=("$completions" $fpath)
autoload -Uz compinit
compinit

Repository checkout, from the repo root:

completions="/absolute/path/to/gitrole/completions"
fpath=("$completions" $fpath)
autoload -Uz compinit
compinit

bash

Source gitrole.bash from ~/.bashrc. bash completion registers when the file is sourced, which is why this isn't the zsh fpath setup.

Global npm install:

source "$(npm root -g)/gitrole/completions/gitrole.bash"

Project install, from that project directory:

source "$(pwd)/node_modules/gitrole/completions/gitrole.bash"

Repository checkout, from the repo root:

source "/absolute/path/to/gitrole/completions/gitrole.bash"

Open a new shell and press Tab after gitrole . bash lists the same subcommands.

fish

Fish was unavailable during verification. These instructions describe the supplied script; interactive behavior remains unverified.

fish loads completions from files in ~/.config/fish/completions/. A symlink keeps the script on the installed package when the package updates.

Global npm install:

mkdir -p ~/.config/fish/completions
ln -sf (npm root -g)/gitrole/completions/gitrole.fish ~/.config/fish/completions/gitrole.fish

Project install, from that project directory:

mkdir -p ~/.config/fish/completions
ln -sf (pwd)/node_modules/gitrole/completions/gitrole.fish ~/.config/fish/completions/gitrole.fish

Repository checkout, from the repo root:

mkdir -p ~/.config/fish/completions
ln -sf /absolute/path/to/gitrole/completions/gitrole.fish ~/.config/fish/completions/gitrole.fish

Open a new fish shell and press Tab after gitrole . fish lists the same subcommands. For a machine-wide install, symlink gitrole.fish into a directory on $fish_complete_path. echo $fish_complete_path prints that list on your machine.

What completes

Tab offers the subcommands, including import current and remote set, and the flags each script lists. For gitrole status, Tab offers --short, --offline, and --help. --offline is in the bash, zsh, and fish scripts so a prompt setup doesn't have to be typed by hand.

Saved role names are offered for:

• gitrole use
• gitrole pin
• gitrole remove
• gitrole remote set
• gitrole add
• gitrole import current --name

Role names come from gitrole list, which reads the saved roles file. If that file can't be read, role completion is empty and no error is printed, so a broken roles file looks like "you have no roles" rather than a shell error.

Verify

Open a new shell after the snippet is in place. Press Tab at the end of this line:

gitrole 

zsh, bash, and fish list subcommands such as add, use, and status. Then try gitrole use and confirm your saved role names appear.

Where the scripts live

The repository and the published npm package both contain:

completions/gitrole.bash
completions/_gitrole
completions/gitrole.fish

Install	Path
Global npm install	$(npm root -g)/gitrole/completions/
Project npm install	node_modules/gitrole/completions/
Repository checkout	completions/ at the repo root

npm root -g prints the global node_modules directory. That path is the npm install, not a Homebrew prefix.

What it doesn't do

Completion doesn't install gitrole, switch roles, or run gitrole status. It also doesn't enable itself when you install the package. The Homebrew formula isn't covered by a prefix path on this page.