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.