docs

Die Kommandozeile

Ein Befehl, pullmark, der Dateien und Ordner an die App reicht. Gebaut für Menschen im Terminal — und für Agenten und Skripte, die dir ein Dokument vorlegen wollen.

Den Befehl installieren

Wie du PullMark bekommen hast, entscheidet, wie du an den Befehl kommst:

Homebrew — schon installiert; der Cask verlinkt pullmark in dein Brew-Prefix.
DMG — öffne Einstellungen (⌘,) → Allgemein und klick pullmark-Befehl installieren…; das verlinkt den Befehl nach /usr/local/bin (eventuell wirst du um Freigabe gebeten).
Aus dem Quelltext — make install-cli (mit BIN_DIR=~/bin wählst du, wohin).

Fürs Grundlegende brauchst du so oder so nichts zu installieren — open -a PullMark README.md ~/notes tut dasselbe über macOS selbst.

Verwendung

pullmark                     # PullMark starten (oder nach vorn holen)
pullmark <path> ...          # Dateien und/oder Ordner öffnen
pullmark --diff <path> ...   # Dateien als gerenderte Diffs gegen HEAD
pullmark --diff=<ref> <path> ...
                             # … gegen einen Branch, Tag oder Commit
pullmark --diff=<r1>..<r2> <path> ...
                             # die Datei an zwei Refs, beide eingefroren
pullmark --diff-with=<file> <path> ...
                             # … gegen eine andere Datei auf der Platte
pullmark -h, --help          # die eingebaute Referenz
pullmark --version           # die Version der App ausgeben

Was Öffnen bedeutet

Die Regeln sind bewusst langweilig, damit ein Skript sich auf sie verlassen kann:

Dateien landen als feste Einträge im Bereich Geöffnete Dateien der Seitenleiste, und angezeigt wird die zuletzt übergebene.
Ordner — Git-Worktrees eingeschlossen — werden zu Orten: durchstöberbare Bäume der Markdown-Dateien darin.
Läuft schon? Alles öffnet im vordersten Fenster. Eine zweite Instanz der App wird nie gestartet.
Relative Pfade lösen gegen dein aktuelles Verzeichnis auf; ~ geht wie gewohnt.
Ein Pfad, den es nicht gibt, bricht den ganzen Befehl ab — mit Meldung und Exit-Code 1. Nichts öffnet halb.

Worktrees — und auf eine Datei zeigen

Übergib einen Ordner und eine Datei zusammen und du bekommst beides auf einmal: Der Ordner öffnet als Ort, die Datei öffnet fest und wird angezeigt. Das ist das ganze Rezept für „öffne diesen Worktree und zeig mir dieses Doc":

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

Der Baum des Worktrees landet unter „Orte“ (mit seinem Branch-Chip, denn ein Worktree ist einfach ein Git-Checkout), plan.md sitzt fest in „Geöffnete Dateien“ und ist gerendert. Rechtsklick darauf und Im Ort zeigen springt dahin, wo sie im Baum wohnt. Das läuft genauso, wenn der Ort schon offen war — eine Datei zu öffnen, die darin liegt, erzeugt nie eine zweite Welt, nur einen Eintrag im Arbeitsset.

Fürs Ordner-Datei-Paar ist die Reihenfolge egal, angezeigt wird aber die zuletzt übergebene Datei — stell also das Dokument, das auf den Schirm soll, ans Ende.

Gerenderte Diffs aus der Shell

--diff öffnet jede Datei im Vergleich — ihren Arbeitsstand gegen den letzten Commit, gezeigt als dasselbe gerenderte, wortgenaue Diff, das auch Pull Requests bekommen. --diff=<ref> vergleicht stattdessen gegen einen Branch, Tag oder Commit-SHA. Es ist die Shell-Tür zum „Vergleichen“-Feature der App (der Uhr-mit-Chevron-Button der Toolbar) und die schnellste Antwort auf „was hat der Agent gerade mit diesem Dokument gemacht":

$ pullmark --diff docs/plan.md            # was die letzten Edits geändert haben
$ pullmark --diff=main README.md          # aktuelle Datei gegen main
$ pullmark --diff=v1.0..main README.md    # zwischen zwei Revisionen, beide eingefroren
$ pullmark --diff-with=old.md new.md      # zwei Dateien, old.md die Basis
$ pullmark --diff ~/wt/feature ~/wt/feature/docs/plan.md
                                          # ein Worktree, plan.md als Diff

Ordner, die du danebenstellst, öffnen weiterhin als Orte, und jede Form hat ihren Zwilling in der App, im „Vergleichen“-Menü der Toolbar (samt Revisionen vergleichen… und Mit Datei vergleichen…). Weil --diff und --diff-with Flags sind und nie Unterbefehle, öffnet eine Datei, die zufällig diff heißt, immer einfach nur.

Exit-Codes

Code	Bedeutung
`0`	Alles wurde an PullMark übergeben.
`1`	Ein Pfad existierte nicht (jeder fehlende wird auf stderr ausgegeben).
`64`	Falsche Verwendung — eine unbekannte Option, `--diff` ohne Datei oder `--diff=` ohne Ref.

Beispiele

$ pullmark README.md                      # eine Datei lesen
$ pullmark ~/notes                        # einen Ordner durchstöbern
$ pullmark docs specs/design.md           # ein Ort plus ein Dokument
$ pullmark ~/wt/feature docs/plan.md      # ein Worktree, ein Doc im Bild
$ pullmark --diff docs/plan.md            # was die letzten Edits geändert haben
$ pullmark -- --weird-filename.md         # -- beendet das Parsen von Optionen

Hinweise für Agenten

Wenn du PullMark in einen Agenten oder ein Skript einbaust:

Der Befehl kehrt zurück, sobald macOS das Öffnen annimmt — er wartet nicht, bis die App gerendert hat.
Ein Öffnen zu wiederholen ist idempotent: Eine schon offene Datei oder ein schon offener Ordner wird ausgewählt, nicht dupliziert.
Alles landet per Design im vordersten Fenster, damit ein Mensch, der ein Fenster im Blick hat, jedes Öffnen dort ankommen sieht.
Nach dem Bearbeiten eines Dokuments ist pullmark --diff <file> der Einzeiler, um dem Menschen das, was du geändert hast vorzulegen — gerendert, mit hervorgehobenen geänderten Wörtern.