Path commands

Omni supports handling any kind of executable file and exposing them as omni commands. This is done using the path configuration parameter that will build the omnipath.

Current working directory

Path commands are executed from the directory in which omni was called.

Scope

Path commands are scoped to a repository when the path for those is only defined in the omni configuration of that repository, or can be made available everywhere if defined in a global configuration file. If you want to access a repository-scoped path command, you can use omni scope.

Discoverability

Path commands are loaded by omni after builtin commands and configuration commands, but before Makefile commands. Path commands are also loaded in the order in which they are defined in the omnipath, and alphabetically after that. This means that if a path command has the same name as a builtin command, configuration command, or another path command loaded from a path that has priority in the omnipath, it will be ignored.

note

Commands cmd and cmd subcmd are considered separate commands, and wouldn't lead any of the two to be ignored. Omni would execute cmd subcmd for any call starting with omni cmd subcmd, and would execute cmd for any call starting with omni cmd but not with omni cmd subcmd.

Path commands will be named after the relative path that they were found at. Omni will remove any extension from the executable file, and any directory in the relative path will lose any .d extension that might have been used.

For instance, with the following tree for a path in the omnipath:

.
├── cmd1.sh               # Executable
├── cmd2.py               # Executable
├── cmd3.bin              # Executable
├── cmd3.d
│   ├── cmd3-1.rb         # Executable
│   └── cmd3-2            # Executable
├── cmd4.txt              # Just a regular file
└── cmd5.d
    ├── cmd5-1.d
    │   └── cmd5-1-1.sh   # Executable
    └── cmd5-2.sh         # Executable

The following commands would be made available:

omni cmd1
omni cmd2

# Note that we have the `cmd3` command because it was an executable
omni cmd3
omni cmd3 cmd3-1
omni cmd3 cmd3-2

# There is no `cmd4` as it was not executable

# In this case, there are two levels of commands that do not directly exist
# as they weren't defined in the path. They can still be defined in another
# path, or as configuration or makefile commands, or even builtin commands.
omni cmd5 cmd5-1 cmd5-1-1
omni cmd5 cmd5-2

Auto-updates

Depending on your path_repo_updates configuration, omni will regularly update any repository found in the global omnipath. This is not happening in the background but will happen as you manually call any omni command, except for hook.

Metadata headers

Omni supports a number of metadata headers that will be read from the executable file to tell omni how to behave, or simply show help for that command. If you want to improve your commands' integration with omni, take a look at the available metadata headers.

Environment

The following environment variables are set by omni before the Makefile command is called:

Environment variable	Type	Description
OMNI_SUBCOMMAND	string...	The subcommand that was called leading to the execution of that command; e.g. my command for omni my command

The following environment variables are set by the shell integration and can be taken advantage of when writing commands:

Environment variable	Type	Description
OMNI_SHELL	string	The shell of the user for which the shell integration was loaded
OMNI_CMD_FILE	filepath	The file in which omni will read operations to apply to the shell; this needs to be compatible with the shell of the user as provided by OMNI_SHELL