Functions

just provides a few built-in functions that might be useful when writing recipes.

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.

Environment Variables

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

test:
  echo "{{home_dir}}"
$ just
/home/user1
  • env_var_or_default(key, default) — Retrieves the environment variable with name key, returning default if it is not present.
  • env(key)1.15.0 — Alias for env_var(key).
  • env(key, default)1.15.0 — Alias for env_var_or_default(key, default).

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 rule:

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

Just Executable

  • just_executable() - Absolute path to the just executable.

For example:

executable:
  @echo The executable is at: {{just_executable()}}
$ just
The executable is at: /bin/just

Just Process ID

  • just_pid() - Process ID of the just executable.

For example:

pid:
  @echo The process ID is: {{ just_pid() }}
$ just
The process ID is: 420

String Manipulation

  • 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 to to.
  • replace_regex(s, regex, replacement) - Replace all occurrences of regex in s to 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, pat) - Remove suffix of s matching pat.
  • trim_end_matches(s, pat) - Repeatedly remove suffixes of s matching pat.
  • trim_start(s) - Remove leading whitespace from s.
  • trim_start_match(s, pat) - Remove prefix of s matching pat.
  • trim_start_matches(s, pat) - Repeatedly remove prefixes of s matching pat.

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) - 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 be 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 true if the path points at an existing entity and false otherwise. Traverses symbolic links, and returns false if the path is inaccessible or points to a broken symlink.
Error Reporting
  • error(message) - Abort execution and report error message to user.

UUID and Hash Generation

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

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 "true" if so and "false" otherwise.
XDG Directories1.23.0

These functions return paths to user-specific directories for things like configuration, data, caches, executables, and the user’s home directory. These functions follow the XDG Base Directory Specification, and are implemented with the dirs crate.

  • 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.