rush / docs

Writing completions

Rush completions are Rush scripts.

Put a completion file at one of these paths:

$XDG_DATA_HOME/rush/completions/COMMAND.rush
$HOME/.local/share/rush/completions/COMMAND.rush
$XDG_CONFIG_HOME/rush/completions/COMMAND.rush
$HOME/.config/rush/completions/COMMAND.rush

System completions are loaded from:

$XDG_DATA_DIRS/rush/completions/COMMAND.rush
/usr/local/share/rush/completions/COMMAND.rush
/usr/share/rush/completions/COMMAND.rush

Rush loads the file when completing COMMAND for the first time.

Static completions

Use complete to register subcommands and options.

complete git --subcommand commit --description 'record changes'
complete git --subcommand checkout --description 'switch branches'

complete git --option --long help --description 'show help'
complete git --option --short C --value-name path --description 'run as if in path'

complete 'git commit' --option --long amend --description 'amend previous commit'
complete 'git commit' --option --short m --long message --value-name text --description 'use text as message'

The first word is the command. Extra words scope the rule to a subcommand path.

Dynamic completions

Use a function when candidates depend on the current machine, repository, or command line.

__rush_complete_git_branches() {
  completion candidate main --description 'branch'
  completion candidate next --description 'branch'
}

complete 'git checkout' --argument --function __rush_complete_git_branches

The function runs only during completion. It adds candidates with completion candidate.

Candidate fields

completion candidate VALUE [--display TEXT] [--description TEXT] [--kind KIND] [--no-space]

Kinds:

command builtin function file directory variable option subcommand plain

VALUE is inserted. DISPLAY is shown in the menu. DESCRIPTION is shown next to it. --no-space prevents Rush from adding a trailing space after insertion.

Options

For option completions, prefer completion option.

__rush_complete_tool() {
  completion option --long verbose --description 'show verbose output'
  completion option --short o --long output --argument file --description 'write to file'
}

complete tool --function __rush_complete_tool

If an option has an argument, Rush can detect the value position.

__rush_complete_tool() {
  completion option --long color --argument when --description 'when to use color'

  if test "$(completion position)" = option_value; then
    completion candidate auto
    completion candidate always
    completion candidate never
  fi
}

complete tool --function __rush_complete_tool

Context

Completion functions can ask Rush about the current command line.

completion prefix          # text being completed
completion command         # root command
completion argument-index  # zero-based argument index
completion previous        # previous word
completion position        # command, subcommand, option, option_value, argument
completion option-name     # active option name, in option_value position
completion option-spelling # active spelling, such as --color or -o

Helper completions

Rush can add common candidate sets for you.

completion files [--prefix PREFIX] [--extension EXT]
completion directories [--prefix PREFIX] [--append-slash]
completion executables [--prefix PREFIX]
completion variables [--prefix PREFIX]

If --prefix is omitted, Rush uses the current completion prefix.

Dynamic rule types

Use these forms to run a function only in a specific semantic position.

complete COMMAND --subcommands --function FUNC
complete COMMAND --options --function FUNC
complete COMMAND --argument --function FUNC
complete COMMAND --option-value --long NAME --function FUNC
complete COMMAND --option-value --short NAME --function FUNC

Complete example

File: $HOME/.local/share/rush/completions/example.rush

complete example --subcommand run --description 'run a target'
complete example --subcommand clean --description 'remove build output'
complete example --option --long help --description 'show help'

__rush_complete_example_targets() {
  completion candidate app --kind plain
  completion candidate tests --kind plain
}

complete 'example run' --argument --function __rush_complete_example_targets

Status

The completion API is early. Expect changes.