Below you can find a list of general purpose utilities.
This command validates that given program is available for execution. It checks for PATH binaries, functions, and builtins. It returns zero exit code if a
command exists and non-zero code otherwise.
You can use this utility to check if some program is installed and perform actions conditionally. For example, you can either return an error and exit or continue script's execution. For example:
# Check multiple commands for existing if spaceship::exists nvm; then # extract nvm version elif spaceship::exists node; then # extract node version else return fi # Do nothing if docker is not installed spaceship::exists docker || return
The same as
spaceship::exists, but for functions. It returns zero exit code if a
function has been defined previously and non-zero if
You can use this utility to check if a user has previously defined a function or not. For example:
# Check if section has been defined if spaceship::defined spaceship_section; then spaceship_section else # section is not found fi
This utility returns zero exit code if a current working directory is a Git repository and non-zero if it's not. For example:
# Return if current directory is not a git repository spaceship::is_git || return
The same as
spaceship::is_git, but for Mercurial repositories. This utility returns zero exit code if a current working directory is a Mercurial repository and non-zero if it's not.
# Return if current directory is not a Mercurial repository spaceship::is_hg || return
Checks if a section is asynchronous or not by checking
SPACESHIP_<SECTION>_ASYNC option. This utility returns zero exit code if a section is asynchronous and non-zero if it's not.
SPACESHIP_PROMPT_ASYNC is set to
false, then all sections are considered to be synchronous.
sectionRequired — a section to be checked.
Some sections are always synchronous, not matter what, to ensure correct work of the prompt. Those are:
Checks if the prompt works in asynchronous mode or not. This utility returns zero exit code if the prompt works in asynchronous mode and non-zero if it's not.
SPACESHIP_PROMPT_ASYNC is set to
zsh-async is loaded.
This utility checks if
option variable is set and if it is, prints the
message supports escapes to set foreground color, background color and other visual effects.
spaceship::deprecated <option> [message]
optionRequired — the name of a deprecated variable. If this variable is set (contains any value), then
"%B$deprecated%b is deprecated.will be printed.
%bis escapes to set the bold style for text.
messageOptional — a string for additional deprecation message. Can contain prompt expansions.
Read more about escapes in Prompt Expansion section of Zsh documentation.
Here's an example of usage:
# Check if SPACESHIP_BATTERY_ALWAYS_SHOW is set spaceship::deprecated SPACESHIP_BATTERY_ALWAYS_SHOW "Use %BSPACESHIP_BATTERY_SHOW='always'%b instead." #> SPACESHIP_BATTERY_ALWAYS_SHOW is deprecated. Use SPACESHIP_BATTERY_SHOW='always' instead.
This utility converts
seconds into a human-readable format. It splits
seconds into days (
d), hours (
h), minutes (
m) and seconds (
spaceship::displaytime <seconds> [precision]
secondsRequired — seconds for conversion into the readable format.
precisionOptional — precision of the output. Default value is
The usage example looks like this:
spaceship::displaytime 123456 #> 1d 10h 17m 36.0s paceship::displaytime 123.45 2 #> 2m 3.45s
A utility for performing a union (intersection) of arrays. It lists the contents found in two or more arrays.
Spaceship uses this utility internally for resolution of sections that need to be sourced.
spaceship::union <arr1[ arr2[ ...]]>
arr...— a list of arrays.
Here is an example:
arr1=('a' 'b' 'c') arr2=('b' 'c' 'd') arr3=('c' 'd' 'e') spaceship::union $arr1 $arr2 $arr3 #> a b c d e
Performs an upward search for a specific file or directory. Returns the path of the first found file or directory. Goes upwards up to the repository or system root directory. Useful for understanding the context of a current directory.
spaceship::upsearch [--silent] <paths...>
paths...Required — a list of paths to search.
-sOptional — if set, then the utility will return zero exit code, if at least one of
pathsis found and non-zero, if not.
This can be used for detecting project context or finding a specific file upwards.
# Understanding the project context spaceship::upsearch -s package.json node_modules && echo "Node project detected." # Finding a specific file upwards spaceship::upsearch package.json #> /path/to/project/package.json
This utility queries data files for a specific key. It returns the value of the key. Exits with non-zero code when the file type is unknown, data cannot be read, or the key is not found.
spaceship::datafile --<type> <file> [key]
--typeRequired — a type of the data file. Can be
fileRequired — a path to the data file.
keyOptional — a key to query within a data file.
You can use this utility to query data from a data file:
spaceship::datafile --json package.json "author.name" #> "John Doe"
It needs the following tools for reading data files:
- JSON —
- YAML —
- TOML —
- XML —
The most universal solution for reading data files is to use