docs

Solução de problemas

As poucas coisas que saem do trilho, o que as mensagens do PullMark significam e o design por trás das falhas mais silenciosas — a maioria dos “erros” aqui é o app se recusando de propósito a perder o seu trabalho.

Acesso ao GitHub: como o PullMark conecta, e como consertar

O PullMark toma emprestadas as credenciais do GitHub que suas próprias ferramentas já têm — ele não tem login próprio e nunca guarda um segredo. Ajustes → Geral → GitHub mostra se está conectado, como quem e por qual fonte; Configurar… guia uma máquina nova pela conexão, e Verificar Novamente pega uma correção na hora — depois de gh auth login, sem precisar reabrir o app.

Lendo isto no Mac onde o PullMark (0.36+) está instalado? Abra a linha de conexão agora.

As fontes de credenciais, na ordem em que o PullMark as tenta:

1. O token da GitHub CLI: gh auth token precisa imprimir um. Se não, brew install gh && gh auth login — o caminho recomendado: seu token tem escopos comprovadamente bons, trata SSO pelo fluxo do navegador e se renova.
2. Senão, git credential fill — o que o próprio git usa para github.com (as Chaves do macOS, o Git Credential Manager, um token guardado por um push HTTPS antigo).

As letras miúdas dos tokens, para os que funcionam pela metade: tokens clássicos precisam do escopo repo (e read:org para nomes de times de organização); tokens fine-grained são presos a um único dono de recursos — repositórios públicos e os privados daquele dono funcionam, todo o resto é negado; organizações protegidas por SSO exigem o token autorizado para cada organização; e tokens criados manualmente expiram — a linha nos Ajustes é onde o “ontem funcionava” é diagnosticado.

GitHub: “pode não existir nesse ref… ou pode ser um repositório privado”

“Não foi possível abrir … Pode não existir nesse ref, ou pode ser um repositório privado que suas credenciais do GitHub não acessam.” A API do GitHub relata “privado sem acesso” e “não existe” de forma idêntica, então o PullMark não consegue dizer qual dos dois é. Se o repositório deveria funcionar, é quase sempre autenticação — veja Acesso ao GitHub acima, ou abra Ajustes → Geral → GitHub e acione Configurar….

O Gatekeeper não abre o app

As releases são assinadas com um Developer ID e notarizadas pela Apple, então um download normal não mostra aviso. Se você compilou do código-fonte (make app), o app tem assinatura ad-hoc: clique com o botão direito → Abrir → Abrir, ou permita-o em Ajustes do Sistema → Privacidade e Segurança.

As prévias do Quick Look pararam de renderizar

Uma atualização do Homebrew substitui o pacote do app, o que pode derrubar silenciosamente o registro da extensão de Quick Look. O PullMark a re-registra a cada abertura — então basta abrir o app uma vez. Se as prévias ainda mostrarem texto cru, confira se Ajustes → Geral → “Prévias do Quick Look” está em Renderizado.

“O PullMark não é mais seu app padrão de Markdown”

Mesma causa: uma atualização substituiu o pacote e o macOS derrubou o vínculo com .md. O Tornar Padrão de Novo do banner o retoma; Ajustes → Geral também.

“… mudou enquanto você estava editando este bloco — nada foi salvo”

O arquivo mudou no disco (outro editor, um agente, uma operação git) entre abrir o editor de bloco e salvar. O PullMark se recusa a emendar em linhas que se moveram — nada se perde além daquela única edição, e reabrir o bloco mostra o texto atual. A mesma proteção vale para commits: comparar contra uma ref onde o arquivo não existe é relatado com clareza, em vez de mostrar um diff vazio.

Linhas escurecidas: pastas e recentes que “não estão lá”

Uma Localização com selo de interrogação, ou um recente acinzentado, significa que o caminho não resolve agora — um volume desmontado, uma branch git trocada, uma worktree apagada. As linhas escurecem em vez de sumir de propósito: elas revivem sozinhas quando o caminho volta. Clicar num recente morto oferece Remover dos Recentes ou Manter.

Pull requests: banners e comentários pendentes

• “Este pull request foi atualizado no GitHub.” — a branch avançou desde que você o carregou. Atualizar é um clique e seus rascunhos de comentário sobrevivem; o PullMark nunca recarrega sozinho por baixo de uma revisão em andamento.
• “Não foi possível carregar os comentários de revisão…” — sem isso, o diff se passaria por um PR sem comentários; Tentar Novamente rebusca.
• “Não foi possível enviar N comentários pendentes… mantidos localmente para nova tentativa.” — comentários escritos offline (ou durante um soluço da API) entram numa fila no disco por head de PR e sobem quando podem. Nada é descartado.
• “…, mas o push falhou” — o commit está a salvo no seu histórico local; só o push precisa ser repetido.

Atualizações

O Atualizar Agora do banner executa o upgrade do brew (ou uma instalação verificada no lugar, para instalações via DMG) e reabre o app. Se falhar, o banner mostra o comando exato brew upgrade --cask pullmark com um botão de copiar — executá-lo num terminal faz a mesma coisa. Builds de desenvolvimento não verificam atualizações.

O comando pullmark

• “no such file or folder” — o comando verifica cada caminho antes de abrir qualquer coisa; um erro de digitação aborta a abertura inteira (código de saída 1), para os scripts falharem em voz alta.
• Comando não encontrado — veja instalando o comando.
• “Não foi possível instalar o comando” — o instalador dos Ajustes precisa de autorização para gravar em /usr/local/bin; cancele e rode de novo se você dispensou o aviso.

Ainda travado?

Abra uma issue — Ajuda → Relatar um Erro… pré-preenche uma de dentro do app.