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

Nix:

nix build github:TurtleTech-ehf/snapper

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

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

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.

Każde zdanie zajmuje osobną linię. Elementy strukturalne, takie jak bloki kodu, tabele, szuflady, środowiska matematyczne i front matter, przechodzą bez zmian.

Wykrywanie formatu¶

snapper automatycznie wykrywa format na podstawie rozszerzenia pliku:

.org – Org-mode
.tex, .latex – LaTeX
.md, .markdown – Markdown
Wszystko inne – zwykły tekst

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

Expose snapper to Claude Desktop, Claude Code, and other MCP clients:

{
  "mcpServers": {
    "snapper": {
      "command": "npx",
      "args": ["@turtletech/snapper-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.7.1
  hooks:
    - id: snapper

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\ --format\ org

Emacs (Apheleia)¶

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

Obsidian¶

Install from Community Plugins (search „Snapper”). Uses WebAssembly – no binary needed.

Word¶

Install the snapper add-in from AppSource (Insert > Get Add-ins > search „Snapper”). Uses WebAssembly – no binary needed.

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