Quickstart

Installation

Pre-built binary (fastest, no compilation):

cargo binstall snapper-fmt

cargo binstall fetches the archive for your platform from the GitHub release. Releases cover Linux on x8664and aarch64 (glibc and static musl), macOS on x8664and Apple silicon, and Windows on x8664. Pick the musl archive for Alpine or a minimal container.

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

conda-forge:

conda install -c conda-forge snapper-fmt

Nix:

nix build github:TurtleTech-ehf/snapper

The crate is snapper-fmt on all registries. Each install ships two CLI names for the same program: snapper and snapper-fmt. If openSUSE snapper (Btrfs/LVM snapshots) already owns /usr/bin/snapper, call this formatter as snapper-fmt.

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

The CLI uses the native line parsers unless --use-pandoc is set or .snapperrc.toml sets use_pandoc = true. --native is accepted and selects those same parsers. --use-pandoc requires pandoc (error if missing). Markdown on that path is read and written as gfm. A render mismatch leaves the input unchanged and warns on stderr. A list item or blockquote at the end of the file still splits when the final newline is missing. Editors, wasm, and LSP stay native.

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. Tables, drawers, math environments, and front matter pass through unchanged. Source blocks are code regions: fences stay fixed and configured language comments reflow (see the formats and config references).

Format detection

snapper auto-detects the format from the file extension:

  • .org – Org-mode

  • .tex, .latex – LaTeX

  • .md, .markdown – Markdown

  • .rst, .rest – reStructuredText

  • .typ, .typst – Typst

  • .txt – plaintext

Unknown extensions (.rs, .py, no extension) are refused unless --format is explicit.

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.

MCP server (AI assistants)

Published snapper / snapper-fmt binaries include the MCP server. Configure an MCP client to run the stdio command:

snapper mcp

Agents should call this server or the snapper CLI instead of applying sembr.org / sembr/skills wrapping by hand.

From source with --no-default-features, rebuild with MCP:

cargo install snapper-fmt --features mcp
{
  "mcpServers": {
    "snapper": {
      "command": "snapper",
      "args": ["mcp"]
    }
  }
}

See MCP Integration for details.

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.11.10
  hooks:
    - id: snapper

Runs snapper --in-place on \*.org, \*.tex=/=*.latex, \*.md=/=*.markdown, \*.rst, \*.typ=/=*.typst, and \*.txt (extension match; identify has no org type). Requires a Rust toolchain so pre-commit can build the hook from this repo.

Editor integration

VS Code

Install TurtleTech.snapper from the Marketplace. Provides format-on-save, range formatting, diagnostics, and code actions out of the box.

Neovim

See the snapper.nvim plugin for full LSP integration, or use formatprg:

autocmd FileType org setlocal formatprg=snapper\ --native\ --format\ org

Emacs (Apheleia)

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

Obsidian

Development preview; not listed in Community Plugins. Use the source in editors/obsidian for development builds.

Word

Development preview; not published in AppSource. Use the source and sideloading instructions in editors/word.

See Editor Integration for Vim, Helix, eglot, conform.nvim, and other setups.