Entender a sintaxe de pesquisa de código do GitHub

Você pode criar consultas de pesquisa para os resultados desejados com qualificadores de código especializados, expressões regulares e operações boolianas.

Neste artigo

Sobre a estrutura de consulta de pesquisa de código

A sintaxe de pesquisa neste artigo aplica-se somente ao código de pesquisa com pesquisa de código GitHub. Observe que a sintaxe e os qualificadores para pesquisar conteúdos não relacionados ao código, como problemas, usuários e discussões, não é igual à sintaxe para pesquisa de código. Para obter mais informações sobre a pesquisa sem código, confira "Sobre a pesquisa no GitHub" e "Pesquisar no GitHub".

As consultas de pesquisa consistem em termos de pesquisa, incluindo o texto que você deseja procurar e qualificadores, que restringem a pesquisa.

Um termo simples sem qualificadores corresponderá ao conteúdo de um arquivo ou ao caminho do arquivo.

Por exemplo, a seguinte consulta:

http-push

A consulta acima corresponderá ao arquivo docs/http-push.txt, mesmo que ele não contenha o termo http-push. Ela também corresponderá a um arquivo chamado example.txt se ele contiver o termo http-push.

Você pode inserir vários termos separados por espaço em branco para pesquisar documentos que satisfaçam os dois termos.

Por exemplo, a seguinte consulta:

sparse index

Os resultados da pesquisa incluiriam todos os documentos que contêm os termos sparse e index, em qualquer ordem. Como exemplos, ele corresponderia a um arquivo que contém SparseIndexVector, um arquivo com a frase index for sparse trees e até mesmo um arquivo chamado index.txt que contém o termo sparse.

A procura de vários termos separados por espaço em branco é equivalente à pesquisa hello AND world. Outras operações boolianas, como hello OR world, também são compatíveis. Para obter mais informações sobre operações boolianas, confira "Como usar operações boolianas".

A pesquisa de código também dá suporte à pesquisa de uma cadeia de caracteres exata, incluindo espaços em branco. Para obter mais informações, confira "Consultar uma correspondência exata".

Você pode restringir a pesquisa de código com qualificadores especializados, como repo:, language: e path:. Para saber sobre os qualificadores que podem ser usados na pesquisa de código, confira "Usando qualificadores".

Você também pode usar expressões regulares em suas pesquisas colocando a expressão entre barras duplas. Para obter mais informações de como usar expressões regulares, confira "Como usar expressões regulares".

Consultar uma correspondência exata

Para procurar uma cadeia de caracteres exata, incluindo espaço em branco, você pode colocar a cadeia de caracteres entre aspas. Por exemplo:

"sparse index"

Você também pode usar cadeias de caracteres entre aspas em qualificadores, por exemplo:

path:git language:"protocol buffers"

Procurando cotações e barras invertidas

Para procurar um código que contenha uma aspa, você pode fazer o escape da aspa usando uma barra invertida. Por exemplo, para localizar a cadeia de caracteres name = "tensorflow" exata, você pode pesquisar:

"name = \"tensorflow\""

Para procurar código contendo uma barra invertida \, use uma barra invertida dupla, \\.

As duas sequências de escape \\ e \" podem ser usadas fora das aspas também. Nenhuma outra sequência de escape é reconhecida, no entanto. Uma barra invertida que não é seguida por nenhum dos dois " ou \ está incluída na pesquisa, inalterada.

Sequências de escape adicionais, como \n para corresponder a um caractere de nova linha, têm suporte em expressões regulares. Consulte "Usando expressões regulares".

Como usar operações boolianas

A pesquisa de código dá suporte a expressões boolianas. Você pode usar os operadores AND, OR e NOT para combinar termos de pesquisa.

Por padrão, os termos adjacentes separados por espaço em branco são equivalentes ao uso do operador AND. Por exemplo, a consulta de pesquisa sparse index é a mesma que sparse AND index, o que significa que os resultados da pesquisa incluirão todos os documentos que contenham os termos sparse e index, em qualquer ordem.

Para procurar documentos que contenham um termo ou outro, você pode usar o operador OR. Por exemplo, a consulta a seguir corresponderá aos documentos que contenham sparse ou index:

sparse OR index

Para excluir arquivos dos resultados da pesquisa, você pode usar o operador NOT. Por exemplo, para excluir os arquivos no diretório __testing__, você pode pesquisar:

"fatal error" NOT path:__testing__

Você pode usar parênteses para expressar expressões boolianas mais complicadas. Por exemplo:

(language:ruby OR language:python) AND NOT path:"/tests/"

Como usar qualificadores

Você pode usar palavras-chave especializadas para qualificar a pesquisa.

Qualificador de repositório

Para pesquisar em um repositório, use o qualificador repo:. Você precisa fornecer o nome completo do repositório, incluindo o proprietário. Por exemplo:

repo:github-linguist/linguist

Para pesquisar em um conjunto de repositórios, você pode combinar vários qualificadores repo: com o operador booliano OR. Por exemplo:

repo:github-linguist/linguist OR repo:tree-sitter/tree-sitter

Observação: a pesquisa de código atualmente não dá suporte a expressões regulares ou correspondência parcial para nomes de repositório, portanto, será necessário digitar o nome completo do repositório (incluindo o prefixo do usuário) para que o qualificador repo: funcione.

Qualificadores de organização e usuário

Para procurar arquivos em uma organização, use o qualificador org:. Por exemplo:

org:github

Para procurar arquivos em uma conta pessoal, use o qualificador user:. Por exemplo:

user:octocat

Observação: a pesquisa de código atualmente não dá suporte a expressões regulares ou correspondência parcial para organização ou nomes de usuário, portanto, será necessário digitar toda a organização ou nome de usuário para que o qualificador funcione.

Qualificador de linguagem

Para restringir a linguagem específicos, use o qualificador language:. Por exemplo:

language:ruby OR language:cpp OR language:csharp

Para ver a lista completa de nomes de linguagens com suporte, confira languages.yaml em github-linguist/linguist. Se a linguagem preferencial não estiver na lista, você poderá abrir uma solicitação de pull para adicioná-la.

Qualificador de caminho

Para pesquisar dentro de caminhos de arquivo, use o qualificador path:. Isso corresponderá aos arquivos que contêm o termo em qualquer lugar no caminho do arquivo. Por exemplo, para localizar arquivos que contêm o termo unit_tests no caminho, use:

path:unit_tests

A consulta acima corresponderá a src/unit_tests/my_test.py e a src/docs/unit_tests.md, pois ambos contêm unit_test em algum lugar do caminho.

Para corresponder apenas a um nome de arquivo específico (e não a parte do caminho), use uma expressão regular:

path:/(^|\/)README\.md$/

Observe que o . no nome do arquivo tem escape, pois . tem um significado especial para expressões regulares. Para obter mais informações de como usar expressões regulares, confira "Como usar expressões regulares".


Você também pode usar algumas expressões de glob limitadas no qualificador path:.

Por exemplo, para procurar arquivos com a extensão txt, você pode usar:

path:*.txt

Para procurar arquivos JavaScript em um diretório `src`, você pode usar: 
path:src/*.js

  • Por padrão, as expressões glob não são ancoradas no início do caminho, portanto, a expressão acima ainda corresponderia a um caminho como app/src/main.js. No entanto, se você prefixar a expressão com /, ela será ancorada no início. Por exemplo:

    path:/src/*.js

  • Observe que * não corresponde ao caractere /, portanto, para o exemplo acima, todos os resultados serão descendentes diretos do diretório src. A fim de corresponder em subdiretórios, para que os resultados incluam arquivos profundamente aninhados, como /src/app/testing/utils/example.js, use **. Por exemplo:

    path:/src/**/*.js

Você também pode usar o caractere global ?. Por exemplo, para corresponder ao caminho file.aac ou file.abc, você pode usar:

path:*.a?c

Para procurar um nome de arquivo que contenha um caractere especial como `*` ou `?`, basta usar uma cadeia de caracteres entre aspas: 
path:"file?"

As expressões glob são desabilitadas em cadeias de caracteres entre aspas, portanto a consulta acima corresponderá apenas a caminhos que contenham a cadeia de caracteres literal file?.

Qualificador de símbolo

Você pode procurar definições de símbolo no código, como definições de função ou de classe, usando o qualificador symbol:. A pesquisa de símbolos se baseia na análise do código usando o ecossistema do analisador de código aberto Tree-sitter, portanto, não é necessária nenhuma configuração ou integração de ferramentas de build adicional.

Por exemplo, para procurar um símbolo chamado WithContext:

language:go symbol:WithContext

Em algumas linguagens, você pode procurar símbolos usando um prefixo (por exemplo, um prefixo do nome da classe). Por exemplo, para um método deleteRows em um struct Maint, você pode pesquisar symbol:Maint.deleteRows se estiver usando o Go ou symbol:Maint::deleteRows no Rust.

Você também pode usar expressões regulares com o qualificador de símbolo. Por exemplo, a consulta a seguir localizaria conversões que as pessoas implementaram no Rust para o tipo String:

language:rust symbol:/^String::to_.*/

Observe que esse qualificador procura apenas definições e não referências, e nem todos os tipos de símbolo ou linguagens já contam com suporte completo. A extração de símbolos é compatível com as linguagens a seguir.

  • C#
  • Python
  • Go
  • Java
  • JavaScript
  • TypeScript
  • PHP
  • Buffers de protocolo
  • Ruby
  • Rust

Estamos trabalhando para adicionar o suporte para mais linguagens. Se você quiser contribuir com essas ações, adicione suporte para sua linguagem no ecossistema de analisadores de código aberto Tree-sitter, no qual a pesquisa de símbolos se baseia.

Qualificador de conteúdo

Por padrão, os termos simples pesquisam os caminhos e o conteúdo do arquivo. Para restringir uma pesquisa para corresponder exatamente ao conteúdo de um arquivo e não aos caminhos de arquivo, use o qualificador content:. Por exemplo:

content:README.md

Essa consulta corresponderia apenas a arquivos que contenham o termo README.md, em vez de corresponder a arquivos chamados README.md.

Qualificador Is

Para filtrar com base nas propriedades do documento, você pode usar o qualificador is:. O is: oferece suporte aos seguintes valores:

  • archived: restringe a pesquisa a repositórios arquivados.
  • fork: restringe a pesquisa a repositórios com fork.
  • vendored: restringe a pesquisa ao conteúdo detectado como fornecedor.
  • generated: restringa a pesquisa ao conteúdo detectado como gerado.

Por exemplo:

path:/^MIT.txt$/ is:archived

Observe que o qualificador is: pode ser invertido com o operador NOT. Para procurar repositórios não arquivados, você pode pesquisar:

log4j NOT is:archived

Para excluir bifurcações dos resultados, você pode pesquisar:

log4j NOT is:fork

Como usar expressões regulares

A pesquisa de código dá suporte a expressões regulares para pesquisar padrões em seu código. Você pode usar expressões regulares em termos de pesquisa simples, bem como em muitos qualificadores, colocando a regex entre barras duplas.

Por exemplo, para procurar a expressão regular sparse.*index, você usaria:

/sparse.*index/

Observe que você precisará usar escape em todas as barras na expressão regular. Por exemplo, para pesquisar arquivos dentro do diretório App/src, você usaria:

/^App\/src\//

Dentro de uma expressão regular, \n significa um caractere de nova linha \t representa uma guia e \x{hhhh} pode ser usado para escapar de qualquer caractere Unicode. Isso significa que você pode usar expressões regulares para procurar cadeias de caracteres exatas que contenham caracteres que você não pode digitar na barra de pesquisa.

Os recursos de expressões regulares mais comuns funcionam na pesquisa de código. No entanto, as afirmações "look-around" não têm suporte.

Separar termos de pesquisas

Todas as partes de uma pesquisa, como termos de pesquisa, cadeias de caracteres exatas, expressões regulares, qualificadores, parênteses e as palavras-chave booleanas AND, OR e NOT devem ser separadas umas das outras com espaços. A única exceção é que os itens dentro de parênteses ( ) não precisam ser separados dos parênteses.

Se sua pesquisa contiver vários componentes que não estão separados por espaços ou outro texto que não siga as regras listadas acima, a pesquisa de código tentará adivinhar o que você quer dizer. Muitas vezes, ele recorre ao tratamento desse componente da consulta como o texto exato a ser pesquisado. Por exemplo, a seguinte consulta:

printf("hello world\n");

A pesquisa de código desistirá de interpretar os parênteses e aspas como caracteres especiais e, em vez disso, procurará arquivos contendo esse código exato.

Se a pesquisa de código der errado, você sempre poderá obter a pesquisa desejada usando aspas e espaços para deixar o significado claro.

Diferenciar maiúsculas de minúsculas

A pesquisa de código diferencia maiúsculas de minúsculas. A pesquisa por True incluirá resultados para maiúsculas TRUE e minúsculas true. Não é possível fazer pesquisas que diferenciam maiúsculas de minúsculas. Pesquisas por expressões regulares (por exemplo, para [t][H][i][S]) também não diferenciam maiúsculas de minúsculas e, portanto, retornariam This, THIS e this, além de quaisquer instâncias de tHiS.