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.
Path commands are executed from the directory in which omni was called.
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.
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
Omni supports a number of metadata that will be read either from the executable file itself or from a <command>.metadata.yaml file located in the same directory. These metadata serve to tell omni how to behave with that command, or simply show help for it. If you want to improve your commands' integration with omni, take a look at the available metadata.
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 |