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:

…or cmd.exe:

(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.)

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:

For example, to install just to ~/bin:

extractions/setup-just can be used to install just in a GitHub Actions workflow.

Example usage:

An RSS feed of just releases is available here.

vim-just

call plug#begin()

Plug 'NoahTheDuke/vim-just'

call plug#end()

mkdir -p ~/.vim/pack/vendor/start
cd ~/.vim/pack/vendor/start
git clone https://github.com/NoahTheDuke/vim-just.git

tree-sitter-just

Makefile Syntax Highlighting

if exists("did_load_filetypes")
  finish
endif

augroup filetypedetect
  au BufNewFile,BufRead justfile setf make
augroup END

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

An extension for VS Code by skellock is available here. (repository)

You can install it from the command line by running:

Kakoune supports justfile syntax highlighting out of the box, thanks to TeddyDD.

A syntax file for Sublime Text written by TonioGela is available in extras/just.sublime-syntax.

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.

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:

You can also use dependencies to run multiple recipes by default:

If no recipe makes sense as the default recipe, you can add a recipe to the beginning of your justfile that lists the available recipes:

Recipes can be listed in alphabetical order with just --list:

just --summary is more concise:

Pass --unsorted to print recipes in the order they appear in the justfile:

If you’d like just to default to listing the recipes in the justfile, you can use this as your default recipe:

The heading text can be customized with --list-heading:

And the indentation can be customized with --list-prefix:

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

Aliases allow recipes to be invoked with alternative names:

Settings control interpretation and execution. Each setting may be specified at most once, anywhere in the justfile.

For example:

Table of Settings

set NAME

set NAME := true

Dotenv Load

Export

set export

a := "hello"

@foo b:
  echo $a
  echo $b

$ just foo goodbye
hello
goodbye

Positional Arguments

set positional-arguments

@foo bar:
  echo $0
  echo $1

$ just foo hello
foo
hello

Shell

# 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}}")

set shell := ["python3", "-c"]

set shell := ["bash", "-uc"]

set shell := ["zsh", "-uc"]

set shell := ["fish", "-c"]

Comments immediately preceding a recipe will appear in just --list:

Variables, strings, concatenation, and substitution using {{…​}} are supported:

Escaping {{

braces:
    echo 'I {{{{LOVE}} curly braces!'

braces:
    echo '{{'I {{LOVE}} curly braces!'}}'

braces:
    echo 'I {{ "{{" }}LOVE}} curly braces!'

Double-quoted strings support escape sequences:

Strings may contain line breaks:

Single-quoted strings do not recognize escape sequences:

Indented versions of both single- and double-quoted strings, delimited by triple single- or triple double-quotes, are supported. Indented string lines are stripped of leading whitespace common to all non-blank lines:

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 unindention algorithm does not take escape-sequence produced whitespace or newlines into account.

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

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

System Information

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

$ just system-info
This is an x86_64 machine

Environment Variables

Invocation Directory

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

build:
    cd {{invocation_directory()}}; ./some_script_that_needs_to_be_run_from_here

Justfile and Justfile Directory

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

Just Executable

executable:
    @echo The executable is at: {{just_executable()}}

$ just
The executable is at: /bin/just

String Manipulation

Dotenv Integration

# a comment, will be ignored
DATABASE_ADDRESS=localhost:6379
SERVER_PORT=1337

serve:
  @echo "Starting server with database $DATABASE_ADDRESS on port $SERVER_PORT..."
  ./server --database $DATABASE_ADDRESS --port $SERVER_PORT

$ just serve
Starting server with database localhost:6379 on port 1337...
./server --database $DATABASE_ADDRESS --port $SERVER_PORT

Path Manipulation

Backticks can be used to store the result of commands:

Indented backticks, delimited by three backticks, are de-indented in the same manner as indented strings:

See the Strings section for details on unindenting.

Backticks may not start with #!. This syntax is reserved for a future upgrade.

if/else expressions evaluate different branches depending on if two expressions evaluate to the same value:

It is also possible to test for inequality:

And match against regular expressions:

Regular expressions are provided by the regex crate, whose syntax is documented on docs.rs. Since regular expressions commonly use backslash escape sequences, consider using single-quoted string literals, which will pass slashes to the regex parser unmolested.

Conditional expressions short-circuit, which means they only evaluate one of their branches. This can be used to make sure that backtick expressions don’t run when they shouldn’t.

Conditionals can be used inside of recipes:

Note the space after the final }! Without the space, the interpolation will be prematurely closed.

Multiple conditionals can be chained:

Variables can be overridden from the command line.

Any number of arguments of the form NAME=VALUE can be passed before recipes:

Or you can use the --set flag:

Assignments prefixed with the export keyword will be exported to recipes as environment variables:

Parameters prefixed with a $ will be exported as environment variables:

Exported variables and parameters are not exported to backticks in the same scope.

Recipes may have parameters. Here recipe build has a parameter called target:

To pass arguments on the command line, put them after the recipe name:

To pass arguments to a dependency, put the dependency in parentheses along with the arguments:

Parameters may have default values:

Parameters with default values may be omitted:

Or supplied:

Default values may be arbitrary expressions, but concatenations must be parenthesized:

The last parameter of a recipe may be variadic, indicated with either a + or a * before the argument name:

Variadic parameters prefixed with + accept one or more arguments and expand to a string containing those arguments separated by spaces:

Variadic parameters prefixed with * accept zero or more arguments and expand to a string containing those arguments separated by spaces, or an empty string if no arguments are present:

Variadic parameters can be assigned default values. These are overridden by arguments passed on the command line:

{{…​}} substitutions may need to be quoted if they contain spaces. For example, if you have the following recipe:

And you type:

just will run the command lynx https://www.google.com/?q=cat toupee, which will get parsed by sh as lynx, https://www.google.com/?q=cat, and toupee, and not the intended lynx and https://www.google.com/?q=cat toupee.

You can fix this by adding quotes:

Parameters prefixed with a $ will be exported as environment variables:

Normal dependencies of a recipes always run before a recipe starts. That is to say, the dependee always runs before the depender. These dependencies are called "prior dependencies".

A recipe can also have subsequent dependencies, which run after the recipe and are introduced with an &&:

…running 'b' prints:

just doesn’t support running recipes in the middle of another recipe, but you can call just recursively in the middle of a recipe. Given the following justfile:

…running 'b' prints:

This has limitations, since recipe c is run with an entirely new invocation of just: Assignments will be recalculated, dependencies might run twice, and command line arguments will not be propagated to the child just process.

Recipes that start with a #! are executed as scripts, so you can write recipes in other languages:

If you’re writing a bash shebang recipe, consider adding set -euxo pipefail:

It isn’t strictly necessary, but set -euxo pipefail turns on a few useful features that make bash shebang recipes behave more like normal, linewise just recipe:

• set -e makes bash exit if a command fails.

• set -u makes bash exit if a variable is undefined.

• set -x makes bash print each script line before it’s run.

• set -o pipefail makes bash exit if a command in a pipeline fails.

Together, these avoid a lot of shell scripting gotchas.

Shebang Recipe Execution on Windows

echo:
  #!/bin/sh

  echo "Hello!"

Recipe lines are interpreted by the shell, not just, so it’s not possible to set just variables in the middle of a recipe:

It is possible to use shell variables, but there’s another problem. Every recipe line is run by a new shell instance, so variables set in one line won’t be set in the next:

The best way to work around this is to use a shebang recipe. Shebang recipe bodies are extracted and run as scripts, so a single shell instance will run the whole thing:

Each recipe line is executed by a new shell, so if you change the working directory on one line, it won’t have an effect on later lines:

There are a couple ways around this. One is to call cd on the same line as the command you want to run:

The other is to use a shebang recipe. Shebang recipe bodies are extracted and run as scripts, so a single shell instance will run the whole thing, and thus a pwd on one line will affect later lines, just like a shell script:

Recipes without an initial shebang are evaluated and run line-by-line, which means that multi-line constructs probably won’t do what you want.

For example, with the following justfile:

The extra leading whitespace before the second line of the conditional recipe will produce a parse error:

To work around this, you can write conditionals on one line, escape newlines with slashes, or add a shebang to your recipe. Some examples of multi-line constructs are provided for reference.

if statements

conditional:
    if true; then echo 'True!'; fi

conditional:
    if true; then \
        echo 'True!'; \
    fi

conditional:
    #!/usr/bin/env sh
    if true; then
        echo 'True!'
    fi

for loops

for:
    for file in `ls .`; do echo $file; done

for:
    for file in `ls .`; do \
        echo $file; \
    done

for:
    #!/usr/bin/env sh
    for file in `ls .`; do
        echo $file
    done

while loops

while:
    while `server-is-dead`; do ping -c 1 server; done

while:
    while `server-is-dead`; do \
        ping -c 1 server; \
    done

while:
    #!/usr/bin/env sh
    while `server-is-dead`; do
        do ping -c 1 server
    done

just supports a number of useful command line options for listing, dumping, and debugging recipes and variable:

Run just --help to see all the options.

Recipes and aliases whose name starts with a _ are omitted from just --list:

And from just --summary:

This is useful for helper recipes which are only meant to be used as dependencies of other recipes.

A recipe name may be prefixed with '@' to invert the meaning of '@' before each line:

Now only the lines starting with '@' will be echoed:

Shebang recipes are quiet by default:

Adding @ to a shebang recipe name makes just print the recipe before executing it:

The --choose subcommand makes just invoke a chooser to select which recipes to run. Choosers should read lines containing recipe names from standard input and print one or more of those names separated by spaces to standard output.

Because there is currently no way to run a recipe that requires arguments with --choose, such recipes will not be given to the chooser. Private recipes and aliases are also skipped.

The chooser can be overridden with the --chooser flag. If --chooser is not given, then just first checks if $JUST_CHOOSER is set. If it isn’t, then the chooser defaults to fzf, a popular fuzzy finder.

Arguments can be included in the chooser, i.e. fzf --exact.

The chooser is invoked in the same way as recipe lines. For example, if the chooser is fzf, it will be invoked with sh -cu 'fzf', and if the shell, or the shell arguments are overridden, the chooser invocation will respect those overrides.

If you’d like just to default to selecting recipes with a chooser, you can use this as your default recipe:

If the first argument passed to just contains a /, then the following occurs:

1. The argument is split at the last /.

2. The part before the last / is treated as a directory. just will start its search for the justfile there, instead of in the current directory.

3. The part after the last slash is treated as a normal argument, or ignored if it is empty.

This may seem a little strange, but it’s useful if you wish to run a command in a justfile that is in a subdirectory.

For example, if you are in a directory which contains a subdirectory named foo, which contains a justfile with the recipe build, which is also the default recipe, the following are all equivalent:

just looks for justfiles named justfile and .justfile, which can be used to keep a justfile hidden.

By adding a shebang line to the top of a justfile and making it executable, just can be used as an interpreter for scripts:

When a script with a shebang is executed, the system supplies the path to the script as an argument to the command in the shebang. So, with a shebang of #!/usr/bin/env just --justfile, the command will be /usr/bin/env just --justfile PATH_TO_SCRIPT.

With the above shebang, just will change its working directory to the location of the script. If you’d rather leave the working directory unchanged, use #!/usr/bin/env just --working-directory . --justfile.

Note: Shebang line splitting is not consistent across operating systems. The previous examples have only been tested on macOS. On Linux, you may need to pass the -S flag to env:

The --dump command can be used with --dump-format json to print a JSON representation of a justfile. The JSON format is currently unstable, so the --unstable flag is required.

A changelog for the latest release is available in CHANGELOG.md. Changelogs for previous releases are available on the releases page. just --changelog can also be used to make a just binary print its changelog.

Tools that pair nicely with just include:

• watchexec — a simple tool that watches a path and runs a command whenever it detects modifications.

For lightning-fast command running, put alias j=just in your shell’s configuration file.

In bash, the aliased command may not keep the shell completion functionality described in the next section. Add the following line to your .bashrc to use the same completion function as just for your aliased command:

Shell completion scripts for Bash, Zsh, Fish, PowerShell, and Elvish are available in the completions directory. Please refer to your shell’s documentation for how to install them.

The just binary can also generate the same completion scripts at runtime, using the --completions command:

A non-normative grammar of justfiles can be found in GRAMMAR.md.

Before just was a fancy Rust program it was a tiny shell script that called make. You can find the old version in extras/just.sh.

If you want some recipes to be available everywhere, you have a few options.

First, create a justfile in ~/.user.justfile with some recipes.

Recipe Aliases

for recipe in `just --justfile ~/.user.justfile --summary`; do
  alias $recipe="just --justfile ~/.user.justfile --working-directory . $recipe"
done

Forwarding Alias

alias .j='just --justfile ~/.user.justfile --working-directory .'

Customization

alias .j='just --justfile ~/.user.justfile --working-directory ~'

There is no shortage of command runners out there! Some more or less similar alternatives to just include:

• [mmake](https://github.com/tj/mmake): A wrapper around make with a number of improvements, including remote includes.

• [robo](https://github.com/tj/robo): A YAML-based command runner written in Go.

Janus is a tool that collects and analyzes justfiles, and can determine if a new version of just breaks or changes the interpretation of existing justfiles.

Before merging a particularly large or gruesome change, Janus should be run to make sure that nothing breaks. Don’t worry about running Janus yourself, Casey will happily run it for you on changes that need it.

The minimum supported Rust version, or MSRV, is Rust 1.47.0.

make has some behaviors which are confusing, complicated, or make it unsuitable for use as a general command runner.

One example is that under some circumstances, make won’t actually run the commands in a recipe. For example, if you have a file called test and the following makefile:

make will refuse to run your tests:

make assumes that the test recipe produces a file called test. Since this file exists and the recipe has no other dependencies, make thinks that it doesn’t have anything to do and exits.

To be fair, this behavior is desirable when using make as a build system, but not when using it as a command runner. You can disable this behavior for specific targets using make's built-in .PHONY target name, but the syntax is verbose and can be hard to remember. The explicit list of phony targets, written separately from the recipe definitions, also introduces the risk of accidentally defining a new non-phony target. In just, all recipes are treated as if they were phony.

Other examples of make's idiosyncrasies include the difference between = and := in assignments, the confusing error messages that are produced if you mess up your makefile, needing $$ to use environment variables in recipes, and incompatibilities between different flavors of make.

cargo build scripts have a pretty specific use, which is to control how cargo builds your Rust project. This might include adding flags to rustc invocations, building an external dependency, or running some kind of codegen step.

just, on the other hand, is for all the other miscellaneous commands you might run as part of development. Things like running tests in different configurations, linting your code, pushing build artifacts to a server, removing temporary files, and the like.

Also, although just is written in Rust, it can be used regardless of the language or build system your project uses.