Prerequisites

just should run on any system with a reasonablesh, including Linux, MacOS, and the BSDs.

On Windows,just works with thesh provided byGit for Windows,GitHub Desktop, orCygwin.

If you’d rather not installsh, you can use theshell setting to use the shell of your choice.

Like PowerShell:

…orcmd.exe:

(PowerShell is installed by default on Windows 7 SP1 and Windows Server 2008 R2 S1 and later, andcmd.exe is quite fiddly, so PowerShell is recommended for most Windows users.)

Packages

Pre-Built Binaries

Pre-built binaries for Linux, MacOS, and Windows can be found onthe releases page.

You can use the following command on Linux, MacOS, or Windows to download the latest release, just replaceDEST with the directory where you’d like to putjust:

GitHub Actions

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

Example usage:

Release RSS Feed

AnRSS feed ofjust releases is availablehere.

Vim and Neovim

Emacs

There is a MELPA package,just-mode, for automatic Emacs syntax highlighting and automatic indentation in justfiles.

You can add the following to an individual justfile to enablemake mode on a per-file basis:

Visual Studio Code

An extension for VS Code byskellock isavailable here. (repository)

You can install it from the command line by running:

Kakoune

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

Sublime Text

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

Other Editors

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.

Listing Available Recipes

Recipes can be listed in alphabetical order withjust --list:

just --summary is more concise:

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

If you’d likejust to default to listing the recipes in the justfile, you canuse 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 newlinefollowing it, so it should contain a newline if non-empty. It works this way soyou can suppress the heading line entirely by passing the empty string:

Aliases

Aliases allow recipes to be invoked with alternative names:

Settings

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

For example:

Documentation Comments

Comments immediately preceding a recipe will appear injust --list:

Variables and Substitution

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

Strings

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.

Ignoring Errors

Normally, if a command returns a non-zero exit status, execution will stop. Tocontinue execution after a command, even if it fails, prefix the command with-:

Functions

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

Command Evaluation Using Backticks

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 theStrings section for details on unindenting.

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

Conditional Expressions

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

It is also possible to test for inequality:

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

Conditionals can be used inside of recipes:

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

Multiple conditionals can be chained:

Setting Variables from the Command Line

Variables can be overridden from the command line.

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

Or you can use the--set flag:

Environment Variables

Assignments prefixed with theexport 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.

Recipe Parameters

Recipes may have parameters. Here recipebuild has a parameter calledtarget:

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+ acceptone or more arguments and expand to a string containing those arguments separated by spaces:

Variadic parameters prefixed with* acceptzero 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 commandlynxhttps://www.google.com/?q=cat toupee, which will get parsed bysh aslynx,https://www.google.com/?q=cat, andtoupee, and not the intendedlynx andhttps://www.google.com/?q=cat toupee.

You can fix this by adding quotes:

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

Running Recipes at the End of a Recipe

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:

Running Recipes in the Middle of a Recipe

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

…running 'b' prints:

This has limitations, since recipec is run with an entirely new invocation ofjust: Assignments will be recalculated, dependencies might run twice, and command line arguments will not be propagated to the childjust process.

Writing Recipes in Other Languages

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

Safer Bash Shebang Recipes

If you’re writing abash shebang recipe, consider addingset -euxo pipefail:

It isn’t strictly necessary, butset -euxo pipefail turns on a few usefulfeatures that makebash shebang recipes behave more like normal, linewisejustrecipe:

• set -e makesbash exit if a command fails.

• set -u makesbash exit if a variable is undefined.

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

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

Together, these avoid a lot of shell scripting gotchas.

Setting Variables in a Recipe

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

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

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

Changing the Working Directory in a Recipe

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

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

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

Multi-Line Constructs

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

Command Line Options

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

Runjust --help to see all the options.

Private Recipes

Recipes and aliases whose name starts with a_ are omitted fromjust --list:

And fromjust --summary:

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

Quiet 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 makesjust print the recipe before executing it:

Selecting Recipes to Run With an Interactive Chooser

The--choose subcommand makesjust invoke a chooser to select which recipesto run. Choosers should read lines containing recipe names from standard inputand 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 andaliases are also skipped.

The chooser can be overridden with the--chooser flag. If--chooser is notgiven, thenjust first checks if$JUST_CHOOSER is set. If it isn’t, thenthe chooser defaults tofzf, 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 thechooser isfzf, it will be invoked withsh -cu 'fzf', and if the shell, orthe shell arguments are overridden, the chooser invocation will respect thoseoverrides.

If you’d likejust to default to selecting recipes with a chooser, you canuse this as your default recipe:

Invoking Justfiles in Other Directories

If the first argument passed tojust 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 namedfoo, which contains a justfile with the recipebuild, which is also the default recipe, the following are all equivalent:

Hiding Justfiles

just looks for justfiles namedjustfile and.justfile, which can be used to keep ajustfile hidden.

Just Scripts

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

Changelog

A changelog for the latest release is available inCHANGELOG.md. Changelogs for previous releases are avaiable onthe releases page.just --changelog can also be used to make ajust binary print its changelog.

Companion Tools

Tools that pair nicely withjust include:

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

Shell Alias

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

Shell Completion Scripts

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

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

Grammar

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

just.sh

Beforejust was a fancy Rust program it was a tiny shell script that calledmake. You can find the old version inextras/just.sh.

Non-Project Specific Justfile

If you want some commands to be available everywhere, put them in~/.global.justfile and add the following to your shell’s initialization file:

Or, if you’d rather they run in the current directory:

I’m pretty sure that nobody actually uses this feature, but it’s there.

¯\_(ツ)_/¯

Janus

Janus is a tool that collects and analyzes justfiles, and can determine if a new version ofjust 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.

What are the idiosyncrasies of Make that Just avoids?

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 calledtest and the following makefile:

make will refuse to run your tests:

make assumes that thetest recipe produces a file calledtest. 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 usingmake as a build system, but not when using it as a command runner. You can disable this behavior for specific targets usingmake’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. Injust, all recipes are treated as if they were phony.

Other examples ofmake’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 ofmake.

What’s the relationship between Just and Cargo build scripts?

cargo build scripts have a pretty specific use, which is to control howcargo builds your Rust project. This might include adding flags torustc 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, althoughjust is written in Rust, it can be used regardless of the language or build system your project uses.