Skip to main content

database index-files

[Conexão] Indexe arquivos autônomos com um extrator do CodeQL especificado.

Quem pode usar esse recurso?

O CodeQL do GitHub é licenciado por usuário após a instalação. Você pode usar o CodeQL somente para determinadas tarefas sob as restrições de licença. Para obter mais informações, confira "Sobre a CLI do CodeQL".

Se você tiver uma licença do GitHub Advanced Security, poderá usar o CodeQL para análise automatizada, integração contínua e entrega contínua. Para obter mais informações, confira "Sobre a Segurança Avançada do GitHub".

Este conteúdo descreve a versão mais recente do CodeQL CLI. Para obter mais informações sobre essa versão, confira https://github.com/github/codeql-cli-binaries/releases.

Para ver os detalhes das opções disponíveis para esse comando em uma versão anterior, execute o comando com a opção --help no terminal.

Sinopse

Shell
codeql database index-files --language=<lang> [--threads=<num>] [--ram=<MB>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

Descrição

[Conexão] Indexe arquivos autônomos com um extrator do CodeQL especificado.

Esse comando seleciona um conjunto de arquivos no diretório de trabalho especificado e aplica o extrator especificado a eles. Por padrão, todos os arquivos são selecionados. As invocações típicas especificarão opções para restringir o conjunto de arquivos incluídos.

As opções --include, --exclude e --prune usam padrões glob, que podem usar os seguintes caracteres curinga:

  • Um único "?" corresponde a qualquer caractere diferente de uma barra "/" ou uma barra invertida;
  • Um único "*" corresponde a qualquer número de caracteres que não seja uma barra "/" ou uma barra invertida;
  • O padrão "**" corresponde a zero ou mais componentes de diretório completos.

Opções

Opções principais

<database>

[Obrigatório] Caminho para o banco de dados CodeQL em construção. Isso precisa ter sido preparado para extração com codeql database init.

-l, --language=<lang>

[Obrigatório] O extrator que deve ser usado para indexar arquivos correspondentes.

-j, --threads=<num>

Instrua o extrator a usar esse número de threads. Essa opção é transmitida para o extrator como uma sugestão. Se a variável de ambiente CODEQL_THREADS estiver definida, o valor da variável de ambiente terá precedência sobre essa opção.

Você pode transmitir 0 para usar um thread por núcleo no computador ou -N para manter N núcleos não utilizados (com a exceção de que ainda será usado, pelo menos, um thread).

-M, --ram=<MB>

Instrua o extrator a usar essa quantidade de memória. Essa opção é transmitida para o extrator como uma sugestão. Se a variável de ambiente CODEQL_RAM estiver definida, o valor da variável de ambiente terá precedência sobre essa opção.

--working-dir=<dir>

[Avançado] O diretório no qual o comando especificado deve ser executado. Se esse argumento não for fornecido, o comando será executado no valor de --source-root transmitido para codeql database create, se houver um. Se nenhum argumento --source-root for fornecido, o comando será executado no diretório de trabalho atual.

Opções para controlar o comportamento do extrator

-O, --extractor-option=<extractor-option-name=value>

Defina as opções para os extratores do CodeQL. extractor-option-name deve ter o formato extractor_name.group1.group2.option_name ou group1.group2.option_name. Se extractor_option_name começar com o nome de um extrator, o extrator indicado precisará declarar a opção group1.group2.option_name. Caso contrário, qualquer extrator que declare a opção group1.group2.option_name terá a opção definida. value pode ser qualquer cadeia de caracteres que não contenha uma nova linha.

Use essa opção de linha de comando repetidamente para definir várias opções de extratores. Se você fornecer vários valores para a mesma opção de extrator, o comportamento dependerá do tipo esperado pela opção de extrator. As opções de cadeia de caracteres usarão o último valor fornecido. As opções de matriz usarão todos os valores fornecidos, em ordem. As opções de extratores especificadas com essa opção de linha de comando são processadas após as opções de extratores fornecidas por meio de --extractor-options-file.

Quando transmitido para codeql database init ou codeql database begin-tracing, as opções serão aplicadas somente ao ambiente de rastreamento indireto. Se o fluxo de trabalho também fizer chamadas a codeql database trace-command, as opções também precisarão ser transmitidas para ele, se desejado.

Confira https://codeql.github.com/docs/codeql-cli/extractor-options para obter mais informações sobre as opções do extrator do CodeQL, incluindo como listar as opções declaradas pelos extratores.

--extractor-options-file=<extractor-options-bundle-file>

Especifique os arquivos de pacote de opções de extratores. Um arquivo de pacote de opções de extratores é um arquivo JSON (extensão .json) ou um arquivo YAML (extensão .yaml ou .yml) que define as opções de extratores. O arquivo precisa ter a chave de mapa de nível superior 'extractor' e, abaixo dela, os nomes de extratores como chaves de mapa de segundo nível. Outros níveis de mapas representam grupos de extratores aninhados, e as opções de cadeia de caracteres e matriz são entradas de mapa com valores de cadeia de caracteres e matriz.

Os arquivos do pacote de opções de extratores são lidos na ordem em que são especificados. Se diferentes arquivos do pacote de opções de extratores especificarem a mesma opção de extrator, o comportamento dependerá do tipo esperado pela opção de extrator. As opções de cadeia de caracteres usarão o último valor fornecido. As opções de matriz usarão todos os valores fornecidos, em ordem. As opções de extratores especificadas com essa opção de linha de comando são processadas antes das opções de extratores fornecidas por meio de --extractor-option.

Quando transmitido para codeql database init ou codeql database begin-tracing, as opções serão aplicadas somente ao ambiente de rastreamento indireto. Se o fluxo de trabalho também fizer chamadas a codeql database trace-command, as opções também precisarão ser transmitidas para ele, se desejado.

Confira https://codeql.github.com/docs/codeql-cli/extractor-options para obter mais informações sobre as opções do extrator do CodeQL, incluindo como listar as opções declaradas pelos extratores.

Opções para limitar o conjunto de arquivos indexados

--include-extension=<.ext>

Inclua todos os arquivos na árvore de diretórios de pesquisa que têm a extensão fornecida. Normalmente, você deve incluir o ponto antes da extensão. Por exemplo, se você transmitir --include-extension .xml, isso incluirá todos os arquivos com a extensão ".xml". Essa opção é incompatível com as opções --include negadas.

--include=<glob>

Inclua todos os arquivos e os diretórios na árvore de diretórios de pesquisa que correspondam ao glob fornecido, usando o caminho relativo de cada arquivo e diretório do diretório de pesquisa. Se o glob começar com um caractere !, os arquivos e os diretórios correspondentes serão excluídos.

As opções --include são processadas em ordem, com as opções posteriores substituindo as anteriores. Por exemplo, --include ** --include !sub/*.ts --include sub/main.* incluirá sub/main.ts (porque é incluído por sub/main.*), excluirá sub/index.ts (porque é excluído por !sub/*.ts) e incluirá sub/test.js (porque é incluído por ** sem ser excluído posteriormente).

--also-match=<glob>

Exija que todos os resultados também correspondam ao glob fornecido, usando o caminho relativo de cada arquivo e diretório do diretório de pesquisa. Essa opção tem a mesma estrutura e a mesma interpretação de --include, mas especifica uma sequência separada de globs que são aplicados em conjunto com --include.

--exclude=<glob>

Exclua todos os arquivos e os diretórios que correspondam ao glob fornecido, usando o caminho relativo de cada arquivo e diretório do diretório de pesquisa. Essa opção substitui todas as opções de inclusão. Essa opção é incompatível com as opções --include negadas.

--prune=<glob>

Exclua todos os arquivos e os diretórios que correspondam ao glob fornecido, usando o caminho relativo de cada arquivo e diretório do diretório de pesquisa. Essa opção substitui todas as opções de inclusão. Essa opção é incompatível com as opções --include negadas.

--size-limit=<bytes>

Exclua todos os arquivos cujo tamanho excede o limite especificado. O limite de tamanho é indicado em bytes ou em KiB (kibibytes) com o sufixo "k", em MiB (mebibytes) com o sufixo "m" e em GiB (gibibytes) com o sufixo "g". Essa opção substitui todas as opções de inclusão.

--total-size-limit=<bytes>

Faz com que o comando saia com um erro se o tamanho combinado de todos os arquivos resolvidos excede o limite fornecido. O limite de tamanho é indicado em bytes ou em KiB (kibibytes) com o sufixo "k", em MiB (mebibytes) com o sufixo "m" e em GiB (gibibytes) com o sufixo "g".

Siga os links simbólicos para os respectivos destinos.

--[no-]find-any

Encontre, no máximo, uma correspondência (em vez de todas as correspondências).

Disponível desde v2.11.3.

Opções comuns

-h, --help

Mostre este texto de ajuda.

-J=<opt>

[Avançado] Forneça a opção para a JVM que executa o comando.

(Use-a com cautela, pois as opções que contêm espaços não serão tratadas corretamente.)

-v, --verbose

Aumente incrementalmente o número de mensagens de progresso impressas.

-q, --quiet

Diminua incrementalmente o número de mensagens de progresso impressas.

--verbosity=<level>

[Avançado] Defina explicitamente o nível de detalhamento como erros, avisos, progresso, progresso+, progresso++ ou progresso+++. Substitui -v e -q.

--logdir=<dir>

[Avançado] Escreva logs detalhados em um ou mais arquivos no diretório fornecido, com nomes gerados que incluem carimbos de data/hora e o nome do subcomando em execução.

(Para gravar um arquivo de log com um nome sobre o qual você tem controle completo, forneça --log-to-stderr e redirecione stderr conforme desejado.)

--common-caches=<dir>

[Avançado] Controle a localização dos dados armazenados em cache no disco que persistirão entre várias execuções da CLI, como pacotes QL baixados e planos de consulta compilada. Se não for definido explicitamente, o padrão corresponde a um diretório intitulado .codeql no diretório inicial do usuário; que será criado se ainda não existir.

Disponível desde v2.15.2.