docs

La ligne de commande

Une commande, pullmark, qui tend fichiers et dossiers à l'app. Pensée pour les humains dans un terminal comme pour les agents et scripts qui veulent placer un document sous vos yeux.

Installer la commande

La façon dont vous avez obtenu PullMark décide de la façon dont vous obtenez la commande :

Homebrew — déjà installée ; le cask lie pullmark dans votre préfixe brew.
DMG — ouvrez Réglages (⌘,) → Général et cliquez Installer la commande pullmark… ; la commande se lie dans /usr/local/bin (une autorisation peut vous être demandée).
Copie des sources — make install-cli (ajoutez BIN_DIR=~/bin pour choisir où).

Aucune installation n'est nécessaire pour l'essentiel, de toute façon — open -a PullMark README.md ~/notes fait pareil via macOS lui-même.

Utilisation

pullmark                     # lancer (ou mettre au premier plan) PullMark
pullmark <path> ...          # ouvrir des fichiers et/ou dossiers
pullmark --diff <path> ...   # ouvrir les fichiers en diffs rendus contre HEAD
pullmark --diff=<ref> <path> ...
                             # … contre une branche, un tag ou un commit
pullmark --diff=<r1>..<r2> <path> ...
                             # le fichier à deux refs, toutes deux figées
pullmark --diff-with=<file> <path> ...
                             # … contre un autre fichier sur le disque
pullmark -h, --help          # la référence intégrée
pullmark --version           # afficher la version de l'app

Ce que fait l'ouverture

Les règles sont délibérément ennuyeuses, pour qu'un script puisse compter dessus :

Les fichiers atterrissent dans la section Fichiers ouverts de la barre latérale en entrées épinglées, et le dernier fichier passé est affiché.
Les dossiers — worktrees git compris — deviennent des Emplacements : des arborescences navigables des fichiers Markdown qu'ils contiennent.
Déjà lancée ? Tout s'ouvre dans la fenêtre au premier plan. Une seconde instance de l'app n'est jamais démarrée.
Les chemins relatifs se résolvent contre votre répertoire courant ; ~ marche comme d'habitude.
Un chemin qui n'existe pas interrompt toute la commande avec un message et le code de sortie 1 — rien ne s'ouvre à moitié.

Les worktrees, et viser un seul fichier

Passez un dossier et un fichier ensemble et vous obtenez les deux comportements d'un coup : le dossier s'ouvre en emplacement, le fichier s'ouvre épinglé et affiché. C'est toute la recette de « ouvre ce worktree et montre-moi cette doc » :

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

L'arborescence du worktree atterrit dans Emplacements (avec sa pastille de branche, un worktree n'étant qu'une copie de travail git), plan.md est épinglé dans Fichiers ouverts et rendu. Clic droit dessus et Afficher dans Emplacements saute vers sa place dans l'arborescence. Cela marche pareil quand l'emplacement était déjà ouvert — ouvrir un fichier qui vit dedans ne crée jamais un monde en double, juste une entrée dans l'ensemble de travail.

L'ordre n'importe pas pour l'appariement dossier/fichier, mais le dernier fichier passé est celui affiché : mettez en dernier le document que vous voulez à l'écran.

Des diffs rendus depuis le shell

--diff ouvre chaque fichier en comparaison — son contenu de travail contre le dernier commit, montré comme le même diff rendu, mot à mot, que reçoivent les pull requests. --diff=<ref> compare plutôt à une branche, un tag ou un SHA de commit. C'est la porte shell vers la fonctionnalité Comparer de l'app (le bouton horloge-et-chevron de la barre d'outils), et la réponse la plus rapide à « qu'est-ce que l'agent vient de faire à ce document » :

$ pullmark --diff docs/plan.md            # ce que les dernières éditions ont changé
$ pullmark --diff=main README.md          # le fichier courant contre main
$ pullmark --diff=v1.0..main README.md    # entre deux révisions, toutes deux figées
$ pullmark --diff-with=old.md new.md      # deux fichiers, old.md comme référence
$ pullmark --diff ~/wt/feature ~/wt/feature/docs/plan.md
                                          # un worktree, plan.md diffé

Les dossiers passés à côté s'ouvrent toujours en emplacements, et chaque forme a son jumeau dans le menu Comparer de la barre d'outils (y compris Comparer des versions… et Comparer avec un fichier…). Parce que --diff et --diff-with sont des drapeaux, jamais des sous-commandes, un fichier qui s'appellerait diff s'ouvre toujours, tout simplement.

Codes de sortie

Code	Signification
`0`	Tout a été remis à PullMark.
`1`	Un chemin n'existait pas (chaque manquant est imprimé sur stderr).
`64`	Mauvais usage — une option inconnue, `--diff` sans fichier, ou `--diff=` sans ref.

Exemples

$ pullmark README.md                      # lire un fichier
$ pullmark ~/notes                        # parcourir un dossier
$ pullmark docs specs/design.md           # un emplacement plus un document
$ pullmark ~/wt/feature docs/plan.md      # un worktree, une doc affichée
$ pullmark --diff docs/plan.md            # ce que les dernières éditions ont changé
$ pullmark -- --weird-filename.md         # -- termine l'analyse des options

Notes pour les agents

Si vous branchez PullMark sur un agent ou un script :

La commande rend la main dès que macOS accepte l'ouverture — elle n'attend pas que l'app ait rendu.
Répéter une ouverture est idempotent : un fichier ou dossier déjà ouvert est sélectionné, pas dupliqué.
Tout atterrit dans la fenêtre au premier plan, à dessein : un humain qui regarde une fenêtre y voit arriver chaque ouverture.
Après avoir édité un document, pullmark --diff <file> est la ligne unique qui met ce que vous avez changé sous les yeux de l'humain — rendu, avec les mots modifiés surlignés.