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, and Cygwin.

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

Like cmd.exe:

…or Powershell:

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:

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:

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:

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

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

Double-quoted strings support escape sequences:

Single-quoted strings do not recognize escape sequences and may contain line breaks:

Normally, if a command returns a nonzero 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.

Backticks can be used to store the result of commands:

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:

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

Dependencies of a recipes always run before a recipe starts. That is to say, the dependee always runs before the depender.

You can call Just recursively to run a recipe after a recipe ends. Given the following justfile:

…running 'b' prints:

This has some 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:

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.

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 recipe to run. Choosers should read lines containing recipe names from standard input and print one of those names to standard output.

Because there is currenly 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 a recipe 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:

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.

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.

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:

justfile syntax is close enough to make that you may want to tell your editor to use make syntax highlighting for just.

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 commands to be available everywhere, put them in ~/.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 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.

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.