docs

La línea de comandos

Un solo comando, pullmark, que le entrega archivos y carpetas a la app. Hecho para humanos en una terminal y para los agentes y scripts que quieren ponerte un documento delante.

Instalar el comando

Cómo llegaste a PullMark decide cómo llegas al comando:

Homebrew — ya está instalado; el cask enlaza pullmark dentro de tu prefijo de brew.
DMG — abre Ajustes (⌘,) → General y haz clic en Instalar el comando pullmark…; eso enlaza el comando en /usr/local/bin (puede que te pida autorización).
Copia del código fuente — make install-cli (añade BIN_DIR=~/bin para elegir dónde).

Para lo básico no hace falta instalar nada, vengas por donde vengas: open -a PullMark README.md ~/notes hace lo mismo a través del propio macOS.

Uso

pullmark                     # abre PullMark (o lo trae al frente)
pullmark <path> ...          # abre archivos y/o carpetas
pullmark --diff <path> ...   # abre archivos como diffs renderizados vs HEAD
pullmark --diff=<ref> <path> ...
                             # … vs una rama, una etiqueta o un commit
pullmark --diff=<r1>..<r2> <path> ...
                             # el archivo en dos refs, ambas congeladas
pullmark --diff-with=<file> <path> ...
                             # … vs otro archivo del disco
pullmark -h, --help          # la referencia integrada
pullmark --version           # imprime la versión de la app

Qué pasa al abrir

Las reglas son deliberadamente aburridas, para que un script pueda confiar en ellas:

Los archivos caen en la sección Archivos abiertos de la barra lateral como entradas conservadas, y se muestra el último archivo que pasaste.
Las carpetas — worktrees de git incluidos — se convierten en Ubicaciones: árboles navegables de los archivos Markdown que hay dentro.
¿Ya está abierta? Todo se abre en la ventana frontal. Nunca se lanza una segunda instancia de la app.
Las rutas relativas se resuelven contra tu directorio actual; ~ funciona como siempre.
Una ruta que no existe aborta el comando entero, con un mensaje y código de salida 1 — nada se abre a medias.

Worktrees, y apuntar a un archivo

Pasa juntos una carpeta y un archivo y tienes los dos comportamientos a la vez: la carpeta se abre como Ubicación, el archivo se abre conservado y a la vista. Esa es la receta entera de «abre este worktree y muéstrame este doc»:

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

El árbol del worktree aterriza en Ubicaciones (con su chip de rama, porque un worktree no es más que un checkout de git), plan.md queda conservado en Archivos abiertos y renderizado. Haz clic derecho y elige Mostrar en su ubicación para saltar al punto del árbol donde vive. Funciona igual cuando la Ubicación ya estaba abierta — abrir un archivo que vive dentro de ella nunca crea un mundo duplicado, solo una entrada en el conjunto de trabajo.

Para emparejar carpeta y archivo el orden da igual, pero el que se muestra es el último archivo que pases, así que deja para el final el documento que quieres en pantalla.

Diffs renderizados desde la terminal

--diff abre cada archivo comparando — su contenido de trabajo contra el último commit, mostrado como el mismo diff renderizado, palabra por palabra, que reciben los pull requests. --diff=<ref> compara en su lugar contra una rama, una etiqueta o el SHA de un commit. Es la puerta de la terminal a la función Comparar de la app (el botón del reloj con chevron en la barra de herramientas), y la respuesta más rápida a «qué acaba de hacerle el agente a este documento»:

$ pullmark --diff docs/plan.md            # qué cambiaron las últimas ediciones
$ pullmark --diff=main README.md          # el archivo actual vs main
$ pullmark --diff=v1.0..main README.md    # entre dos revisiones, ambas congeladas
$ pullmark --diff-with=old.md new.md      # dos archivos, old.md como base
$ pullmark --diff ~/wt/feature ~/wt/feature/docs/plan.md
                                          # un worktree, con plan.md en diff

Las carpetas que pases al lado siguen abriéndose como Ubicaciones, y cada forma tiene su gemela dentro de la app, en el menú Comparar de la barra de herramientas (incluidas Comparar revisiones… y Comparar con un archivo…). Como --diff y --diff-with son opciones, nunca subcomandos, un archivo que se llame precisamente diff siempre se abre y ya.

Códigos de salida

Código	Significado
`0`	Todo quedó entregado a PullMark.
`1`	Alguna ruta no existía (cada una que falta se imprime en stderr).
`64`	Uso incorrecto — una opción desconocida, `--diff` sin archivo o `--diff=` sin ref.

Ejemplos

$ pullmark README.md                      # leer un archivo
$ pullmark ~/notes                        # navegar una carpeta
$ pullmark docs specs/design.md           # una Ubicación más un documento
$ pullmark ~/wt/feature docs/plan.md      # un worktree, mostrando un doc
$ pullmark --diff docs/plan.md            # qué cambiaron las últimas ediciones
$ pullmark -- --weird-filename.md         # -- termina el análisis de opciones

Notas para agentes

Si estás conectando PullMark a un agente o a un script:

El comando devuelve el control en cuanto macOS acepta la apertura — no espera a que la app renderice.
Repetir una apertura es idempotente: un archivo o una carpeta que ya esté abierta se selecciona, no se duplica.
Todo aterriza en la ventana frontal por diseño, así que quien mire una sola ventana ve llegar ahí cada apertura.
Después de editar un documento, pullmark --diff <file> es la forma de una línea de poner lo que cambiaste delante de la persona — renderizado, con las palabras cambiadas resaltadas.