Szybki start¶

Instalacja¶

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

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.

Podstawowe użycie¶

Sformatuj plik, wypisz na stdout:

snapper paper.org

Sformatuj w miejscu:

snapper --in-place paper.org

Prześlij przez stdin (dla integracji z edytorem):

cat draft.org | snapper --format org

The CLI uses pandoc (auto FFI, then CLI) when an FFI writer or pandoc on PATH is available. Otherwise it keeps the native line parsers (no error). Pass --native to force today’s parsers. Pass --use-pandoc to require pandoc (error if missing). Editors, wasm, and LSP stay native.

Co robi¶

Mając akapit taki jak ten:

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

snapper generuje:

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).

Wykrywanie formatu¶

snapper automatycznie wykrywa format na podstawie rozszerzenia pliku:

.org – Org-mode
.tex, .latex – LaTeX
.md, .markdown – Markdown
.rst, .rest – reStructuredText
.txt – plaintext

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

Nadpisz za pomocą --format:

snapper --format latex draft.tex

Diff zdaniowy¶

Porównaj dwie wersje pliku na poziomie zdań, ignorując przeformatowanie białych znaków:

snapper sdiff paper_v1.org paper_v2.org

Wyświetlane są tylko rzeczywiste zmiany treści. Przeformatowanie (przełamanie wierszy) tego samego tekstu daje zerowy diff. Przydatne do przeglądania edycji współpracowników we wspólnych artykułach.

Tryb obserwacji¶

Automatyczne przeformatowanie plików przy zapisie:

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

Monitoruje pliki i uruchamia --in-place przy zmianie (200ms opóźnienia). Naciśnij Ctrl+C, aby zatrzymać.

Konfiguracja projektu¶

Zainicjalizuj snapper dla nowego projektu:

snapper init

Wykrywa, które formaty istnieją, i generuje .snapperrc.toml, .gitattributes, konfigurację pre-commit oraz fragmenty Apheleia. Użyj --dry-run, aby wyświetlić podgląd.

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.

Integracja z CI¶

Użyj trybu --check, aby zweryfikować formatowanie bez modyfikowania plików. Kończy działanie z kodem 1, jeśli jakikolwiek plik uległby zmianie:

snapper --check paper.org

Dla GitHub Code Scanning użyj wyjścia SARIF:

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

Hook pre-commit¶

Dodaj do swojego .pre-commit-config.yaml:

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

Runs snapper --in-place on \*.org, \*.tex=/=*.latex, \*.md=/=*.markdown, \*.rst, 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.