justfmt

A Python-based formatter for justfiles that enforces consistent style and formatting conventions.

Features

• Consistent Indentation: Normalizes all recipe bodies to use spaces (default: 4 spaces)
• Quote Normalization: Converts quotes to a consistent style (double or single)
• Automatic Spacing: Ensures proper spacing around operators (:=, =)
• Alphabetical Sorting: Optional alphabetical sorting of recipes
• Blank Line Management: Maintains consistent spacing between recipes
• Configuration Support: Load settings from justfmt.ini or pyproject.toml
• Check Mode: Verify formatting without making changes (perfect for CI)
• Diff Mode: Preview changes before applying them

Installation

Install as a development dependency using uv:

uv add --dev justfmt

Or with pip:

pip install justfmt

Usage

Basic Usage

Format a justfile in place:

justfmt

This will format the justfile in the current directory using default settings.

Format a specific file:

justfmt path/to/justfile

Check Mode (CI/CD)

Check if a file is formatted without modifying it:

justfmt --check

Exit code will be 1 if formatting is needed, 0 if already formatted.

Preview Changes

Show a diff of what would change:

justfmt --diff

Alphabetical Sorting

Sort recipes alphabetically:

justfmt --sort

Quote Style Override

Override the quote style:

justfmt --quote-style single
justfmt --quote-style double

Custom Configuration

Specify a configuration file or directory:

justfmt --config /path/to/config

Configuration

Using justfmt.ini

Create a justfmt.ini file in your project root:

[justfmt]
indent_spaces = 4
quote_style = double
sort_recipes = false
blank_lines_between_recipes = 1
ensure_trailing_newline = true

Using pyproject.toml

Add a [tool.justfmt] section to your pyproject.toml:

[tool.justfmt]
indent_spaces = 4
quote_style = "double"
sort_recipes = false
blank_lines_between_recipes = 1
ensure_trailing_newline = true

Configuration Options

Option	Type	Default	Description
indent_spaces	int	4	Number of spaces for indentation
quote_style	str	"double"	Quote style: "double" or "single"
sort_recipes	bool	false	Sort recipes alphabetically
blank_lines_between_recipes	int	1	Number of blank lines between recipes
ensure_trailing_newline	bool	true	Ensure file ends with newline

Formatting Rules

Indentation

All recipe bodies are normalized to use spaces (tabs are converted):

Before:

test:
	echo "hello"
	pytest

After:

test:
    echo "hello"
    pytest

Quote Normalization

Quotes are normalized to your preferred style (preserving mixed quotes when necessary):

Before (with quote_style = "double"):

test:
    echo 'hello world'

After:

test:
    echo "hello world"

Variable Spacing

Consistent spacing around operators:

Before:

auto:='auto'
MY_VAR:="value"

After:

auto := "auto"
MY_VAR := "value"

Recipe Sorting

Alphabetically sort recipes while preserving comments:

Before:

zzz:
    echo "last"

aaa:
    echo "first"

After (with --sort):

aaa:
    echo "first"

zzz:
    echo "last"

Integration with Pre-commit

Add to your .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: justfmt
        name: Format justfile
        entry: justfmt
        args: [--check]
        language: system
        files: justfile$

Development

Setup

Ensure that mise is installed. See mise installation guide.

sh setup.sh

Running Tests

just test

Format Code

just fmt

Validate

just validate