docs

A linha de comando

Um comando, pullmark, que entrega arquivos e pastas ao app. Feito para humanos num terminal e para agentes e scripts que querem colocar um documento na sua frente.

Instalando o comando

Como você obteve o PullMark decide como você obtém o comando:

Homebrew — já instalado; o cask vincula o pullmark ao seu prefixo do brew.
DMG — abra Ajustes (⌘,) → Geral e clique em Instalar o Comando pullmark…; ele vincula o comando em /usr/local/bin (talvez você precise autorizar).
Checkout do código-fonte — make install-cli (adicione BIN_DIR=~/bin para escolher onde).

Para o básico, nem precisa instalar — open -a PullMark README.md ~/notes faz o mesmo pelo próprio macOS.

Uso

pullmark                     # abre (ou foca) o PullMark
pullmark <path> ...          # abre arquivos e/ou pastas
pullmark --diff <path> ...   # abre arquivos como diffs renderizados vs HEAD
pullmark --diff=<ref> <path> ...
                             # … vs uma branch, tag ou commit
pullmark --diff=<r1>..<r2> <path> ...
                             # o arquivo em duas refs, ambas congeladas
pullmark --diff-with=<file> <path> ...
                             # … vs outro arquivo no disco
pullmark -h, --help          # a referência embutida
pullmark --version           # imprime a versão do app

O que abrir faz

As regras são deliberadamente sem graça, para um script poder confiar nelas:

Arquivos caem na seção Arquivos Abertos da barra lateral como entradas fixadas, e o último arquivo passado é o exibido.
Pastas — incluindo worktrees git — viram Localizações: árvores navegáveis dos arquivos Markdown lá dentro.
Já em execução? Tudo abre na janela da frente. Uma segunda instância do app nunca é iniciada.
Caminhos relativos resolvem contra o seu diretório atual; ~ funciona como sempre.
Um caminho que não existe aborta o comando inteiro com uma mensagem e código de saída 1 — nada abre pela metade.

Worktrees, e apontando para um arquivo

Passe uma pasta e um arquivo juntos e você ganha os dois comportamentos de uma vez: a pasta abre como Localização, o arquivo abre fixado e exibido. Essa é a receita inteira de “abra esta worktree e me mostre este doc”:

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

A árvore da worktree cai em Localizações (com seu chip de branch, já que uma worktree é só um checkout git), plan.md fica fixado em Arquivos Abertos e renderizado. Clique nele com o botão direito e escolha Mostrar na Localização para pular até onde ele está na árvore. Funciona igual quando a Localização já estava aberta — abrir um arquivo que mora dentro dela nunca cria um mundo duplicado, só uma entrada no conjunto de trabalho.

A ordem não importa para o par pasta/arquivo, mas o último arquivo passado é o exibido, então deixe por último o documento que você quer na tela.

Diffs renderizados a partir do shell

--diff abre cada arquivo comparando — seu conteúdo de trabalho contra o último commit, mostrado como o mesmo diff renderizado, palavra por palavra, que os pull requests recebem. --diff=<ref> compara contra uma branch, tag ou SHA de commit. É a porta de shell para o recurso Comparar do app (o botão de relógio com chevron da barra de ferramentas), e a resposta mais rápida para “o que o agente acabou de fazer com este documento”:

$ pullmark --diff docs/plan.md            # o que as últimas edições mudaram
$ pullmark --diff=main README.md          # o arquivo atual vs a main
$ pullmark --diff=v1.0..main README.md    # entre duas revisões, ambas congeladas
$ pullmark --diff-with=old.md new.md      # dois arquivos, old.md como base
$ pullmark --diff ~/wt/feature ~/wt/feature/docs/plan.md
                                          # uma worktree, plan.md em diff

Pastas passadas junto ainda abrem como Localizações, e cada forma tem um gêmeo dentro do app no menu Comparar da barra de ferramentas (incluindo Comparar Revisões… e Comparar com Arquivo…). Como --diff e --diff-with são flags, nunca subcomandos, um arquivo que por acaso se chame diff sempre simplesmente abre.

Códigos de saída

Código	Significado
`0`	Tudo foi entregue ao PullMark.
`1`	Um caminho não existia (cada um que falta é impresso no stderr).
`64`	Uso incorreto — uma opção desconhecida, `--diff` sem arquivo ou `--diff=` sem ref.

Exemplos

$ pullmark README.md                      # ler um arquivo
$ pullmark ~/notes                        # navegar por uma pasta
$ pullmark docs specs/design.md           # uma Localização mais um documento
$ pullmark ~/wt/feature docs/plan.md      # uma worktree, exibindo um doc
$ pullmark --diff docs/plan.md            # o que as últimas edições mudaram
$ pullmark -- --weird-filename.md         # -- encerra a análise de opções

Notas para agentes

Se você está ligando o PullMark a um agente ou script:

O comando retorna assim que o macOS aceita a abertura — ele não espera o app renderizar.
Repetir uma abertura é idempotente: um arquivo ou pasta já aberto é selecionado, não duplicado.
Tudo chega à janela da frente por design, então um humano observando uma janela vê cada abertura chegar ali.
Depois de editar um documento, pullmark --diff <arquivo> é o jeito de uma linha de colocar o que você mudou na frente do humano — renderizado, com as palavras alteradas em destaque.