just is a handy way to save and run project-specific commands.
This readme is also available as a book. The book reflects the latest release, whereas the readme on GitHub reflects latest master.
(δΈζζζ‘£ε¨ θΏι, εΏ«ηθΏζ₯!)
Commands, called recipes, are stored in a file called justfile with syntax
inspired by make:
You can then run them with just RECIPE:
$ just test-all
cc *.c -o main
./test --all
Yay, all your tests passed!just has a ton of useful features, and many improvements over make:
-
justis a command runner, not a build system, so it avoids much ofmake's complexity and idiosyncrasies. No need for.PHONYrecipes! -
Linux, MacOS, Windows, and other reasonable unices are supported with no additional dependencies. (Although if your system doesn't have an
sh, you'll need to choose a different shell.) -
Errors are specific and informative, and syntax errors are reported along with their source context.
-
Recipes can accept command line arguments.
-
Wherever possible, errors are resolved statically. Unknown recipes and circular dependencies are reported before anything runs.
-
justloads.envfiles, making it easy to populate environment variables. -
Recipes can be listed from the command line.
-
Command line completion scripts are available for most popular shells.
-
Recipes can be written in arbitrary languages, like Python or NodeJS.
-
justcan be invoked from any subdirectory, not just the directory that contains thejustfile. -
And much more!
If you need help with just please feel free to open an issue or ping me on
Discord. Feature requests and bug reports are
always welcome!
just should run on any system with a reasonable sh, including Linux, MacOS,
and the BSDs.
On Windows, just works with the sh provided by
Git for Windows,
GitHub Desktop, or
Cygwin.
If you'd rather not install sh, you can use the shell setting to use the
shell of your choice.
Like PowerShell:
# use PowerShell instead of sh:
set shell := ["powershell.exe", "-c"]
hello:
Write-Host "Hello, world!"β¦or cmd.exe:
# use cmd.exe instead of sh:
set shell := ["cmd.exe", "/c"]
list:
dirYou can also set the shell using command-line arguments. For example, to use
PowerShell, launch just with --shell powershell.exe --shell-arg -c.
(PowerShell is installed by default on Windows 7 SP1 and Windows Server 2008 R2
S1 and later, and cmd.exe is quite fiddly, so PowerShell is recommended for
most Windows users.)
| Package Manager | Package | Command |
|---|---|---|
| asdf | just |
asdf plugin add justasdf install just <version>
|
| Cargo | just | cargo install just |
| Conda | just | conda install -c conda-forge just |
| Homebrew | just | brew install just |
| Nix | just | nix-env -iA nixpkgs.just |
| npm | rust-just | npm install -g rust-just |
| PyPI | rust-just | pipx install rust-just |
| Snap | just | snap install --edge --classic just |
| Operating System | Package Manager | Package | Command |
|---|---|---|---|
| FreeBSD | pkg | just | pkg install just |
| Operating System | Package Manager | Package | Command |
|---|---|---|---|
| Alpine | apk-tools | just | apk add just |
| Arch | pacman | just | pacman -S just |
| Debian 13 (unreleased) and Ubuntu 24.04 derivatives | apt | just | apt install just |
| Debian and Ubuntu derivatives | MPR | just |
git clone https://mpr.makedeb.org/justcd justmakedeb -si
|
| Debian and Ubuntu derivatives | Prebuilt-MPR | just |
You must have the Prebuilt-MPR set up on your system in order to run this command.apt install just
|
| Fedora | DNF | just | dnf install just |
| Gentoo | Portage | guru/dev-build/just |
eselect repository enable guruemerge --sync guruemerge dev-build/just
|
| NixOS | Nix | just | nix-env -iA nixos.just |
| openSUSE | Zypper | just | zypper in just |
| Solus | eopkg | just | eopkg install just |
| Void | XBPS | just | xbps-install -S just |
| Package Manager | Package | Command |
|---|---|---|
| Chocolatey | just | choco install just |
| Scoop | just | scoop install just |
| Windows Package Manager | Casey/Just | winget install --id Casey.Just --exact |
| Package Manager | Package | Command |
|---|---|---|
| MacPorts | just | port install just |
Pre-built binaries for Linux, MacOS, and Windows can be found on the releases page.
You can use the following command on Linux, MacOS, or Windows to download the
latest release, just replace DEST with the directory where you'd like to put
just:
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to DESTFor example, to install just to ~/bin:
# create ~/bin
mkdir -p ~/bin
# download and extract just to ~/bin/just
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/bin
# add `~/bin` to the paths that your shell searches for executables
# this line should be added to your shells initialization file,
# e.g. `~/.bashrc` or `~/.zshrc`
export PATH="$PATH:$HOME/bin"
# just should now be executable
just --helpNote that install.sh may fail on GitHub Actions, or in other environments
where many machines share IP addresses. install.sh calls GitHub APIs in order
to determine the latest version of just to install, and those API calls are
rate-limited on a per-IP basis. To make install.sh more reliable in such
circumstances, pass a specific tag to install with --tag.
Releases include a SHA256SUM file
which can be used to verify the integrity of pre-built binary archives.
To verify a release, download the pre-built binary archive along with the
SHA256SUM file and run:
shasum --algorithm 256 --ignore-missing --check SHA256SUMSjust can be installed on GitHub Actions in a few ways.
Using package managers pre-installed on GitHub Actions runners on MacOS with
brew install just, and on Windows with choco install just.
With extractions/setup-just:
- uses: extractions/setup-just@v2
with:
just-version: 1.5.0 # optional semver specification, otherwise latestOr with taiki-e/install-action:
- uses: taiki-e/install-action@justAn RSS feed of just releases is available here.
just-install can be used to automate
installation of just in Node.js applications.
just is a great, more robust alternative to npm scripts. If you want to
include just in the dependencies of a Node.js application, just-install
will install a local, platform-specific binary as part of the npm install
command. This removes the need for every developer to install just
independently using one of the processes mentioned above. After installation,
the just command will work in npm scripts or with npx. It's great for teams
who want to make the set up process for their project as easy as possible.
For more information, see the just-install README file.
With the release of version 1.0, just features a strong commitment to
backwards compatibility and stability.
Future releases will not introduce backwards incompatible changes that make
existing justfiles stop working, or break working invocations of the
command-line interface.
This does not, however, preclude fixing outright bugs, even if doing so might
break justfiles that rely on their behavior.
There will never be a just 2.0. Any desirable backwards-incompatible changes
will be opt-in on a per-justfile basis, so users may migrate at their
leisure.
Features that aren't yet ready for stabilization are marked as unstable and may
be changed or removed at any time. Using unstable features produces an error by
default, which can be suppressed with by passing the --unstable flag,
set unstable, or setting the environment variable JUST_UNSTABLE, to any
value other than false, 0, or the empty string.
justfile syntax is close enough to make that you may want to tell your
editor to use make syntax highlighting for just.
Vim version 9.1.1042 or better and Neovim version 0.11 or better support Justfile syntax highlighting out of the box, thanks to pbnj.
The vim-just plugin provides syntax
highlighting for justfiles.
Install it with your favorite package manager, like Plug:
call plug#begin()
Plug 'NoahTheDuke/vim-just'
call plug#end()Or with Vim's built-in package support:
mkdir -p ~/.vim/pack/vendor/start
cd ~/.vim/pack/vendor/start
git clone https://github.com/NoahTheDuke/vim-just.gittree-sitter-just is an Nvim Treesitter plugin for Neovim.
Vim's built-in makefile syntax highlighting isn't perfect for justfiles, but
it's better than nothing. You can put the following in ~/.vim/filetype.vim:
if exists("did_load_filetypes")
finish
endif
augroup filetypedetect
au BufNewFile,BufRead justfile setf make
augroup ENDOr add the following to an individual justfile to enable make mode on a
per-file basis:
# vim: set ft=make :
just-mode provides syntax
highlighting and automatic indentation of justfiles. It is available on
MELPA as just-mode.
justl provides commands for executing and listing recipes.
You can add the following to an individual justfile to enable make mode on
a per-file basis:
# Local Variables:
# mode: makefile
# End:
An extension for VS Code is available here.
Unmaintained VS Code extensions include skellock/vscode-just and sclu1034/vscode-just.
A plugin for JetBrains IDEs by linux_china is available here.
Kakoune supports justfile syntax highlighting out of the box, thanks to
TeddyDD.
Helix supports justfile syntax highlighting
out-of-the-box since version 23.05.
The Just package by
nk9 with just syntax and some other tools is
available on PackageControl.
Micro supports Justfile syntax highlighting out of the box, thanks to tomodachi94.
The zed-just extension by jackTabsCode is avilable on the Zed extensions page.
Feel free to send me the commands necessary to get syntax highlighting working in your editor of choice so that I may include them here.
See the installation section for how to install just on your computer. Try
running just --version to make sure that it's installed correctly.
For an overview of the syntax, check out this cheatsheet.
Once just is installed and working, create a file named justfile in the
root of your project with the following contents:
recipe-name:
echo 'This is a recipe!'
# this is a comment
another-recipe:
@echo 'This is another recipe.'When you invoke just it looks for file justfile in the current directory
and upwards, so you can invoke it from any subdirectory of your project.
The search for a justfile is case insensitive, so any case, like Justfile,
JUSTFILE, or JuStFiLe, will work. just will also look for files with the
name .justfile, in case you'd like to hide a justfile.
Running just with no arguments runs the first recipe in the justfile:
$ just
echo 'This is a recipe!'
This is a recipe!One or more arguments specify the recipe(s) to run:
$ just another-recipe
This is another recipe.just prints each command to standard error before running it, which is why
echo 'This is a recipe!' was printed. This is suppressed for lines starting
with @, which is why echo 'This is another recipe.' was not printed.
Recipes stop running if a command fails. Here cargo publish will only run if
cargo test succeeds:
publish:
cargo test
# tests passed, time to publish!
cargo publishRecipes can depend on other recipes. Here the test recipe depends on the
build recipe, so build will run before test:
build:
cc main.c foo.c bar.c -o main
test: build
./test
sloc:
@echo "`wc -l *.c` lines of code"$ just test
cc main.c foo.c bar.c -o main
./test
testing⦠all tests passed!Recipes without dependencies will run in the order they're given on the command line:
$ just build sloc
cc main.c foo.c bar.c -o main
1337 lines of codeDependencies will always run first, even if they are passed after a recipe that depends on them:
$ just test build
cc main.c foo.c bar.c -o main
./test
testing⦠all tests passed!A variety of justfiles can be found in the
examples directory and on
GitHub.
When just is invoked without a recipe, it runs the first recipe in the
justfile. This recipe might be the most frequently run command in the
project, like running the tests:
test:
cargo testYou can also use dependencies to run multiple recipes by default:
default: lint build test
build:
echo Buildingβ¦
test:
echo Testingβ¦
lint:
echo Lintingβ¦If no
10000
recipe makes sense as the default recipe, you can add a recipe to the
beginning of your justfile that lists the available recipes:
default:
just --listRecipes can be listed in alphabetical order with just --list:
$ just --list
Available recipes:
build
test
deploy
lintRecipes in submodules can be listed with just --list PATH,
where PATH is a space- or ::-separated module path:
$ cat justfile
mod foo
$ cat foo.just
mod bar
$ cat bar.just
baz:
$ just foo bar
Available recipes:
baz
$ just foo::bar
Available recipes:
baz
just --summary is more concise:
$ just --summary
build test deploy lintPass --unsorted to print recipes in the order they appear in the justfile:
test:
echo 'Testing!'
build:
echo 'Building!'$ just --list --unsorted
Available recipes:
test
build$ just --summary --unsorted
test buildIf you'd like just to default to listing the recipes in the justfile, you
can use this as your default recipe:
default:
@just --listNote that you may need to add --justfile {{justfile()}} to the line above.
Without it, if you executed just -f /some/distant/justfile -d . or
just -f ./non-standard-justfile, the plain just --list inside the recipe
would not necessarily use the file you provided. It would try to find a
justfile in your current path, maybe even resulting in a No justfile found
error.
The heading text can be customized with --list-heading:
$ just --list --list-heading $'Cool stuffβ¦\n'
Cool stuffβ¦
test
buildAnd the indentation can be customized with --list-prefix:
$ just --list --list-prefix Β·Β·Β·Β·
Available recipes:
Β·Β·Β·Β·test
Β·Β·Β·Β·buildThe argument to --list-heading replaces both the heading and the newline
following it, so it should contain a newline if non-empty. It works this way so
you can suppress the heading line entirely by passing the empty string:
$ just --list --list-heading ''
test
buildMultiple recipes may be invoked on the command line at once:
build:
make web
serve:
python3 -m http.server -d out 8000$ just build serve
make web
python3 -m http.server -d out 8000Keep in mind that recipes with parameters will swallow arguments, even if they match the names of other recipes:
build project:
make {{project}}
serve:
python3 -m http.server -d out 8000$ just build serve
make: *** No rule to make target `serve'. Stop.The --one flag can be used to restrict command-line invocations to a single
recipe:
$ just --one build serve
error: Expected 1 command-line recipe invocation but found 2.By default, recipes run with the working directory set to the directory that
contains the justfile.
The [no-cd] attribute can be used to make recipes run with the working
directory set to directory in which just was invoked.
@foo:
pwd
[no-cd]
@bar:
pwd$ cd subdir
$ just foo
/
$ just bar
/subdirYou can override the working directory for all recipes with
set working-directory := 'β¦':
set working-directory := 'bar'
@foo:
pwd$ pwd
/home/bob
$ just foo
/home/bob/barYou can override the working directory for a specific recipe with the
working-directory attribute1.38.0:
[working-directory: 'bar']
@foo:
pwd$ pwd
/home/bob
$ just foo
/home/bob/barThe argument to the working-directory setting or working-directory
attribute may be absolute or relative. If it is relative it is interpreted
relative to the default working directory.
Aliases allow recipes to be invoked on the command line with alternative names:
alias b := build
build:
echo 'Building!'$ just b
echo 'Building!'
Building!The target of an alias may be a recipe in a submodule:
mod foo
alias baz := foo::barSettings control interpretation and execution. Each setting may be specified at
most once, anywhere in the justfile.
For example:
set shell := ["zsh", "-cu"]
foo:
# this line will be run as `zsh -cu 'ls **/*.txt'`
ls **/*.txt| Name | Value | Default | Description |
|---|---|---|---|
allow-duplicate-recipes |
boolean | false |
Allow recipes appearing later in a justfile to override earlier recipes with the same name. |
allow-duplicate-variables |
boolean | false |
Allow variables appearing later in a justfile to override earlier variables with the same name. |
dotenv-filename |
string | - | Load a .env file with a custom name, if present. |
dotenv-load |
boolean | false |
Load a .env file, if present. |
dotenv-path |
string | - | Load a .env file from a custom path and error if not present. Overrides dotenv-filename. |
dotenv-required |
boolean | false |
Error if a .env file isn't found. |
export |
boolean | false |
Export all variables as environment variables. |
fallback |
boolean | false |
Search justfile in parent directory if the first recipe on the command line is not found. |
ignore-comments |
boolean | false |
Ignore recipe lines beginning with #. |
positional-arguments |
boolean | false |
Pass positional arguments. |
quiet |
boolean | false |
Disable echoing recipe lines before executing. |
script-interpreter1.33.0 |
[COMMAND, ARGSβ¦] |
['sh', '-eu'] |
Set command used to invoke recipes with empty [script] attribute. |
shell |
[COMMAND, ARGSβ¦] |
- | Set command used to invoke recipes and evaluate backticks. |
tempdir |
string | - | Create temporary directories in tempdir instead of the system default temporary directory. |
unstable1.31.0 |
boolean | false |
Enable unstable features. |
windows-powershell |
boolean | false |
Use PowerShell on Windows as default shell. (Deprecated. Use windows-shell instead. |
windows-shell |
[COMMAND, ARGSβ¦] |
- | Set the command used to invoke recipes and evaluate backticks. |
working-directory1.33.0 |
string | - | Set the working directory for recipes and backticks, relative to the default working directory. |
Boolean settings can be written as:
set NAMEWhich is equivalent to:
set NAME := trueIf allow-duplicate-recipes is set to true, defining multiple recipes with
the same name is not an error and the last definition is used. Defaults to
false.
set allow-duplicate-recipes
@foo:
echo foo
@foo:
echo bar$ just foo
barIf allow-duplicate-variables is set to true, defining multiple variables
with the same name is not an error and the last definition is used. Defaults to
false.
set allow-duplicate-variables
a := "foo"
a := "bar"
@foo:
echo {{a}}$ just foo
barIf any of dotenv-load, dotenv-filename, dotenv-path, or dotenv-required
are set, just will try to load environment variables from a file.
If dotenv-path is set, just will look for a file at the given path, which
may be absolute, or relative to the working directory.
The command-line option --dotenv-path, short form -E, can be used to set or
override dotenv-path at runtime.
If dotenv-filename is set just will look for a file at the given path,
relative to the working directory and each of its ancestors.
If dotenv-filename is not set, but dotenv-load or dotenv-required are
set, just will look for a file named .env, relative to the working directory
and each of its ancestors.
dotenv-filename and dotenv-path are similar, but dotenv-path is only
checked relative to the working directory, whereas dotenv-filename is checked
relative to the working directory and each of its ancestors.
It is not an error if an environment file is not found, unless
dotenv-required is set.
The loaded variables are environment variables, not just variables, and so
must be accessed using $VARIABLE_NAME in recipes and backticks.
For example, if your .env file contains:
# a comment, will be ignored
DATABASE_ADDRESS=localhost:6379
SERVER_PORT=1337And your justfile contains:
set dotenv-load
serve:
@echo "Starting server with database $DATABASE_ADDRESS on port $SERVER_PORTβ¦"
./server --database $DATABASE_ADDRESS --port $SERVER_PORTjust serve will output:
$ just serve
Starting server with database localhost:6379 on port 1337β¦
./server --database $DATABASE_ADDRESS --port $SERVER_PORTThe export setting causes all just variables to be exported as environment
variables. Defaults to false.
set export
a := "hello"
@foo b:
echo $a
echo $b$ just foo goodbye
hello
goodbyeIf positional-arguments is true, recipe arguments will be passed as
positional arguments to commands. For linewise recipes, argument $0 will be
the name of the recipe.
For example, running this recipe:
set positional-arguments
@foo bar:
echo $0
echo $1Will produce the following output:
$ just foo hello
foo
helloWhen using an sh-compatible shell, such as bash or zsh, $@ expands to
the positional arguments given to the recipe, starting from one. When used
within double quotes as "$@", arguments including whitespace will be passed
on as if they were double-quoted. That is, "$@" is equivalent to "$1" "$2"β¦
When there are no positional parameters, "$@" and $@ expand to nothing
(i.e., they are removed).
This example recipe will print arguments one by one on separate lines:
set positional-arguments
@test *args='':
bash -c 'while (( "$#" )); do echo - $1; shift; done' -- "$@"Running it with two arguments:
$ just test foo "bar baz"
- foo
- bar bazPositional arguments may also be turned on on a per-recipe basis with the
[positional-arguments] attribute1.29.0:
[positional-arguments]
@foo bar:
echo $0
echo $1Note that PowerShell does not handle positional arguments in the same way as other shells, so turning on positional arguments will likely break recipes that use PowerShell.
If using PowerShell 7.4 or better, the -CommandWithArgs flag will make
positional arguments work as expected:
set shell := ['pwsh.exe', '-CommandWithArgs']
set positional-arguments
print-args a b c:
Write-Output @($args[1..($args.Count - 1)])The shell setting controls the command used to invoke recipe lines and
backticks. Shebang recipes are unaffected. The default shell is sh -cu.
# use python3 to execute recipe lines and backticks
set shell := ["python3", "-c"]
# use print to capture result of evaluation
foos := `print("foo" * 4)`
foo:
print("Snake snake snake snake.")
print("{{foos}}")just passes the command to be executed as an argument. Many shells will need
an additional flag, often -c, to make them evaluate the first argument.
just uses sh on Windows by default. To use a different shell on Windows,
use windows-shell:
set windows-shell := ["powershell.exe", "-NoLogo", "-Command"]
hello:
Write-Host "Hello, world!"See powershell.just for a justfile that uses PowerShell on all platforms.
set windows-powershell uses the legacy powershell.exe binary, and is no
longer recommended. See the windows-shell setting above for a more flexible
way to control which shell is used on Windows.
just uses sh on Windows by default. To use powershell.exe instead, set
windows-powershell to true.
set windows-powershell := true
hello:
Write-Host "Hello, world!"set shell := ["python3", "-c"]set shell := ["bash", "-uc"]set shell := ["zsh", "-uc"]set shell := ["fish", "-c"]set shell := ["nu", "-c"]If you want to change the default table mode to light:
set shell := ['nu', '-m', 'light', '-c']Nushell was written in Rust, and has cross-platform support for Windows / macOS and Linux.
Comments immediately preceding a recipe will appear in just --list:
# build stuff
build:
./bin/build
# test stuff
test:
./bin/test$ just --list
Available recipes:
build # build stuff
test # test stuffThe [doc] attribute can be used to set or suppress a recipe's doc comment:
# This comment won't appear
[doc('Build stuff')]
build:
./bin/build
# This one won't either
[doc]
test:
./bin/test$ just --list
Available recipes:
build # Build stuff
testVarious operators and function calls are supported in expressions, which may be
used in assignments, default recipe arguments, and inside recipe body {{β¦}}
substitutions.
tmpdir := `mktemp -d`
version := "0.2.7"
tardir := tmpdir / "awesomesauce-" + version
tarball := tardir + ".tar.gz"
config := quote(config_dir() / ".project-config")
publish:
rm -f {{tarball}}
mkdir {{tardir}}
cp README.md *.c {{ config }} {{tardir}}
tar zcvf {{tarball}} {{tardir}}
scp {{tarball}} me@server.com:release/
rm -rf {{tarball}} {{tardir}}The + operator returns the left-hand argument concatenated with the
right-hand argument:
foobar := 'foo' + 'bar'The logical operators && and || can be used to coalesce string
values1.37.0, similar to Python's and and or. These operators
consider the empty string '' to be false, and all other strings to be true.
These operators are currently unstable.
The && operator returns the empty string if the left-hand argument is the
empty string, otherwise it returns the right-hand argument:
foo := '' && 'goodbye' # ''
bar := 'hello' && 'goodbye' # 'goodbye'The || operator returns the left-hand argument if it is non-empty, otherwise
it returns the right-hand argument:
foo := '' || 'goodbye' # 'goodbye'
bar := 'hello' || 'goodbye' # 'hello'The / operator can be used to join two strings with a slash:
foo := "a" / "b"$ just --evaluate foo
a/b
Note that a / is added even if one is already present:
foo := "a/"
bar := foo / "b"$ just --evaluate bar
a//b
Absolute paths can also be constructed1.5.0:
foo := / "b"$ just --evaluate foo
/b
The / operator uses the / character, even on Windows. Thus, using the /
operator should be avoided with paths that use universal naming convention
(UNC), i.e., those that start with \?, since forward slashes are not
supported with UNC paths.
To write a recipe containing {{, use {{{{:
braces:
echo 'I {{{{LOVE}} curly braces!'(An unmatched }} is ignored, so it doesn't need to be escaped.)
Another option is to put all the text you'd like to escape inside of an interpolation:
braces:
echo '{{'I {{LOVE}} curly braces!'}}'Yet another option is to use {{ "{{" }}:
braces:
echo 'I {{ "{{" }}LOVE}} curly braces!''single', "double", and '''triple''' quoted string literals are
supported. Unlike in recipe bodies, {{β¦}} interpolations are not supported
inside strings.
Double-quoted strings support escape sequences:
carriage-return := "\r"
double-quote := "\""
newline := "\n"
no-newline := "\
"
slash := "\\"
tab := "\t"
unicode-codepoint := "\u{1F916}"$ just --evaluate
"arriage-return := "
double-quote := """
newline := "
"
no-newline := ""
slash := "\"
tab := " "
unicode-codepoint := "π€"The unicode character escape sequence \u{β¦}1.36.0 accepts up to
six hex digits.
Strings may contain line breaks:
single := '
hello
'
double := "
goodbye
"Single-quoted strings do not recognize escape sequences:
escapes := '\t\n\r\"\\'$ just --evaluate
escapes := "\t\n\r\"\\"Indented versions of both single- and double-quoted strings, delimited by triple single- or double-quotes, are supported. Indented string lines are stripped of a leading line break, and leading whitespace common to all non-blank lines:
# this string will evaluate to `foo\nbar\n`
x := '''
foo
bar
'''
# this string will evaluate to `abc\n wuv\nxyz\n`
y := """
abc
wuv
xyz
"""Similar to unindented strings, indented double-quoted strings process escape sequences, and indented single-quoted strings ignore escape sequences. Escape sequence processing takes place after unindentation. The unindentation algorithm does not take escape-sequence produced whitespace or newlines into account.
Strings prefixed with x are shell expanded1.27.0:
foobar := x'~/$FOO/${BAR}'| Value | Replacement |
|---|---|
$VAR |
value of environment variable VAR |
${VAR} |
value of environment variable VAR |
${VAR:-DEFAULT} |
value of environment variable VAR, or DEFAULT if VAR is not set |
Leading ~ |
path to current user's home directory |
Leading ~USER |
path to USER's home directory |
This expansion is performed at compile time, so variables from .env files and
exported just variables cannot be used. However, this allows shell expanded
strings to be used in places like settings and import paths, which cannot
depend on just variables and .env files.
Normally, if a command returns a non-zero exit status, execution will stop. To
continue execution after a command, even if it fails, prefix the command with
-:
foo:
-cat foo
echo 'Done!'$ just foo
cat foo
cat: foo: No such file or directory
echo 'Done!'
Done!just provides many built-in functions for use in expressions, including
recipe body {{β¦}} substitutions, assignments, and default parameter values.
All functions ending in _directory can be abbreviated to _dir. So
home_directory() can also be written as home_dir(). In addition,
invocation_directory_native() can be abbreviated to
invocation_dir_native().
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 machineThe 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.
-
shell(command, args...)1.27.0 returns the standard output of shell scriptcommandwith zero or more positional argumentsargs. The shell used to interpretcommandis the same shell that is used to evaluate recipe lines, and can be changed withset shell := [β¦].commandis passed as the first argument, so if the command is'echo $@', the full command line, with the default shell commandsh -cuandargs'foo'and'bar'will be:'sh' '-cu' 'echo $@' 'echo $@' 'foo' 'bar'This is so that
$@works as expected, and$1refers 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')env(key)1.15.0 β Retrieves the environment variable with namekey, aborting if it is not present.
home_dir := env('HOME')
test:
echo "{{home_dir}}"$ just
/home/user1env(key, default)1.15.0 β Retrieves the environment variable with namekey, returningdefaultif it is not present.env_var(key)β Deprecated alias forenv(key).env_var_or_default(key, default)β Deprecated alias forenv(key, default).
A default can be substituted for an empty environment variable value with the
|| operator, currently unstable:
set unstable
foo := env('FOO') || 'DEFAULT_VALUE'-
require(name)1.39.0 β Search directories in thePATHenvironment variable for the executablenameand return its full path, or halt with an error if no executable withnameexists.bash := require("bash") @test: echo "bash: '{{bash}}'"
$ just bash: '/bin/bash'
-
which(name)1.39.0 β Search directories in thePATHenvironment variable for the executablenameand return its full path, or the empty string if no executable withnameexists. Currently unstable.set unstable bosh := which("bosh") @test: echo "bosh: '{{bosh}}'"
$ just bosh: ''
is_dependency()- Returns the stringtrueif the current recipe is being run as a dependency of another recipe, rather than being run directly, otherwise returns the stringfalse.
invocation_directory()- Retrieves the absolute path to the current directory whenjustwas invoked, beforejustchanged it (chdir'd) prior to executing commands. On Windows,invocation_directory()usescygpathto convert the invocation directory to a Cygwin-compatible/-separated path. Useinvocation_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_hereinvocation_directory_native()- Retrieves the absolute path to the current directory whenjustwas invoked, beforejustchanged it (chdir'd) prior to executing commands.
-
justfile()- Retrieves the path of the currentjustfile. -
justfile_directory()- Retrieves the path of the parent directory of the currentjustfile.
For example, to run a command relative to the location of the current
justfile:
script:
{{justfile_directory()}}/scripts/some_script-
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.
just_executable()- Absolute path to thejustexecutable.
For example:
executable:
@echo The executable is at: {{just_executable()}}$ just
The executable is at: /bin/justjust_pid()- Process ID of thejustexecutable.
For example:
pid:
@echo The process ID is: {{ just_pid() }}$ just
The process ID is: 420append(suffix, s)1.27.0 Appendsuffixto whitespace-separated strings ins.append('/src', 'foo bar baz')β'foo/src bar/src baz/src'prepend(prefix, s)1.27.0 Prependprefixto whitespace-separated strings ins.prepend('src/', 'foo bar baz')β'src/foo src/bar src/baz'encode_uri_component(s)1.27.0 - Percent-encode characters insexcept[A-Za-z0-9_.!~*'()-], matching the behavior of the JavaScriptencodeURIComponentfunction.quote(s)- Replace all single quotes with'\''and prepend and append single quotes tos. This is sufficient to escape special characters for many shells, including most Bourne shell descendants.replace(s, from, to)- Replace all occurrences offrominstoto.replace_regex(s, regex, replacement)- Replace all occurrences ofregexinstoreplacement. Regular expressions are provided by the Rustregexcrate. See the syntax documentation for usage examples. Capture groups are supported. Thereplacementstring uses Replacement string syntax.trim(s)- Remove leading and trailing whitespace froms.trim_end(s)- Remove trailing whitespace froms.trim_end_match(s, substring)- Remove suffix ofsmatchingsubstring.trim_end_matches(s, substring)- Repeatedly remove suffixes ofsmatchingsubstring.trim_start(s)- Remove leading whitespace froms.trim_start_match(s, substring)- Remove prefix ofsmatchingsubstring.trim_start_matches(s, substring)- Repeatedly remove prefixes ofsmatchingsubstring.
capitalize(s)1.7.0 - Convert first character ofsto uppercase and the rest to lowercase.kebabcase(s)1.7.0 - Convertstokebab-case.lowercamelcase(s)1.7.0 - ConvertstolowerCamelCase.lowercase(s)- Convertsto lowercase.shoutykebabcase(s)1.7.0 - ConvertstoSHOUTY-KEBAB-CASE.shoutysnakecase(s)1.7.0 - ConvertstoSHOUTY_SNAKE_CASE.snakecase(s)1.7.0 - Convertstosnake_case.titlecase(s)1.7.0 - ConvertstoTitle Case.uppercamelcase(s)1.7.0 - ConvertstoUpperCamelCase.uppercase(s)- Convertsto uppercase.
absolute_path(path)- Absolute path to relativepathin the working directory.absolute_path("./bar.txt")in directory/foois/foo/bar.txt.canonicalize(path)1.24.0 - Canonicalizepathby resolving symlinks and removing.,.., and extra/s where possible.extension(path)- Extension ofpath.extension("/foo/bar.txt")istxt.file_name(path)- File name ofpathwith any leading directory components removed.file_name("/foo/bar.txt")isbar.txt.file_stem(path)- File name ofpathwithout extension.file_stem("/foo/bar.txt")isbar.parent_directory(path)- Parent directory ofpath.parent_directory("/foo/bar.txt")is/foo.without_extension(path)-pathwithout 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.
clean(path)- Simplifypathby removing extra path separators, intermediate.components, and..where possible.clean("foo//bar")isfoo/bar,clean("foo/..")is.,clean("foo/./bar")isfoo/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 pathawith pathb.join("foo/bar", "baz")isfoo/bar/baz. Accepts two or more arguments.
path_exists(path)- Returnstrueif the path points at an existing entity andfalseotherwise. Traverses symbolic links, and returnsfalseif the path is inaccessible or points to a broken symlink.read(path)1.39.0 - Returns the content of file atpathas string.