#+OPTIONS: num:nil toc:nil

* Quickstart

** Installation

Pre-built binary (fastest, no compilation):

#+begin_src bash
cargo binstall snapper-fmt
#+end_src

Or compile from source:

#+begin_src bash
cargo install snapper-fmt
#+end_src

Shell one-liner (Linux/macOS):

#+begin_src bash
curl -LsSf https://github.com/TurtleTech-ehf/snapper/releases/latest/download/snapper-fmt-installer.sh | sh
#+end_src

Homebrew (macOS/Linux):

#+begin_src bash
brew install TurtleTech-ehf/tap/snapper-fmt
#+end_src

pip:

#+begin_src bash
pip install snapper-fmt
#+end_src

Nix:

#+begin_src bash
nix build github:TurtleTech-ehf/snapper
#+end_src

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

** Basic usage

Format a file, printing to stdout:

#+begin_src bash
snapper paper.org
#+end_src

Format in place:

#+begin_src bash
snapper --in-place paper.org
#+end_src

Pipe through stdin (for editor integration):

#+begin_src bash
cat draft.org | snapper --format org
#+end_src

** What it does

Given a paragraph like this:

#+begin_src text
This is the first sentence. It continues with more details about the topic. See Fig. 3 for the results.
#+end_src

~snapper~ produces:

#+begin_src text
This is the first sentence.
It continues with more details about the topic.
See Fig. 3 for the results.
#+end_src

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=:

#+begin_src bash
snapper --format latex draft.tex
#+end_src

** Sentence-level diff

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

#+begin_src bash
snapper sdiff paper_v1.org paper_v2.org
#+end_src

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:

#+begin_src bash
snapper watch '*.org' 'sections/*.tex'
#+end_src

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

** Project setup

Initialize snapper for a new project:

#+begin_src bash
snapper init
#+end_src

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:

#+begin_src bash
snapper --check paper.org
#+end_src

For GitHub Code Scanning, use SARIF output:

#+begin_src bash
snapper --check --output-format sarif paper.org > snapper.sarif
#+end_src

** Pre-commit hook

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

#+begin_src yaml
- repo: https://github.com/TurtleTech-ehf/snapper
  rev: v0.2.1
  hooks:
    - id: snapper
#+end_src

** Emacs (Apheleia)

Add to your Emacs config:

#+begin_src elisp
(with-eval-after-load 'apheleia
  (push '(snapper . ("snapper" "--format" "org")) apheleia-formatters)
  (push '(org-mode . snapper) apheleia-mode-alist))
#+end_src

This runs ~snapper~ on save for Org-mode buffers.
