Quickstart

Installation

Pre-built binary (fastest, no compilation):

cargo binstall snapper-fmt

Or compile from source:

cargo install snapper-fmt

Shell one-liner (Linux/macOS):

curl -LsSf https://github.com/TurtleTech-ehf/snapper/releases/latest/download/snapper-fmt-installer.sh | sh

Homebrew (macOS/Linux):

brew install TurtleTech-ehf/tap/snapper-fmt

pip:

pip install snapper-fmt

Nix:

nix build github:TurtleTech-ehf/snapper

The crate is snapper-fmt on all registries; the binary it installs is snapper.

Basic usage

Format a file, printing to stdout:

snapper paper.org

Format in place:

snapper --in-place paper.org

Pipe through stdin (for editor integration):

cat draft.org | snapper --format org

What it does

Given a paragraph like this:

This is the first sentence. It continues with more details about the topic. See Fig. 3 for the results.

snapper produces:

This is the first sentence.
It continues with more details about the topic.
See Fig. 3 for the results.

Each sentence occupies its own line. Structural elements like code blocks, tables, drawers, math environments, and front matter pass through unchanged.

Format detection

snapper auto-detects the format from the file extension:

• .org – Org-mode

• .tex, .latex – LaTeX

• .md, .markdown – Markdown

• Everything else – plaintext

Override with --format:

snapper --format latex draft.tex

Sentence-level diff

Compare two versions of a file at the sentence level, ignoring whitespace reflow:

snapper sdiff paper_v1.org paper_v2.org

Only actual content changes appear. Reformatting (rewrapping) the same text produces zero diff. Useful for reviewing collaborator edits on shared papers.

Watch mode

Auto-reformat files on save:

snapper watch '*.org' 'sections/*.tex'

Monitors files and runs --in-place on change (200ms debounce). Press Ctrl+C to stop.

Project setup

Initialize snapper for a new project:

snapper init

Detects which formats exist and generates .snapperrc.toml, .gitattributes, pre-commit config, and Apheleia snippets. Use --dry-run to preview.

CI integration

Use --check mode to verify formatting without modifying files. Exits with code 1 if any file would change:

snapper --check paper.org

For GitHub Code Scanning, use SARIF output:

snapper --check --output-format sarif paper.org > snapper.sarif

Pre-commit hook

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

- repo: https://github.com/TurtleTech-ehf/snapper
  rev: v0.2.1
  hooks:
    - id: snapper

Emacs (Apheleia)

Add to your Emacs config:

(with-eval-after-load 'apheleia
  (push '(snapper . ("snapper" "--format" "org")) apheleia-formatters)
  (push '(org-mode . snapper) apheleia-mode-alist))

This runs snapper on save for Org-mode buffers.