Referencia do CLI vdiff

Referencia completa de todos os comandos, flags e opcoes do vdiff incluindo analyze, graph, rules e integracao com CI

Analyze (comando padrão)

O comando analyze é o padrão. Executar vdiff sem subcomando o aciona.

Seleção do diff

bash

# Padrão inteligente: staged se houver, senão unstaged
vdiff

# Apenas mudanças staged
vdiff --staged

# Todas as mudanças (staged + unstaged)
vdiff --all

# Commit específico
vdiff --commit HEAD~1

# Diff de branch (revisão estilo PR)
vdiff --base main

# Diff via pipe
git diff | vdiff --stdin

Quando nenhuma flag explícita é passada, o vdiff verifica primeiro se há mudanças staged. Se existirem, analisa essas (você está prestes a commitar). Caso contrário, usa as mudanças unstaged. Quando a detecção automática escolhe staged e também existem mudanças unstaged, o rodapé mostra uma dica com a contagem de arquivos unstaged não incluídos.

Contexto e profundidade

bash

# Incluir código-fonte completo dos arquivos alterados
vdiff -f

# Análise profunda (modelo melhor + inclui arquivos completos automaticamente)
vdiff --thinking-level high

# Verificar mudanças contra uma spec, PRD ou arquivo de tarefa
vdiff -s docs/spec.md

# Combinar: análise profunda + verificação de spec
vdiff --thinking-level high -s docs/prd.md

# Analisar apenas arquivos que correspondem a um padrão
vdiff -p "src/auth/**"

--thinking-level high ativa automaticamente -f (contexto completo dos arquivos) e usa o modelo mais capaz configurado em llm.highModel.

Controle de saída

bash

# Verbose: mostrar todas as seções e todos os achados
vdiff -v

# Saída JSON (para ferramentas / integração CI)
vdiff --format json

# Saída Markdown (para comentários em PRs)
vdiff --format markdown

# Debug: mostrar progresso da análise e diagnósticos
vdiff -d

Todas as flags do analyze

Flag	Curta	Padrão	Descrição
`--staged`		`false`	Analisar apenas mudanças staged
`--all`		`false`	Analisar mudanças staged + unstaged
`--commit <ref>`			Analisar um commit específico
`--base <branch>`			Comparar branch atual contra uma branch alvo
`--stdin`		`false`	Ler diff do stdin
`--files`	`-f`	`false`	Incluir código-fonte completo dos arquivos alterados
`--spec <files...>`	`-s`		Verificar mudanças contra arquivos de spec/PRD/tarefa
`--path <glob>`	`-p`		Analisar apenas arquivos que correspondem ao padrão
`--thinking-level`		`low`	Profundidade da análise: `low` ou `high`
`--format`		`pretty`	Formato de saída: `pretty`, `json` ou `markdown`
`--verbose`	`-v`	`false`	Mostrar todas as seções e todos os achados
`--min`		`low`	Severidade mínima para exibir: `high`, `medium`, `low`
`--debug`	`-d`	`false`	Mostrar progresso da análise e diagnósticos
`--graph <path>`	`-g`		Usar um graph.json específico
`--no-graph`		`false`	Pular contexto do grafo de conhecimento
`--fresh`		`false`	Ignorar registro de achados, começar do zero
`--strict`		`false`	Sair com código não-zero em veredito `caution`
`--verify`		`false`	Passo extra de LLM para verificar achados HIGH
`--no-feedback`		`false`	Pular o prompt de utilidade pós-execução

Config

Gerenciar valores de configuração. Config local (.vdiff/config.json) sobrescreve global (~/.vdiff/config.json).

bash

vdiff config set -g llm.apiKey sk-ant-...   # Definir globalmente
vdiff config set llm.model gpt-4o-mini      # Definir localmente (projeto)
vdiff config get llm.provider               # Obter um valor
vdiff config list -g                        # Listar config global
vdiff config list                           # Listar config mesclada
vdiff config path                           # Mostrar locais dos arquivos de config

Todos os subcomandos set, get e list aceitam -g / --global para direcionar ao arquivo de config global.

Graph

Gerenciar o grafo de conhecimento (powered by Graphify). Requer Python 3.10+ e pip install graphifyy.

bash

vdiff graph init [path]    # Construir um grafo de conhecimento (padrão: diretório atual)
vdiff graph update [path]  # Atualização incremental
vdiff graph status         # Verificar status do grafo

O grafo fornece contexto de dependências cross-file: raio de impacto, god nodes, pertencimento a comunidade e sinais de cruzamento de comunidade. Armazenado em graphify-out/graph.json por padrão.

Rules

Definir regras específicas do projeto que persistem entre análises.

bash

vdiff rule add "Rotas de API devem validar o corpo da requisição"
vdiff rule add --scope "src/billing/**" "Nunca importar diretamente de orders"
vdiff rule list
vdiff rule remove <n>
vdiff rule clear

A flag --scope (-s) limita uma regra para aplicar apenas quando arquivos correspondentes aparecem no diff. As regras são armazenadas em .vdiff/rules/learned.md.

Você também pode criar arquivos de regras diretamente em .vdiff/rules/ como .md ou .txt.

Hook

Instalar um hook de pre-commit que executa o vdiff automaticamente antes de cada commit.

bash

# Instalar (bloqueia severidade high por padrão)
vdiff hook install

# Bloquear em severidade high + medium
vdiff hook install --block-on high,medium

# Apenas informativo (sem bloqueio)
vdiff hook install --block-on none

# Verificar se está instalado
vdiff hook status

# Remover o hook
vdiff hook remove

Por padrão, o hook bloqueia commits que introduzem achados de alta severidade (segurança, perda de dados, bypass de autenticação, risco financeiro). Para ignorar, use git commit --no-verify.

Configure o limite de bloqueio via config:

bash

vdiff config set hook.blockOn '["high","medium"]'

O hook usa um marcador para se identificar e não sobrescreve hooks existentes que não sejam do vdiff.

Integração com IDE

Instalar o vdiff no seu assistente de código com IA.

bash

vdiff ide install cursor       # Cursor
vdiff ide install windsurf     # Windsurf
vdiff ide install claude-code  # Claude Code
vdiff ide install              # Todas as IDEs detectadas
vdiff ide status               # Verificar status
vdiff ide remove cursor        # Remover

A regra instalada ensina o assistente de IA quais comandos do vdiff executar, como interpretar a saída e como apresentar os achados.

Histórico de revisões

bash

vdiff reviews              # Navegar pelas revisões passadas (seletor interativo)
vdiff reviews list         # Listar todas as revisões armazenadas (não-interativo)
vdiff reviews show <index> # Mostrar uma revisão passada específica (0 = mais recente)

Suporta as flags --format (pretty ou json), --verbose e --min <severity>.

Dismiss

Marcar achados como intencionalmente aceitos.

bash

vdiff dismiss <id>              # Descartar um único achado
vdiff dismiss --all             # Descartar todos os achados abertos
vdiff dismiss <id> --reason "Decisão intencional de design"

Sem um id ou --all, imprime a lista de achados abertos.

Metrics

Visualizar métricas de saúde estrutural do seu grafo de conhecimento.

bash

vdiff metrics                    # Mostrar métricas (requer graph.json)
vdiff metrics --format json      # Saída JSON para tooling

Exibe métricas de complexidade, acoplamento e saúde derivadas do seu grafo de dependências.

Códigos de saída

Código	Significado
`0`	Veredito é `ready` ou `caution`
`1`	Veredito é `not_ready`

Com --strict, caution também sai com 1.

← Primeiros Passos com vdiff Guia de Configuracao do vdiff→