docs

De command line

Eén commando, pullmark, dat bestanden en mappen aan de app doorgeeft. Gebouwd voor mensen in een terminal én voor agents en scripts die jou een document willen voorleggen.

Het commando installeren

Hoe je aan PullMark kwam bepaalt hoe je aan het commando komt:

• Homebrew — al geïnstalleerd; de cask linkt pullmark in je brew-prefix.
• DMG — open Instellingen (⌘,) → Algemeen en klik op Installeer pullmark-commando…; dat linkt het commando in /usr/local/bin (mogelijk wordt om toestemming gevraagd).
• Broncheckout — make install-cli (voeg BIN_DIR=~/bin toe om te kiezen waar).

Voor de basis is er hoe dan ook geen installatie nodig — open -a PullMark README.md ~/notes doet hetzelfde via macOS zelf.

Gebruik

pullmark                     # PullMark starten (of naar voren halen)
pullmark <path> ...          # bestanden en/of mappen openen
pullmark --diff <path> ...   # bestanden openen als gerenderde diffs t.o.v. HEAD
pullmark --diff=<ref> <path> ...
                             # … t.o.v. een branch, tag of commit
pullmark --diff=<r1>..<r2> <path> ...
                             # het bestand op twee refs, beide bevroren
pullmark --diff-with=<file> <path> ...
                             # … t.o.v. een ander bestand op schijf
pullmark -h, --help          # de ingebouwde referentie
pullmark --version           # toont de appversie

Wat openen doet

De regels zijn met opzet saai, zodat een script erop kan bouwen:

• Bestanden landen in de sectie Geopende bestanden van de zijbalk als vastgezette regels, en het laatst doorgegeven bestand wordt getoond.
• Mappen — inclusief git-worktrees — worden Locaties: doorbladerbare bomen van de Markdown-bestanden erin.
• Draait de app al? Alles opent in het voorste venster. Er wordt nooit een tweede app-instantie gestart.
• Relatieve paden lossen op tegen je huidige directory; ~ werkt zoals gewoonlijk.
• Een pad dat niet bestaat breekt het hele commando af met een melding en exitcode 1 — er opent niets half.

Worktrees, en naar één bestand wijzen

Geef een map en een bestand samen door en je krijgt beide gedragingen tegelijk: de map opent als Locatie, het bestand opent vastgezet en wordt getoond. Dat is het hele recept voor "open deze worktree en laat me dit doc zien":

$ pullmark ~/wt/feature ~/wt/feature/docs/plan.md

De boom van de worktree landt in Locaties (met zijn branch-chip, want een worktree is gewoon een git-checkout), plan.md wordt vastgezet in Geopende bestanden en gerenderd. Rechtsklik erop en kies Toon in Locaties om te springen naar waar het in de boom zit. Dit werkt hetzelfde wanneer de Locatie al open was — een bestand openen dat erin woont maakt nooit een dubbele wereld, alleen een regel in de werkset.

De volgorde maakt niet uit voor het map/bestand-paar, maar het laatste bestand dat je doorgeeft is het bestand dat wordt getoond — zet het document dat je op het scherm wilt dus achteraan.

Gerenderde diffs vanuit de shell

--diff opent elk bestand vergelijkend — de werkinhoud tegen de laatste commit, getoond als dezelfde gerenderde diff op woordniveau die pull requests krijgen. --diff=<ref> vergelijkt in plaats daarvan met een branch, tag of commit-SHA. Het is de shelldeur naar de Vergelijk-functie van de app (de klok-met-chevron-knop in de toolbar), en het snelste antwoord op "wat heeft de agent net met dit document gedaan":

$ pullmark --diff docs/plan.md            # wat de laatste bewerkingen veranderden
$ pullmark --diff=main README.md          # huidig bestand t.o.v. main
$ pullmark --diff=v1.0..main README.md    # tussen twee revisies, beide bevroren
$ pullmark --diff-with=old.md new.md      # twee bestanden, old.md als basis
$ pullmark --diff ~/wt/feature ~/wt/feature/docs/plan.md
                                          # een worktree, plan.md als diff

Mappen die je erbij doorgeeft openen nog steeds als Locaties, en elke vorm heeft een tweelingbroer in de app, in het Vergelijk-menu van de toolbar (inclusief Vergelijk revisies… en Vergelijk met bestand…). Omdat --diff en --diff-with flags zijn en nooit subcommando's, opent een bestand dat toevallig diff heet altijd gewoon.

Exitcodes

Voorbeelden

$ pullmark README.md                      # één bestand lezen
$ pullmark ~/notes                        # een map doorbladeren
$ pullmark docs specs/design.md           # een Locatie plus één document
$ pullmark ~/wt/feature docs/plan.md      # een worktree met één document
$ pullmark --diff docs/plan.md            # wat de laatste bewerkingen veranderden
$ pullmark -- --weird-filename.md         # -- beëindigt de optieverwerking

Aantekeningen voor agents

Als je PullMark in een agent of script inbouwt:

• Het commando keert terug zodra macOS de open accepteert — het wacht niet tot de app heeft gerenderd.
• Een open herhalen is idempotent: een al geopend bestand of map wordt geselecteerd, niet gedupliceerd.
• Alles landt bewust in het voorste venster, zodat een mens die naar één venster kijkt elke open daar ziet aankomen.
• Na het bewerken van een document is pullmark --diff <file> de éénregelige manier om wat je veranderde aan de mens voor te leggen — gerenderd, met de gewijzigde woorden gemarkeerd.