Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Functions

System Information

  • arch() — Instruction set architecture. Possible values are: "aarch64", "arm", "asmjs", "hexagon", "mips", "msp430", "powerpc", "powerpc64", "s390x", "sparc", "wasm32", "x86", "x86_64", and "xcore".
  • num_cpus()1.15.0 — Number of logical CPUs.
  • os() — Operating system. Possible values are: "android", "bitrig", "dragonfly", "emscripten", "freebsd", "haiku", "ios", "linux", "macos", "netbsd", "openbsd", "solaris", and "windows".
  • os_family() — Operating system family; possible values are: "unix" and "windows".

For example:

system-info:
  @echo "This is an {{arch()}} machine."

$ just system-info
This is an x86_64 machine.

The os_family() function can be used to create cross-platform justfiles that work on various operating systems. For an example, see cross-platform.just file.

External Commands

  • shell(command, args...)1.27.0 returns the standard output of shell script command with zero or more positional arguments args. The shell used to interpret command is the same shell that is used to evaluate recipe lines, and can be changed with set shell := […].

    command is passed as the first argument, so if the command is 'echo $@', the full command line, with the default shell command sh -cu and args 'foo' and 'bar' will be:

    'sh' '-cu' 'echo $@' 'echo $@' 'foo' 'bar'

    This is so that $@ works as expected, and $1 refers to the first argument. $@ does not include the first positional argument, which is expected to be the name of the program being run.

# arguments can be variables or expressions
file := '/sys/class/power_supply/BAT0/status'
bat0stat := shell('cat $1', file)

# commands can be variables or expressions
command := 'wc -l'
output := shell(command + ' "$1"', 'main.c')

# arguments referenced by the shell command must be used
empty := shell('echo', 'foo')
full := shell('echo $1', 'foo')
error := shell('echo $1')

# Using python as the shell. Since `python -c` sets `sys.argv[0]` to `'-c'`,
# the first "real" positional argument will be `sys.argv[2]`.
set shell := ["python3", "-c"]
olleh := shell('import sys; print(sys.argv[2][::-1])', 'hello')

Environment Variables

  • env(key)1.15.0 — Retrieves the environment variable with name key, aborting if it is not present.
home_dir := env('HOME')

test:
  echo "{{home_dir}}"

$ just
/home/user1
  • env(key, default)1.15.0 — Retrieves the environment variable with name key, returning default if it is not present.
  • env_var(key) — Deprecated alias for env(key).
  • env_var_or_default(key, default) — Deprecated alias for env(key, default).

Executables

  • require(name)1.39.0 — Search directories in the PATH environment variable for the executable name and return its full path, or halt with an error if no executable with name exists.

    bash := require("bash")

@test:
    echo "bash: '{{bash}}'"

    $ just
bash: '/bin/bash'

  • which(name)1.39.0 — Search directories in the PATH environment variable for the executable name and return its full path, or the empty list if not found. Requires set lists1.53.0.

    set unstable
set lists

bosh := which("bosh")

@test:
    echo "bosh: '{{bosh}}'"

    $ just
bosh: ''

Invocation Information

  • is_dependency() - Returns the string true if the current recipe is being run as a dependency of another recipe, rather than being run directly, otherwise returns the string false.

  • recipe_name()1.53.0 - Returns the name of the current recipe.

Invocation Directory

  • invocation_directory() - Retrieves the absolute path to the current directory when just was invoked, before just changed it (chdir’d) prior to executing commands. On Windows, invocation_directory() uses cygpath to convert the invocation directory to a Cygwin-compatible /-separated path. Use invocation_directory_native() to return the verbatim invocation directory on all platforms.

For example, to call rustfmt on files just under the “current directory” (from the user/invoker’s perspective), use the following recipe:

rustfmt:
  find {{invocation_directory()}} -name \*.rs -exec rustfmt {} \;

Alternatively, if your command needs to be run from the current directory, you could use (e.g.):

build:
  cd {{invocation_directory()}}; ./some_script_that_needs_to_be_run_from_here
  • invocation_directory_native() - Retrieves the absolute path to the current directory when just was invoked, before just changed it (chdir’d) prior to executing commands.

Justfile and Justfile Directory

  • justfile() - Retrieves the path of the current justfile.

  • justfile_directory() - Retrieves the path of the parent directory of the current justfile.

For example, to run a command relative to the location of the current justfile:

script:
  {{justfile_directory()}}/scripts/some_script

Source and Source Directory

  • source_file()1.27.0 - Retrieves the path of the current source file.

  • source_directory()1.27.0 - Retrieves the path of the parent directory of the current source file.

source_file() and source_directory() behave the same as justfile() and justfile_directory() in the root justfile, but will return the path and directory, respectively, of the current import or mod source file when called from within an import or submodule.

Module and Module Directory

  • module_file() - Returns the path of the current module file.

  • module_directory() - Returns the path of the parent directory of the current module file.

  • module_path() - Returns the ::-separated path to the current module.

module_file() and module_directory() behave the same as justfile() and justfile_directory() in the root justfile, but will return the path and directory, respectively, of the current mod source file when called from within a submodule.

Just Process and Executable

  • just_executable() - Absolute path to the just executable.
  • just_pid() - Process ID of the just executable.
  • just_version()1.55.0 - Version of the just executable.

For example:

just-info:
  @echo The executable is at: {{just_executable()}}
  @echo The process ID is: {{ just_pid() }}
  @echo The version is: {{ just_version() }}

$ just
The executable is at: /bin/just
The process ID is: 420
The version is: 1.54.0

String Manipulation

  • append(suffix, s)1.27.0 - Append suffix to whitespace-separated strings in s. append('/src', 'foo bar baz') → 'foo/src bar/src baz/src'
  • prepend(prefix, s)1.27.0 - Prepend prefix to whitespace-separated strings in s. prepend('src/', 'foo bar baz') → 'src/foo src/bar src/baz'
  • encode_uri_component(s)1.27.0 - Percent-encode characters in s except [A-Za-z0-9_.!~*'()-], matching the behavior of the JavaScript encodeURIComponent function.
  • quote(s) - Replace all single quotes with '\'' and prepend and append single quotes to s. This is sufficient to escape special characters for many shells, including most Bourne shell descendants.
  • replace(s, from, to) - Replace all occurrences of from in s with to.
  • replace_regex(s, regex, replacement) - Replace all occurrences of regex in s with replacement. Regular expressions are provided by the Rust regex crate. See the syntax documentation for usage examples. Capture groups are supported. The replacement string uses Replacement string syntax.
  • trim(s) - Remove leading and trailing whitespace from s.
  • trim_end(s) - Remove trailing whitespace from s.
  • trim_end_match(s, substring) - Remove suffix of s matching substring.
  • trim_end_matches(s, substring) - Repeatedly remove suffixes of s matching substring.
  • trim_start(s) - Remove leading whitespace from s.
  • trim_start_match(s, substring) - Remove prefix of s matching substring.
  • trim_start_matches(s, substring) - Repeatedly remove prefixes of s matching substring.

Case Conversion

  • capitalize(s)1.7.0 - Convert first character of s to uppercase and the rest to lowercase.
  • kebabcase(s)1.7.0 - Convert s to kebab-case.
  • lowercamelcase(s)1.7.0 - Convert s to lowerCamelCase.
  • lowercase(s) - Convert s to lowercase.
  • shoutykebabcase(s)1.7.0 - Convert s to SHOUTY-KEBAB-CASE.
  • shoutysnakecase(s)1.7.0 - Convert s to SHOUTY_SNAKE_CASE.
  • snakecase(s)1.7.0 - Convert s to snake_case.
  • titlecase(s)1.7.0 - Convert s to Title Case.
  • uppercamelcase(s)1.7.0 - Convert s to UpperCamelCase.
  • uppercase(s) - Convert s to uppercase.

Path Manipulation

Fallible
  • absolute_path(path) - Absolute path to relative path in the working directory. absolute_path("./bar.txt") in directory /foo is /foo/bar.txt.
  • canonicalize(path)1.24.0 - Canonicalize path by resolving symlinks and removing ., .., and extra /s where possible.
  • extension(path) - Extension of path. extension("/foo/bar.txt") is txt.
  • file_name(path) - File name of path with any leading directory components removed. file_name("/foo/bar.txt") is bar.txt.
  • file_stem(path) - File name of path without extension. file_stem("/foo/bar.txt") is bar.
  • parent_directory(path) - Parent directory of path. parent_directory("/foo/bar.txt") is /foo.
  • without_extension(path) - path without extension. without_extension("/foo/bar.txt") is /foo/bar.

These functions can fail, for example if a path does not have an extension, which will halt execution.

Infallible
  • clean(path) - Simplify path by removing extra path separators, intermediate . components, and .. where possible. clean("foo//bar") is foo/bar, clean("foo/..") is ., clean("foo/./bar") is foo/bar.
  • join(a, b…) - This function uses / on Unix and \ on Windows, which can lead to unwanted behavior. The / operator, e.g., a / b, which always uses /, should be considered as a replacement unless \s are specifically desired on Windows. Join path a with path b. join("foo/bar", "baz") is foo/bar/baz. Accepts two or more arguments.

Filesystem Access

  • path_exists(path) - Returns the string true if the path points at an existing entity and the string false otherwise. Traverses symbolic links, and returns the string false if the path is inaccessible or points to a broken symlink.
  • read(path)1.39.0 - Returns the content of file at path as a string.

Assertions and Error Reporting

  • assert(CONDITION, EXPRESSION)1.27.0 - Error with message EXPRESSION if CONDITION is false. EXPRESSION may be omitted1.53.0,
  • error(message) - Abort execution and report error message to user.

UUID and Hash Generation

  • blake3(string)1.25.0 - Return BLAKE3 hash of string as hexadecimal string.
  • blake3_file(path)1.25.0 - Return BLAKE3 hash of file at path as hexadecimal string.
  • sha256(string) - Return the SHA-256 hash of string as hexadecimal string.
  • sha256_file(path) - Return SHA-256 hash of file at path as hexadecimal string.
  • uuid() - Generate a random version 4 UUID.

Random

  • choose(n, alphabet)1.27.0 - Generate a string of n randomly selected characters from alphabet, which may not contain repeated characters. For example, choose('64', HEX) will generate a random 64-character lowercase hex string.

Datetime

  • datetime(format)1.30.0 - Return local time with format.
  • datetime_utc(format)1.30.0 - Return UTC time with format.

The arguments to datetime and datetime_utc are strftime-style format strings, see the chrono library docs for details.

Semantic Versions

  • semver_matches(version, requirement)1.16.0 - Check whether a semantic version, e.g., "0.1.0" matches a requirement, e.g., ">=0.1.0", returning the string "true" if so and the string "false" otherwise.

Style

  • style(styles)1.37.0 - Return a terminal escape sequence combining the named styles in styles.

    The styles supported by version 1.37.0 and later can be used to duplicate just’s own styles:

    • command: echoed recipe lines

    • error: errors

    • warning: warnings Additional styles supported by 1.55.0 and later include named colors:

    • black

    • blue

    • cyan

    • green

    • magenta

    • red

    • white

    • yellow The 256 indexed colors, written as integers between 0 and 255, e.g., 1 or 67.

    The 24-bit colors, written as #RRGGBB or #RGB hex codes, e.g., #065535 or #AAA.

    And display properties:

    • blink

    • bold

    • dim

    • hidden

    • italic

    • reverse

    • strikethrough

    • underline Two stream names1.55.0 gate the style on whether just would color the output stream, determined by --color, JUST_COLOR, and whether the stream is connected to a terminal:

    • stdout

    • stderr All color styles color the foreground by default, and come in explicit foreground variants prefixed with fg: and background variants prefixed with bg:, e.g., bg:blue, fg:133, and #FFF.

    styles may be a list of styles, in which case all listed styles are combined to produce the final escape sequence.

    Note that the escape sequence returned by style(styles) are prefixes. You can use the NORMAL constant to reset the style after use:

    error message:
  echo '{{style("error") + message + NORMAL}}'

  • style(styles, text)1.55.0 Style text with styles as in the one-argument form. The style is reset automatically, so use of NORMAL to reset the terminal is not needed:

    error message:
  echo '{{style("error", message)}}'
User Directories

These functions1.23.0 return paths to user-specific directories for things like configuration, data, caches, executables, and the user’s home directory.

On Unix, these functions follow the XDG Base Directory Specification.

On macOS and Windows, these functions return the system-specified user-specific directories. For example, cache_directory() returns ~/Library/Caches on macOS and {FOLDERID_LocalAppData} on Windows.

See the dirs crate for more details.

  • cache_directory() - The user-specific cache directory.
  • config_directory() - The user-specific configuration directory.
  • config_local_directory() - The local user-specific configuration directory.
  • data_directory() - The user-specific data directory.
  • data_local_directory() - The local user-specific data directory.
  • executable_directory() - The user-specific executable directory.
  • home_directory() - The user’s home directory.
  • runtime_directory() - The user-specific runtime directory. Only defined on Linux.

If you would like to use XDG base directories on all platforms you can use the env(…) function with the appropriate environment variable and fallback, although note that the XDG specification requires ignoring non-absolute paths, so for full compatibility with spec-compliant applications, you would need to do:

xdg_config_dir := if env('XDG_CONFIG_HOME', '') =~ '^/' {
  env('XDG_CONFIG_HOME')
} else {
  home_directory() / '.config'
}