Como pesquisar e organizar o histórico do repositório usando o GitHub

8 minutos

Aqui, discutimos como você pode usar filtros, blame e vinculação cruzada para pesquisar e organizar o histórico do repositório.

Coloque-se no lugar de um desenvolvedor que acabou de ingressar em um projeto grande. Alguém acabou de postar um novo problema relatando um bug relacionado à barra lateral do aplicativo Web e você foi atribuído para corrigi-lo. Você já leu o relatório algumas vezes e entendeu o problema que está sendo descrito, agora você precisa descobrir como começar a correção.

Como um novo membro da equipe, você ainda não está familiarizado com a base de código. Também não fez parte das discussões de planejamento, das revisões de código ou de qualquer outra coisa que lhe fornecesse o contexto necessário para iniciar a implementação. Primeiro, você precisará adquirir esse conhecimento base para determinar melhor a correção adequada.

Como pesquisar no GitHub

Embora você não estivesse presente nos eventos que levaram à implementação da barra lateral, muitos desses eventos estão no histórico do projeto. Pesquisar no repositório do projeto por "barra lateral" lhe dará um ponto de partida.

Há dois métodos de pesquisa disponíveis no GitHub: a pesquisa global na parte superior da página e a pesquisa com escopo disponível em determinadas guias de repositório. Eles dão suporte à mesma sintaxe e à mesma função da mesma forma, mas com algumas diferenças importantes.

Pesquisa global

A pesquisa global permite que você use a sintaxe de pesquisa completa para pesquisar em todo o GitHub.

Os resultados da pesquisa são abrangentes e incluem tudo, desde o código até os problemas, o Marketplace e até mesmo os usuários. Essa é a melhor maneira de localizar menções de termos-chave em vários tipos de resultados e de repositórios.

Observação

A cláusula de filtro is:pr filtra os problemas retornados do repositório de problemas/solicitações de pull. Algumas cláusulas de filtro, como is:pr, só têm suporte em determinados provedores de pesquisa e são ignoradas por outros. Por exemplo, o provedor de pesquisa de código não dá suporte a essa cláusula, então ele vai ignorá-la e retornará os mesmos resultados de código de qualquer forma.

Em nosso cenário, usar a pesquisa global com escopo para o repositório atual é uma boa maneira de localizar código e commits que mencionam o termo "barra lateral". Provavelmente, você também terá ocorrências de problemas e solicitações de pull, embora eles não sejam tão fáceis de filtrar na visualização dos resultados da pesquisa global.

Para criar uma pesquisa global complexa, tente a pesquisa avançada.

Pesquisa de contexto

As pesquisas de contexto estão disponíveis em determinadas guias, como Problemas e Solicitações de pull. Essas pesquisas têm como escopo o repositório atual e retornam apenas os resultados desse tipo. O benefício desse escopo é que ele permite que a interface do usuário exponha filtros específicos de tipos conhecidos, como autores, rótulos, projetos e outros.

Usar a pesquisa de contexto é a opção preferencial quando você está procurando algo no repositório atual. Em nosso cenário, esta é uma boa maneira de encontrar resultados de pesquisa que mencionem "barra lateral", os quais você pode então refinar facilmente usando os filtros disponíveis nas listas suspensas.

Há um número infinito de maneiras de pesquisar usando a sintaxe de pesquisa completa. No entanto, a maioria das pesquisas faz uso apenas de alguns filtros comuns. Embora com frequência elas estejam disponíveis em menus suspensos de pesquisa de contexto, às vezes é mais conveniente digitá-las diretamente.

Aqui estão alguns exemplos de consultas de filtro:

Consulta	Explicação
`is:open is:issue assignee:@me`	Problemas em aberto atribuídos ao usuário atual (`@me`)
`is:closed is:pr author:contoso`	Solicitações de pull fechadas criadas por `@contoso`
`is:pr sidebar in:comments`	Solicitações de pull nas quais "barra lateral" é mencionada nos comentários
`is:open is:issue label:bug -linked:pr`	Problemas em aberto rotulados como bugs que não têm uma solicitação de pull vinculada

Saiba mais sobre Noções básicas de sintaxe de pesquisa

O que é o git blame?

Apesar de seu nome ameaçador, git blame é um comando que exibe o histórico de commit de um arquivo. Ele facilita a visualização de quem fez as alterações e quando. Isso facilita muito rastrear outras pessoas que trabalharam em um arquivo a fim de buscar a contribuição ou a participação delas.

Observação

Alguns sistemas de Git tem um alias git praise em git blame para evitar a implicação de julgamento.

Blame no GitHub

O GitHub estende a funcionalidade básica de git blame com uma interface do usuário mais robusta.

Em nosso cenário, você pode chegar a esta exibição de algumas maneiras. Você pode ter encontrado algum código na barra lateral a partir da pesquisa global e selecionado a opção Responsabilizar para ver quem trabalhou nele por último, ou talvez tenha encontrado uma pull request e rastreado isso de volta para a última confirmação que parece relacionada à descrição do bug. Independente de como chegou até aqui, a exibição de blame é um modo eficaz de localizar um especialista no assunto para a tarefa em questão.

Problemas de vinculação cruzada, commit e muito mais

Parte do que torna o GitHub ótimo para projetos de software colaborativo é o suporte para vincular diferentes informações. Parte disso ocorre automaticamente, como quando você cria uma solicitação de pull de uma série de commits em um branch. Em outras ocasiões, você pode usar a interface para vincular manualmente as solicitações de pull ou os projetos aos problemas usando as opções suspensas.

Referências autovinculadas

Para facilitar ainda mais a vinculação cruzada de itens diferentes em todo o projeto, o GitHub oferece uma sintaxe abreviada. Por exemplo, se você deixar um comentário como Duplicate of #8, o GitHub reconhecerá que #8 é um problema e criará o link apropriado para você.

O GitHub também vinculará commits para você se você colar os primeiros sete ou mais caracteres da ID.

Em nosso cenário, esses links poderiam ser muito valiosos para incrementar se alguém tivesse se antecipado e deixado o contexto. Por exemplo, o estado atual da barra lateral pode ter tido alguns problemas conhecidos relacionados a uma dependência de JavaScript. Se o problema com essa dependência foi discutido em outra questão que não mencionou explicitamente "barra lateral", então seria difícil encontrá-lo. No entanto, se alguém tivesse se antecipado e vinculado o problema na discussão, muito do seu tempo poderia ter sido poupado. Lembre-se disso da próxima vez que você estiver documentando problemas e solicitações de pull.

Saiba mais sobre URLs e referências autovinculadas.

Loop em usuários com @mention

Além de vincular problemas e commits, muitas vezes é útil associar outras pessoas às discussões. A maneira mais fácil de fazer isso é usar um @mention. Esse tipo de menção notifica o usuário mencionado para que ele possa participar da discussão. Também é uma boa maneira de identificar as pessoas associadas a problemas muito tempo após eles terem sido fechados.