DocsHandbookExecuting shell commands

Executing Shell Commands

Using Generators, completion specs can execute shell commands on behalf of the user.

Syntax

Shell commands are defined in Generators, using the script property or, for advanced use cases, the custom property.

script as string

The script property can be a string that is executed directly.

See "Basic Generators" to learn more.

script as function

Alternatively, the script property can be function, which recieves the current edit buffer as input and returns a string that is executed.

See "Contextual Generators" for more details.

custom function

If you write a custom function, you can execute shell commands directly.

See "Custom Generators".

Under the hood

Let's say you've defined a Generator where the script property is equal to git branch -l.

Here is the full command that is run in Fig's psuedoterminal:

( cd /path/to/current/directory; git branch -l | cat )

There are a few things to note:

  • By default, Fig will execute your command from the same working directory as the user's current interactive shell.

  • The specified command is piped into cat.

    Piping the target command into cat signals that it is not running in a tty which will often prevent the command from outputting ANSI escape characters to set color or launching into PAGERS, like less.

  • The entire command is executed from a subshell. This means that environment variables will not persist.

  • The environment variables in the psuedoterminal are not guaranteed to match those in the user's current shell.

    Fig attempts to mirror certain environment variables, like $PATH. If there are others that we should include by default, please open an issue.