A new recent trick I’ve added to my repertoire: justfiles for each branch I work on.

It’s well worth reading int the just task runner, it’s become indispensable for all of my projects. My main use for it is documenting and recording those sequences of ad-hoc steps I occasionally need to do in a project.

But of course, I don’t want to maintain a single massive justfile for every change and branch I do. So I added this script to a new directory called ~/.gitalias:

#!/bin/sh
branch=$(git rev-parse --abbrev-ref HEAD)

branch=$(echo "$branch" | tr '[:upper:]' '[:lower:]')
branch=$(echo "$branch" | sed -E 's/[^a-zA-Z0-9-]+/-/g')
branch=$(echo "$branch" | sed -E 's/^-+//g')
branch=$(echo "$branch" | sed -E 's/-+$//g')

justfile=.$branch.just

if [ ! -f "$justfile" ]; then
    $EDITOR "$justfile"
elif [ "$#" -eq 0 ]; then
    $EDITOR "$justfile"
else
    just -f "$justfile" "${@}"
fi

Then I added this alias to my ~/.gitconfig:

[alias]
    just = "!~/.gitalias/just"

So that git just opens a justfile called .name-of-branch.just in my project directory when called without any args (or if the file doesn’t exist yet). Once I’ve defined some steps, I can execute them immediately by using git just <name-of-step> [args] to select the branch justfile with -f, and pass through all arguments.

If I don’t want to commit these files, I tend to declare them in .git/info/exclude so that they’re only ignored on my local copy of the repo (and I don’t need to declare and commit them to the shared .gitignore)

echo "*.just" >> .git/info/exclude

You can define scripts inline a justfile with a shebang, and use the usual substitution syntax:

my-shell-script my-arg:
    #!/usr/bin/env sh
    echo {{ my-arg }}

my-uv-python-script my-arg:
    #!/usr/bin/env -S uv run --script --quiet
    # /// script
    # requires-python = ">=3.12"
    # dependencies = [
    #     "rich",
    # ]
    # ///
    from rich import print
    print("Hello, [bold magenta]{{ my-arg }}[/bold magenta]!", ":wave:")

You can even “layer” justfiles by importing rules from another justfile (such as the roles for the main branch at .main.just) by adding import '.main.just' at the top of the file opened by git just

Every time I look at the amazing documentation of this tool I seem to learn something new! Thank you for this @casey