GITSH_COMPLETIONS(5)

NAME
gitsh_completions - Defines options for tab completion

DESCRIPTION
gitsh_completions files define the tab completions options that are available in interactive gitsh(1) sessions.

The content of a gitsh_completions file consists of rules defining the options and arguments that are expected by various commands. gitsh(1) uses the rules to match the input before the word being completed and to generate completions that are relevant in the context.

Each rule is separated from other rules by a blank line.

The first line of a rule specifies the name of the command and the arguments it accepts. In the simplest case, these are just space-separated words. For example, the following gitsh_completions file defines three rules for the git-stash(1) command:

    stash list
    stash show
    stash drop

With these rules in place, gitsh(1) could tab complete the command stash, or if the user had already entered stash it could tab complete the sub-commands list, show, and drop.

In addition to literal words we expect to see in the command, we can use variables that represent particular types of argument. For example, the git-add(1) command expects a file path as an argument:

    add $path

See the section on VARIABLES for a complete list of what's supported.

Some arguments are optional, and others can be repeated. This can be specified using operators similar to those provided by regular expressions. To expand the previous example, git-add(1) can accept one or more paths preceded by an optional -- token:

    add --? $path+

In this example, the? and + operators modify the meaning of the literal and variable arguments. See the section on OPERATORS for a complete list of what's supported.

Subsequent lines of each rule specify the options that the command accepts. These lines start with a whitespace indent, followed by the option name which must start with a - character, optionally followed by an argument the option takes.

The special $opt variable is used in the first line of the rule to specify where the options are expected to appear. For example, git-add(1) accepts options like --all and --edit:

    add $opt* --? $path+
      --all
      --edit

Some options are followed by an argument. This argument is specified in the same way as a positional argument would be specified in the first line of the completion rule, including support for the same variables and operators. For example, the git-init(1) command can be passed a template directory via the --template option:

    init $opt*
      --template $path

It is usually not useful to list short options (i.e. single character options) in a completion rule, except when they expect an argument. For example, the git-commit(1) command can be passed a file containing the commit message via the -F option:

    commit $opt*
      -F $path

OPERATORS
The following operators are supported. They have similar semantics to regular expressions, except that they operate on an entire word instead of a single character.

word?
    Indicates that word can appear zero or one times. In other words, word is optional.

word*
    Indicates that word can appear zero or more times. In other words, word is optional and can be repeated.

word+
    Indicates that word can appear one or more times. In other words, word is required but can be repeated.

(first|second)
    Indicates that either first or second may appear. Unlike regular expressions, the surrounding parentheses are required, and this is the only context in which parentheses may be used.

The various post-fix operators may be applied to a list of options, but the options inside the list must be literals or variables. For example, various commands take a --recurse-submodules option with an optional argument:

    fetch $opt*
      --recurse-submodules (yes|on-demand|no)?

VARIABLES
Variables represent types of arguments that we want to tab complete in a gitsh(1) session.

Variables are more permissive when they are matching the context before a completion than when they are generating completions. For example, consider the following rule:

    diff $revision? $path

If the user enters diff, followed by a space, and presses the tab key, then the $revision variable will produce the names of revisions in the repository as possible completions. However, if the user enters diff my-branch, followed by a space, and presses the tab key, then the $revision variable will match the input my-branch regardless of whether or not it's a valid revision name. gitsh(1) will assume the revision argument has been provided, and present completions for the $path variable.

The role of the tab completion system is to understand the structure of commands and present useful options; it can leave the validation of the user's input to Git.

The following variables are supported:

$anything
    Produces no completion options, but matches any user input. This is useful for situations where we know Git requires an argument, but we're unable to produce useful completions for it.

$command
    Produces the names of Git commands. This includes any custom Git commands found on the user's PATH, the user's Git aliases, and internal gitsh commands.

$path
    Produces paths to files and directories, relative to the current working directory.

$remote
    Produces the names of Git remotes in the current repository.

$revision
    Produces various names for Git revisions, including the names of local branches, remote tracking branches, and tags.

    The completion options produced by this variable will also try to take punctuation into account. For example, if the word being completed is master..my-f, and there is a local branch called my-feature, then the completions would include master..my-feature.

$opt
    Produces the options specified on subsequent lines of the current rule. See the DESCRIPTION section above for more details.

    Unlike other variables listed here, $opt only matches input that begins with a - character and is followed by one or more other characters. For example, -a and --all would match, but example.txt and -- wouldn't.

FILES

/etc/gitsh/completions
    System-wide tab completions file, which defines the tab completion options for popular Git commands.

$HOME/.gitsh_completions
    User-defined completions file, which can be used to add completions for custom commands or aliases.

EXAMPLES
The git-add(1) command takes zero or more options, followed by an optional --, followed by one or more file system paths.

This argument scheme is represented as:

    add $opt* --? $path+
      --all
      --edit
      --force
      --update

I have a custom command called git browse, which takes two arguments: an optional Git revision, followed by a single file system path.

I can add this to my gitsh_completions file as:

    browse $revision? $path

SEE ALSO
gitsh(1)

AUTHORS
George Brocklehurst <george@thoughtbot.com> thoughtbot <hello@thoughtbot.com>