Runic.jl

A code formatter with rules set in stone.

Runic is a formatter for the Julia programming language built on top of JuliaSyntax.jl.

Similarly to gofmt, Runic have no configuration. The formatting rules are set in stone (although not yet complete). This approach is something that is appreciated by most Go programmers, see for example the following quote:

Gofmt's style is no one's favorite, yet gofmt is everyone's favorite.

Table of contents

• Quick start
• Installation
• Usage
  • CLI
  • Editor integration
  • Git integration
  • Adopting Runic formatting
    • Ignore formatting commits in git blame
    • Badge
• Checking formatting
  • Github Actions
  • Git hooks
• Version policy
• Formatting specification

Quick start

Copy-pasteable setup commands for the impatient:

# Install Runic
julia --project=@runic --startup-file=no -e 'using Pkg; Pkg.add("Runic")'
# Install the runic shell script
curl -fsSL -o ~/.local/bin/runic https://raw.githubusercontent.com/fredrikekre/Runic.jl/refs/heads/master/bin/runic
chmod +x ~/.local/bin/runic
# Install the git-runic shell script
curl -fsSL -o ~/.local/bin/git-runic https://raw.githubusercontent.com/fredrikekre/Runic.jl/refs/heads/master/bin/git-runic
chmod +x ~/.local/bin/git-runic

Assuming ~/.local/bin is in your PATH you can now invoke runic, e.g.:

runic --version # Show version info
runic --help    # Show documentation

# Format all files in-place in the current directory (recursively)
# !! DON'T DO THIS FROM YOUR HOME DIRECTORY !!
runic --inplace .

Installation

Runic can be installed with Julia's package manager:

julia --startup-file=no -e 'using Pkg; Pkg.add("Runic")'

For CLI usage and editor integration (see Usage) it is recommended to install Runic in a separate project such as e.g. the shared project @runic:

julia --project=@runic --startup-file=no -e 'using Pkg; Pkg.add("Runic")'

The main interface to Runic is the command line interface (CLI) through the main function:

julia --project=@runic --startup-file=no -e 'using Runic; exit(Runic.main(ARGS))' -- <args>

To simplify the invocation of the CLI it is recommended to install the runic shell script into a directory in your PATH. This can be done with the following commands (replace the two occurrences of ~/.local/bin if needed):

# Download the script into ~/.local/bin
curl -fsSL -o ~/.local/bin/runic https://raw.githubusercontent.com/fredrikekre/Runic.jl/refs/heads/master/bin/runic
# Make the script executable
chmod +x ~/.local/bin/runic
# Verify the installation
runic --version

[!NOTE] Alternatively you can can add a shell alias to your shell startup file. The drawback of this approach is that runic can only be invoked from the shell and not by other programs.

alias runic="julia --project=@runic --startup-file=no -e 'using Runic; exit(Runic.main(ARGS))' --"
# alias runic="julia --project=@runic --startup-file=no -m Runic"

[!NOTE] In Julia 1.12 and later the main function can be invoked with the -m flag, i.e.:

julia --project=@runic --startup-file=no -m Runic <args>

Usage

CLI

The CLI is the main interface to Runic. runic --help will show all available options (output included below). Some example invocations are listed here.

Format a single file in place:

runic --inplace file.jl

Format all files in a directory (recursively) in place:

runic --inplace src/

Verify formatting of all files in a directory with verbose and diff output:

runic --check --diff --verbose src/

Format the content of standard in and print the result to standard out:

echo "1+1" | runic

Output of runic --help for a complete list of options:

$ runic --help
NAME
       Runic.main - format Julia source code

SYNOPSIS
       julia -m Runic [<options>] <path>...

DESCRIPTION
       `Runic.main` (typically invoked as `julia -m Runic`) formats Julia source
       code using the Runic.jl formatter.

OPTIONS
       <path>...
           Input path(s) (files and/or directories) to process. For directories,
           all files (recursively) with the '*.jl' suffix are used as input files.
           If no path is given, or if path is `-`, input is read from stdin.

       -c, --check
           Do not write output and exit with a non-zero code if the input is not
           formatted correctly.

       -d, --diff
           Print the diff between the input and formatted output to stderr.
           Requires `git` to be installed.

       --help
           Print this message.

       -i, --inplace
           Format files in place.

       --lines=<start line>:<end line>
           Limit formatting to the line range <start line> to <end line>. Multiple
           ranges can be formatted by specifying multiple --lines arguments.

       -o <file>, --output=<file>
           File to write formatted output to. If no output is given, or if the file
           is `-`, output is written to stdout.

       -v, --verbose
           Enable verbose output.

       --version
           Print Runic and julia version information.

In addition to the CLI there is also the two function Runic.format_file and Runic.format_string. See their respective docstrings for details.

Editor integration

Most code editors have code formatting capabilities and many can be configured to use Runic. Example configuration for some editors are given in the following sections.

• Neovim
• VS Code
• Emacs
• Helix
• Zed

[!IMPORTANT] Note that these configurations depend on third party plugins. They works as advertised but use it at your own risk.

Neovim

Runic can be used as a formatter in Neovim using conform.nvim. Refer to the conform.nvim repository for installation and setup instructions.

Runic is not (yet) available directly in conform so the following configuration needs to be passed to the setup function. This assumes Runic is installed in the @runic shared project as suggested in the Installation section above. Adjust the --project flag if you installed Runic somewhere else.

require("conform").setup({
    formatters = {
        runic = {
            command = "julia",
            args = {"--project=@runic", "--startup-file=no", "-e", "using Runic; exit(Runic.main(ARGS))"},
        },
    },
    formatters_by_ft = {
        julia = {"runic"},
    },
    default_format_opts = {
        -- Increase the timeout in case Runic needs to precompile
        -- (e.g. after upgrading Julia and/or Runic).
        timeout_ms = 10000,
    },
})

Note that conform (and thus Runic) can be used as formatexpr for the gq command. This is enabled by adding the following to your configuration:

vim.o.formatexpr = "v:lua.require('conform').formatexpr()"

VS Code

Runic can be used as a formatter in VS Code using the extension Custom Local Formatters.

After installing the extension you can configure Runic as a local formatter by adding the following entry to your settings.json. This assumes Runic is installed in the @runic shared project as suggested in the Installation section above. Adjust the --project flag if you installed Runic somewhere else.

"customLocalFormatters.formatters": [
    {
      "command": "julia --project=@runic --startup-file=no -e 'using Runic; exit(Runic.main(ARGS))'",
      "languages": ["julia"]
    }
]

Using the "Format Document" VS Code command will now format the file using Runic. Note that the first time you execute the command you will be prompted to select a formatter since the Julia language extension also comes with a formatter.

[!NOTE] If you've installed Julia with juliaup, the julia executable might not be available in PATH within VS Code, causing formatting to fail. In that case, you can find the full path of the julia executable using which julia (typically something like ${HOME}/.juliaup/bin/julia with default juliaup settings), and then replace julia in the command in settings.json with the full path.

Emacs

Runic can be used as a formatter in Emacs using apheleia. Refer to the apheleia repository for installation and setup instruction.

Runic is not (yet) available directly in apheleia so the following configuration needs to be added to your .emacs. This assumes Runic is installed in the @runic shared project as suggested in the Installation section above. Adjust the --project flag