VS Code: compare versões lado a lado antes de aceitar o diff

ANÁLISE EDITORIAL

Um diff no terminal é preciso, mas nem sempre é a forma mais clara de revisar uma mudança com outra pessoa. A Skill VS Code, do repositório badlogic/pi-skills, orienta o agente a abrir duas versões do mesmo arquivo no editor de diferenças do Visual Studio Code. A ideia é simples: identificar a origem correta, materializar a versão histórica quando necessário e deixar a decisão final visível para revisão humana.

O que esta Skill faz

A Skill ensina o agente a usar code -d arquivo1 arquivo2 para abrir dois arquivos lado a lado no editor de diferenças do VS Code. Ela também combina esse comando com git show para comparar o arquivo atual com uma versão de commit, com o commit anterior ou com a versão que está na área de stage.

O ganho não está em criar um algoritmo de diff novo. O VS Code já oferece essa interface. A Skill transforma a comparação em um procedimento repetível, com uma verificação curta do histórico antes de abrir a janela. Isso ajuda quando o agente precisa mostrar, e não apenas descrever, o que mudou.

Para quem serve

Ela serve a desenvolvedores, revisores, analistas e usuários que preferem conferir alterações em uma interface visual. É útil para comparar uma configuração antes e depois, revisar uma mudança gerada por IA, explicar uma alteração a alguém que não usa Git no terminal ou confirmar se o conteúdo em stage corresponde ao arquivo de trabalho.

Não é um substituto para revisão de pull request, teste automatizado, análise de segurança ou validação de comportamento. A tela mostra diferenças entre dois arquivos. Ela não prova que a revisão escolhida é a correta nem que a alteração funciona.

Origem e curadoria

A origem é a pasta vscode no repositório badlogic/pi-skills. A curadoria fixou o commit 90bb51cae36515a648515b633a81c0c6efc8c74d e comparou o SKILL.md original byte a byte.

O README do projeto declara compatibilidade com pi-coding-agent, Claude Code, Codex CLI, Amp e Droid. Essa compatibilidade descreve o formato da Skill. A execução prática ainda depende de o agente poder chamar o terminal e de o usuário autorizar a abertura do VS Code.

Compatibilidade e pré-requisitos

Para comparar dois arquivos já existentes, basta ter o Visual Studio Code instalado e o comando code disponível no PATH. A documentação oficial da interface de linha de comando confirma que -d e --diff abrem o editor de diferenças e exigem dois caminhos.

Para comparar uma versão histórica, Git também precisa estar instalado e o comando deve ser executado dentro do repositório correto. O arquivo deve existir na revisão escolhida. Em Windows, Linux e macOS, o caminho do temporário e as regras de escape são diferentes.

Instalação com origem fixada

O README oficial sugere clonar o repositório de Skills. Para repetir exatamente a revisão auditada, clone em uma pasta de teste e faça checkout do commit fixado antes de copiar somente a pasta vscode para o diretório de Skills do agente.

git clone https://github.com/badlogic/pi-skills.git
git -C pi-skills checkout 90bb51cae36515a648515b633a81c0c6efc8c74d

Esses comandos consultam a rede, gravam o repositório completo e alteram o checkout do clone. Revise a origem e o conteúdo antes de copiar. O ZIP do Bastidores é menor e documental: contém apenas SKILL.md, LICENSE e ORIGEM.md, sem VS Code ou Git.

Configuração antes do primeiro uso

Confirme três pontos: qual repositório está em escopo, quais duas versões serão comparadas e onde o arquivo temporário será criado. Peça ao agente para mostrar o comando planejado e os dois caminhos antes de executá-lo. Se o arquivo contiver segredos, dados pessoais ou código restrito, não abra a comparação em uma sessão compartilhada ou transmitida.

Também vale confirmar o executável com code --version e o repositório com git status --short. Esses comandos não substituem autorização, mas reduzem o risco de abrir o editor errado ou usar uma pasta diferente da esperada.

Primeiro uso com dois arquivos existentes

O caso mais seguro não precisa de Git nem cria temporário. Escolha dois arquivos já existentes e use a forma longa, que deixa a intenção mais clara:

code --diff caminho/versao-anterior.txt caminho/versao-atual.txt

O resultado esperado é uma janela de diferenças com um arquivo de cada lado e marcações visuais das linhas alteradas. Antes de decidir, confira os nomes exibidos no editor. Dois arquivos com nomes parecidos podem pertencer a diretórios, clientes ou branches diferentes.

Comparar o arquivo atual com um commit

A documentação oficial do git show explica que o comando pode exibir objetos Git, inclusive o conteúdo de um blob. A notação revisão:caminho permite obter a versão de um arquivo armazenada em determinado commit.

No exemplo original, essa saída é redirecionada para /tmp/old e depois aberta com code -d. Antes disso, confirme que a revisão e o caminho existem:

git log --oneline -5 -- caminho/do/arquivo
git show HEAD~1:caminho/do/arquivo

O segundo comando imprime o conteúdo no terminal. Só crie o temporário depois de verificar que a origem está correta e que a saída não é grande, binária ou sensível.

Use um temporário exclusivo

O nome fixo /tmp/old é didático, mas pode colidir com outro processo ou com um arquivo deixado por execução anterior. Em Bash, prefira gerar um nome exclusivo, conferir a variável e só então redirecionar:

old_file="$(mktemp)"
git show HEAD~1:caminho/do/arquivo > "$old_file"
code --diff "$old_file" caminho/do/arquivo

Esse fluxo cria um arquivo e abre uma aplicação gráfica. A remoção do temporário deve acontecer apenas depois que o editor não precisar mais dele. Em automações, registre o caminho sem registrar o conteúdo.

Adaptação para Windows e PowerShell

A Skill original não traz um exemplo nativo de PowerShell. Não substitua /tmp/old por um nome previsível na pasta do projeto. Use New-TemporaryFile ou a API de caminho temporário para obter um destino exclusivo, mas valide a codificação quando redirecionar saída de um processo nativo.

Para arquivos de texto, diferenças de codificação ou fim de linha podem aparecer como mudanças que não existiam no blob. Quando a identidade byte a byte for importante, compare tamanho e SHA-256, ou use uma ferramenta que preserve bytes. Não use esse fluxo para imagens, documentos compactados ou outros binários.

Comparar stage e working tree

A notação :caminho/do/arquivo representa o blob armazenado no índice do Git. O exemplo da Skill materializa essa versão e a compara com o arquivo da árvore de trabalho. Isso ajuda a conferir o que será incluído no próximo commit, especialmente quando ainda existem mudanças não adicionadas.

O editor visual não altera o stage por si só, mas qualquer comando adicional executado no terminal pode alterar o repositório. Mantenha a sessão em modo de revisão. Não permita git add, commit, restore ou descarte de mudanças sem uma autorização separada.

Resultado esperado

Uma execução correta termina com o editor de diferenças aberto, os dois lados identificados e a origem histórica registrada. O usuário deve conseguir responder quais linhas mudaram, qual versão está à esquerda e qual está à direita, e se a comparação representa working tree, stage ou um commit específico.

O sucesso não é apenas abrir uma janela. É abrir a janela certa, com caminhos confirmados, sem sobrescrever um arquivo importante e sem transformar uma inspeção em alteração do repositório.

Permissões e riscos

git show e git log são usados aqui para leitura. O redirecionamento, porém, grava ou sobrescreve um arquivo. code --diff abre uma aplicação gráfica e pode restaurar extensões, configurações e estado da sessão do usuário. Isso exige consentimento quando o agente controla o computador.

O conteúdo aberto pode ficar visível em compartilhamento de tela, histórico recente do editor ou telemetria configurada pelo próprio ambiente. A Skill não analisa essas políticas. Use perfil de trabalho apropriado, menor privilégio e dados autorizados.

Erros comuns e como corrigir

• code não encontrado: confirme a instalação do VS Code e se o diretório do executável está no PATH. Em VS Code Insiders, o comando pode ser code-insiders.
• Dois arquivos iguais: confirme a revisão, o caminho e se houve mudança no período escolhido.
• Path does not exist in revisão: use git log --oneline -- caminho e verifique renomeações ou criação posterior.
• Diff mostra o arquivo inteiro: investigue codificação, fim de linha e conversão ocorrida na criação do temporário.
• Arquivo temporário vazio: confira a saída e o código de retorno do git show antes de abrir o editor.
• Conteúdo sensível apareceu na tela: feche a comparação, interrompa o compartilhamento e trate o incidente conforme a política local.

Quando não usar

Não use a Skill quando a revisão precisa ficar inteiramente no terminal, quando uma aplicação gráfica não pode ser aberta, quando o arquivo é binário ou quando o ambiente não permite materializar versões históricas em disco. Também não use uma comparação visual isolada como evidência de teste, segurança ou correção.

Para entender a estrutura de uma mudança grande antes da revisão linha a linha, a PR Lens tem outra finalidade. Para revisar alterações com critérios de qualidade, a Open Code Review é mais abrangente. Esta Skill resolve especificamente a abertura de uma comparação visual.

Versão, licença e pacote auditado

A pasta não declara versão própria nem possui release separada. Esta curadoria usa o commit 90bb51cae36515a648515b633a81c0c6efc8c74d, de 06/06/2026. O arquivo de licença é MIT.

O ZIP local tem 2.379 bytes e três arquivos textuais: SKILL.md, LICENSE e ORIGEM.md. SHA-256: 401314f6936b4b45ac45e1f23ee750b3edc6f2c3091f98af1170f658178e188f.

O que a revisão editorial confirmou

O SKILL.md e a licença do pacote correspondem byte a byte ao commit fixado. A pasta oficial não contém scripts, dependências ou binários. O pacote do Bastidores não inclui Visual Studio Code, Git, extensões, repositórios, histórico, arquivos temporários, configurações, chaves, credenciais ou dados.

A curadoria também confirmou na documentação oficial do VS Code que -d e --diff abrem o editor de diferenças. Os exemplos históricos foram confrontados com a documentação oficial de git show e git log. Nenhum comando foi executado contra um repositório do leitor.

Checklist antes de executar

• Fixe o commit da Skill, a revisão Git e o caminho do arquivo.
• Confirme repositório, working tree, stage e direção da comparação.
• Use um arquivo temporário exclusivo e não previsível.
• Evite binários e confira codificação e fim de linha em arquivos de texto.
• Revise os dois caminhos antes de abrir o VS Code.
• Aprove separadamente escrita temporária, abertura gráfica e qualquer ação Git mutável.
• Feche e remova o temporário somente quando a comparação terminar.

Fontes oficiais consultadas

• Repositório badlogic/pi-skills, compatibilidade, instalação e licença declaradas.
• SKILL.md no commit auditado, comandos, requisitos e limitações originais.
• Licença MIT no commit auditado, permissão de redistribuição.
• Interface de linha de comando do Visual Studio Code, opções --diff, --version e requisitos de PATH.
• Edição básica no VS Code, uso do editor de diferenças.
• Documentação do git show, leitura de commits e blobs.
• Documentação do git log, histórico filtrado por caminho.