Rastreando Bugs no Git: Encontre o PR

O Problema

Você está debugando código e encontra um bug na linha 42 de um arquivo. As perguntas surgem imediatamente:

• 🤔 Quando essa linha foi modificada pela última vez?
• 👤 Quem fez a mudança?
• 📝 Por que foi alterada (contexto da mudança)?
• 🔍 Qual Pull Request introduziu o problema?

Este guia mostra o workflow simples de investigação, combinando Git e GitHub CLI para rastrear bugs desde a linha problemática até o PR responsável.

TL;DR (Workflow em 3 Passos)

# PASSO 1: Encontrar quando a linha foi modificada
git log -L 42,42:app/models/user.rb

# PASSO 2: Ver detalhes completos do commit suspeito
git show abc1234 --stat

# PASSO 3: Encontrar o PR que contém esse commit
gh pr list --search "abc1234" --state all
# ou se souber que está merged:
gh pr list --search "abc1234" --state merged

💡 Esse workflow permite identificar a origem de bugs em aplicações e entender o contexto completo da mudança.

Índice

• Workflow: Da Linha ao PR
• Passo 1: Rastrear Histórico da Linha
• Passo 2: Analisar o Commit
• Passo 3: Encontrar o Pull Request
• Comandos Complementares de Investigação
• Busca Avançada com git grep
• Boas Práticas
• Aliases Úteis
• Conclusão

Workflow Completo: Da Linha ao PR

Vamos seguir um caso em uma aplicação Rails. Imagine que você encontrou um bug nesta linha do modelo User:

# app/models/user.rb:42
class User < ApplicationRecord
  # ...

  validates :email, format: { with: /@/ }  # Bug: validação muito simplista!

  # ...
end

Essa validação de email só verifica se tem o símbolo @, permitindo emails inválidos como "teste@" ou "@exemplo". Vamos investigar quando e por que foi introduzido.

Cenário

• Arquivo: app/models/user.rb
• Linha: 42
• Problema: Validação de email aceita formatos inválidos
• Impacto: Usuários podem cadastrar emails inválidos no sistema
• Objetivo: Encontrar o PR que introduziu essa validação fraca

Passo 1: Rastrear Histórico da Linha

O comando mais poderoso para investigar uma linha específica é o git log -L. Ele mostra todo o histórico de uma linha, incluindo o código antes e depois de cada mudança.

Comando Principal

git log -L 42,42:app/models/user.rb

O que esse comando faz:

• Mostra todos os commits que modificaram a linha 42 do modelo User
• Exibe o diff (antes/depois) de cada mudança
• Lista autor, data e mensagem do commit

Saída Exemplo

commit abc1234567890
Author: João Silva <joao@example.com>
Date:   Mon Jan 20 14:30:00 2026

    feat: simplifica validação de email no User

diff --git a/app/models/user.rb b/app/models/user.rb
--- a/app/models/user.rb
+++ b/app/models/user.rb
@@ -42,1 +42,1 @@
-  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :email, format: { with: /@/ }  # Simplificado para melhorar performance

🎯 Achamos o culpado! O commit abc1234 substituiu a validação robusta do Rails (URI::MailTo::EMAIL_REGEXP) por uma regex simples que só verifica @.

Variação com Formato Compacto

Para ver apenas os hashes e mensagens:

git log -L 42,42:app/models/user.rb --oneline

Saída:

abc1234 feat: simplifica validação de email no User
def5678 refactor: adiciona validações customizadas

Rastrear Range de Linhas

Se o bug afeta múltiplas linhas próximas (por exemplo, validações relacionadas):

git log -L 40,50:app/models/user.rb

Isso mostra mudanças nas linhas 40 a 50, útil para ver todas as validações do modelo.

Passo 2: Analisar o Commit

Agora que identificamos o commit abc1234, vamos analisar todo o contexto dessa mudança para entender o que foi modificado.

Ver Resumo das Mudanças

git show --stat abc1234

Saída exemplo:

commit abc1234567890
Author: João Silva <joao@example.com>
Date:   Mon Jan 20 14:30:00 2026

    feat: simplifica validação de email no User

 app/models/user.rb           |  2 +-
 app/controllers/users_controller.rb  |  3 +--
 spec/models/user_spec.rb     | 18 ------------------
 3 files changed, 2 insertions(+), 21 deletions(-)

⚠️ Red flags detectados:

• Removeu 18 linhas de specs (spec/models/user_spec.rb)
• Modificou controller também (escopo maior que esperado)
• Mensagem diz “simplifica” (pode ter removido validações importantes)

Ver Diff Completo

Para ver todas as mudanças linha por linha:

git show abc1234

Isso mostra o diff completo de todos os arquivos modificados.

Ver Apenas Arquivos Modificados

git show --name-only abc1234

Saída:

app/models/user.rb
app/controllers/users_controller.rb
spec/models/user_spec.rb

Ver Informações do Autor

git show --format="%an (%ae)%nData: %ad%nMensagem: %s%n%b" --no-patch abc1234

Saída:

João Silva (joao@example.com)
Data: Mon Jan 20 14:30:00 2026
Mensagem: feat: simplifica validação de email no User

Substitui URI::MailTo::EMAIL_REGEXP por validação simples
para melhorar performance do save. Issue #123 reportou
lentidão ao criar usuários em batch.

Benchmarks mostram melhoria de 40% no throughput.

💡 Contexto importante: A mudança foi feita por motivo de performance em operações batch, mas sacrificou a validação correta de emails individuais.

Passo 3: Encontrar o Pull Request

Agora vem a parte crucial: descobrir qual PR contém esse commit. Isso nos dá:

• Discussões da code review
• Contexto completo da mudança
• Outros commits relacionados
• Quem aprovou o PR

Método 1: Buscar PR por Hash do Commit

O GitHub CLI permite buscar PRs que contêm um commit específico:

gh pr list --search "abc1234" --state all

Saída exemplo:

#127  feat: otimiza validação de email no User  feature/faster-validations  MERGED

🎯 Encontramos! O commit está no PR #127.

Método 2: Buscar Apenas PRs Mergeados

Se você sabe que o código já está em produção:

gh pr list --search "abc1234" --state merged

Ver Detalhes Completos do PR

gh pr view 127

Saída exemplo:

feat: otimiza validação de email no User #127
Merged • feature/faster-validations merged into main

  Melhora performance na criação de usuários em batch

  Mudanças:
  - Substitui URI::MailTo::EMAIL_REGEXP por validação simples
  - Remove specs redundantes de formato de email
  - Atualiza UsersController para usar validação client-side

  Performance:
  - Batch create de 1000 users: 45s → 27s (40% mais rápido)
  - Benchmarks no PR comment

  Fixes #123

───────────────────────────────────────
View this pull request on GitHub: https://github.com/empresa/projeto/pull/127

Ver Informações Específicas em JSON

Para análise programática:

gh pr view 127 --json number,title,author,createdAt,mergedAt,reviews,url

Saída JSON:

{
  "number": 127,
  "title": "feat: otimiza validação de email no User",
  "author": "joaosilva",
  "createdAt": "2026-01-20T14:00:00Z",
  "mergedAt": "2026-01-20T16:30:00Z",
  "reviews": [
    {
      "author": "mariasilva",
      "state": "APPROVED"
    }
  ],
  "url": "https://github.com/empresa/projeto/pull/127"
}

Ver Comentários do PR no Terminal

gh pr view 127 --comments

Isso mostra toda a discussão da code review, onde você pode encontrar:

• Questionamentos sobre a mudança
• Decisões tomadas
• Possíveis avisos ignorados

Método Alternativo: Verificar Branches

Se gh não estiver disponível, use Git puro:

# Ver em quais branches o commit está
git branch -a --contains abc1234

# Ver se está na main/master
git branch --contains abc1234 | grep -E "main|master"

Saída:

  main
  remotes/origin/main

Depois busque manualmente no GitHub por commits recentes merged na main.

Resumo do Workflow Completo

Juntando tudo, aqui está o fluxo de investigação de ponta a ponta:

# 1️⃣ DESCOBRIR: Encontrar o commit que modificou a linha
git log -L 42,42:app/models/user.rb --oneline

# Saída: abc1234 feat: otimiza validação de email no User

# 2️⃣ ANALISAR: Ver o que foi alterado no commit
git show --stat abc1234

# Revisar: models, specs, controllers modificados

# 3️⃣ INVESTIGAR: Encontrar o PR que contém o commit
gh pr list --search "abc1234" --state merged

# Saída: #127 feat: otimiza validação de email no User

# 4️⃣ CONTEXTO: Ver detalhes completos do PR
gh pr view 127 --comments

# Ler discussões da code review, benchmarks, trade-offs

O que Você Ganhou

✅ Hash do commit: abc1234 ✅ Autor: João Silva ✅ Data: 20 de janeiro de 2026 ✅ Motivo: Otimizar performance em batch creates (Issue #123) ✅ PR: #127 ✅ Reviewer: Maria Silva (aprovou) ✅ Trade-off: Sacrificou validação robusta por performance ✅ Impacto: Batch de 1000 users 40% mais rápido, mas emails inválidos aceitos

Com essas informações, você pode:

• Reverter o commit se necessário
• Discutir com o autor sobre a decisão
• Criar um PR de fix referenciando o problema original
• Aprender com o erro para futuras code reviews

Comandos Complementares de Investigação

Além do workflow principal, estes comandos são úteis para investigações mais complexas.

Buscar Commits por Mensagem

Encontre commits por palavras-chave:

git log --all --oneline --grep="validation"

# Case-insensitive
git log --all --oneline --grep="validation" -i

# Com regex
git log --all --oneline --grep="^feat:"

Ver Histórico Completo de um Arquivo

Útil para entender a evolução de um model ou controller:

git log --format="%h - %an - %ar: %s" -- app/models/user.rb

Buscar por Código Adicionado/Removido

Encontre quando um método específico foi adicionado ou removido:

git log -S "def email_valid?" --oneline -- app/models/

Isso mostra todos os commits que adicionaram ou removeram o método email_valid? nos models.

Buscar Mudanças em Associations

git log -S "has_many :posts" --oneline -- app/models/user.rb

Rastrear Mudanças em Migrations

git log --oneline -- db/migrate/*users*.rb

Instalando o GitHub CLI

Para usar o workflow completo, você precisa ter o GitHub CLI instalado.

Instalação

# Ubuntu/Debian
sudo apt install gh

# macOS
brew install gh

# Arch Linux
sudo pacman -S github-cli

# Windows (com Chocolatey)
choco install gh

Primeira Configuração

# Fazer login
gh auth login

# Verificar se está autenticado
gh auth status

Comandos Adicionais Úteis do GitHub CLI

# Listar PRs abertos
gh pr list

# Ver status de checks/CI do PR
gh pr checks 127

# Fazer checkout de um PR localmente
gh pr checkout 127

# Ver diff do PR
gh pr diff 127

# Abrir PR no navegador
gh pr view 127 --web

# Criar novo PR
gh pr create --title "fix: corrige validação" --body "Descrição"

# Mergear PR
gh pr merge 127 --squash

Busca Avançada com git grep

O git grep é mais rápido que grep normal pois busca apenas em arquivos rastreados pelo Git. Muito útil para encontrar padrões em aplicações Rails.

Buscar Validações em Models

git grep "validates" -- "app/models/*.rb"

Buscar Uso de uma Gem Específica

git grep "require.*sidekiq" -- "*.rb"

Buscar com Contexto

Para ver linhas ao redor do resultado (útil para ver toda a validação ou método):

git grep -C 5 "validates :email" -- app/models/user.rb

Opções de contexto:

• -A 5: Mostra 5 linhas depois (útil para ver o corpo de um método)
• -B 5: Mostra 5 linhas antes
• -C 5: Mostra 5 linhas antes e depois

Buscar Callbacks em Models

git grep -n "before_save\|after_save" -- "app/models/*.rb"

Buscar TODOs no Código

git grep -i "TODO\|FIXME" -- "*.rb"

Buscar Configurações Sensíveis

git grep -i "password\|secret\|key" -- "config/*.yml"

Agora que você conhece os principais comandos de investigação e busca, vamos ver como aplicá-los seguindo boas práticas que manterão seu repositório organizado e profissional.

Boas Práticas

✅ Commits Atômicos

Cada commit deve representar uma mudança lógica:

❌ Ruim:

feat: adiciona login, corrige bug no header e atualiza README

✅ Bom:

feat(auth): adiciona formulário de login
fix(header): corrige alinhamento do logo
docs: atualiza instruções de instalação

✅ Mensagens Descritivas

❌ Ruim:

fix bug
update code
changes
WIP

✅ Bom:

fix(auth): previne login com campos vazios
refactor(api): extrai lógica de validação para função separada
test(checkout): adiciona testes para fluxo de pagamento

✅ Commits Frequentes

Faça commits pequenos e frequentes em vez de grandes commits:

• Facilita code review
• Mais fácil de fazer revert
• Histórico mais claro
• Reduz conflitos de merge

✅ Use Branches Descritivas

❌ Ruim:

feature1
new-stuff
test

✅ Bom:

feature/user-authentication
fix/header-alignment
refactor/api-validation

Para tornar seu trabalho ainda mais eficiente, você pode criar aliases que transformam comandos longos em atalhos rápidos.

Aliases Úteis

Adicione ao seu ~/.gitconfig:

[alias]
    # Status resumido
    st = status --short

    # Log formatado
    lg = log --graph --oneline --decorate --all

    # Ver últimos commits
    last = log -1 HEAD --stat

    # Desfazer último commit mantendo mudanças
    undo = reset HEAD~1 --soft

    # Branches recentes
    recent = branch --sort=-committerdate

    # Amend sem editar mensagem
    amend = commit --amend --no-edit

    # Ver branches que contêm um commit
    contains = branch -a --contains

    # Limpar branches já mergeadas
    cleanup = "!git branch --merged | grep -v '\\*\\|main\\|master\\|develop' | xargs -n 1 git branch -d"

    # Aliases específicos para Rails
    # Ver histórico de models
    models = log --oneline -- app/models/

    # Ver histórico de migrations
    migrations = log --oneline -- db/migrate/

    # Buscar validações
    validations = grep "validates" -- "app/models/*.rb"

    # Ver mudanças em routes
    routes = log -p -- config/routes.rb

Uso:

# Aliases gerais
git st              # em vez de git status --short
git lg              # log visual bonito
git last            # ver último commit
git undo            # desfazer último commit
git recent          # ver branches recentes
git amend           # amend rápido
git contains abc123 # ver branches com commit
git cleanup         # limpar branches mergeadas

# Aliases específicos Rails
git models          # ver histórico de mudanças em models
git migrations      # ver histórico de migrations
git validations     # listar todas as validações em models
git routes          # ver mudanças em routes com diff

Para facilitar a consulta rápida, aqui está uma tabela resumindo os comandos mais importantes abordados neste guia:

Resumo dos Comandos Mais Úteis

Conclusão

Rastrear bugs de forma eficiente é uma habilidade essencial para todo desenvolvedor. Com o workflow apresentado neste guia, você pode:

🔍 Identificar rapidamente quando e onde um problema foi introduzido 🧠 Entender o contexto completo por trás de uma mudança 💬 Acessar discussões que levaram à decisão ⚡ Agir com conhecimento para corrigir ou reverter mudanças problemáticas

O Workflow em 3 Passos

1. git log -L → Encontrar o commit que modificou a linha
2. git show → Analisar o que foi alterado
3. gh pr list → Descobrir o PR responsável

Dica Final

Não tente decorar todos os comandos. Salve este guia e use como referência. Com o tempo, o workflow se tornará automático:

1. Bug em um model? → git log -L <linha>,<linha>:app/models/<model>.rb
2. Pegou o hash? → git show <hash> --stat
3. Quer o contexto? → gh pr list --search "<hash>"

Dominar esse workflow vai economizar horas de investigação e tornar você muito mais eficiente em debugging e code review!

Próximo passo: Comece usando o workflow hoje mesmo no próximo bug que você encontrar no seu projeto. A prática leva à perfeição!

Referências

• Git Documentation
• GitHub CLI Manual
• Conventional Commits
• Pro Git Book (gratuito)
• Git Flight Rules - Guia prático para situações específicas

Sobre Este Guia

Este workflow foi desenvolvido com base em experiência real de debugging em projetos Rails de produção. Todos os comandos foram testados e validados em situações reais de investigação.

Tem alguma dúvida ou sugestão de melhoria para o workflow? Compartilhe nos comentários!