数据库初始化

此内容描述了 CodeQL CLI 的最新版本。有关此版本的更多信息，请参阅 https://github.com/github/codeql-cli-binaries/releases。

要在较早版本中查看此命令可用选项的详细信息，请在终端中使用 --help 选项运行该命令。

概要

Shell

codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

描述

[底层实现] 创建一个空的 CodeQL 数据库。

创建 CodeQL 数据库的框架结构，该结构尚未包含原始 QL 数据集，但已准备好运行提取步骤。此命令完成后，运行一个或多个 codeql database trace-command 命令，然后运行 codeql database finalize 来准备用于查询的数据库。

（此操作的一部分是解析相应语言包的位置并将其存储在数据库元数据中，这样就不需要在每个提取命令中重新执行此操作。无论如何，在提取操作过程中切换提取器都是无效的。）

选项

主要选项

`<database>`

[必填] 要创建的 CodeQL 数据库的路径。将创建此目录，并且必须不存在（但其父目录必须存在）。

如果给出--db-cluster选项，则这本身不会是一个数据库，而是一个将包含从同一源根构建的几种语言的数据库的目录。

重要的是，此目录不在构建过程会干扰的位置。例如，Maven 项目的target目录不是合适的选择。

`-s, --source-root=<dir>`

[必填] 根源代码目录。在许多情况下，这将是检出根目录。其中的文件被认为是此数据库的主要源文件。在某些输出格式中，将通过从此目录的相对路径引用文件。

`--[no-]overwrite`

[高级] 如果数据库已存在，则删除它并继续执行此命令，而不是失败。如果目录存在，但它看起来不像数据库，则会抛出错误。

`--[no-]force-overwrite`

[高级] 如果数据库已存在，即使它看起来不像数据库，也删除它并继续执行此命令，而不是失败。此选项应谨慎使用，因为它可能会递归删除整个数据库目录。

`--codescanning-config=<file>`

[高级] 读取 Code Scanning 配置文件，该文件指定有关如何创建 CodeQL 数据库以及在后续步骤中运行哪些查询的选项。有关此配置文件格式的更多详细信息，请参阅自定义代码扫描的高级设置。要在后续步骤中从此文件运行查询，请调用 codeql database analyze，无需指定任何其他查询。

`--[no-]db-cluster`

不创建单个数据库，而是为不同的语言创建数据库“集群”，每个数据库都是命令行上给出的目录的子目录。

`-l, --language=<lang>[,<lang>...]`

将用于分析的新数据库的语言。

使用 codeql resolve languages 获取搜索路径上找到的可插入语言提取器的列表。

给出--db-cluster选项时，此选项可以多次出现，或者该值可以是语言的逗号分隔列表。

如果省略此选项，并且正在分析的源根是 GitHub 存储库的检出，则 CodeQL CLI 将调用 GitHub API 以尝试自动确定要分析的语言。请注意，要能够执行此操作，必须在环境变量 GITHUB_TOKEN 中或通过使用--github-auth-stdin选项使用标准输入提供 GitHub PAT 令牌。

`--build-mode=<mode>`

将用于创建数据库的构建模式。

根据您正在分析的语言选择您的构建模式

none：将在不构建源根的情况下创建数据库。适用于 C#、Java、JavaScript/TypeScript、Python 和 Ruby。

autobuild：将尝试自动构建源根来创建数据库。适用于 C/C++、C#、Go、Java/Kotlin 和 Swift。

manual：将使用手动指定的构建命令来构建源根创建数据库。适用于 C/C++、C#、Go、Java/Kotlin 和 Swift。

使用--command创建数据库时，无需另外指定“--build-mode manual”。

自v2.16.4版本起可用。

`--[no-]allow-missing-source-root`

[高级] 即使指定的源根不存在，也要继续执行。

`--[no-]begin-tracing`

[高级] 创建一些可用于设置“间接构建跟踪”的脚本，当没有可用的显式构建命令时，允许集成到现有的构建工作流程中。有关何时以及如何使用此功能的信息，请参阅我们的文档为 CodeQL 分析准备代码。

基线计算选项

`--[no-]calculate-baseline`

[高级] 计算被分析代码的基线信息并将其添加到数据库中。默认情况下，除非源根目录是文件系统的根目录，否则启用此功能。此标志可用于禁用或强制启用此行为，即使在文件系统的根目录中也是如此。

`--[no-]sublanguage-file-coverage`

[仅限 GitHub.com 和 GitHub Enterprise Server v3.12.0+] 使用子语言文件覆盖率信息。这将计算、显示和导出共享 CodeQL 提取器（如 C 和 C++、Java 和 Kotlin 以及 JavaScript 和 TypeScript）的语言的单独文件覆盖率信息。

自 v2.15.2 起可用。

提取器选择选项

`--search-path=<dir>[:<dir>...]`

可能找到提取器包的目录列表。这些目录可以是提取器包本身，也可以是包含提取器作为直接子目录的目录。

如果路径包含多个目录树，则它们的顺序定义它们之间的优先级：如果目标语言在多个目录树中匹配，则先给出的目录树优先。

CodeQL 工具链自带的提取器将始终被找到，但是如果您需要使用单独分发的提取器，则需要使用此选项（或者，最好在每个用户的配置文件中设置--search-path）。

（注意：在 Windows 上，路径分隔符为;）。

配置如何调用 GitHub API 以自动检测语言的选项

`-a, --github-auth-stdin`

通过标准输入接受 GitHub Apps 令牌或个人访问令牌。

这将覆盖 GITHUB_TOKEN 环境变量。

`-g, --github-url=<url>`

要使用的 GitHub 实例的 URL。如果省略，CLI 将尝试从签出路径自动检测此 URL，如果无法检测，则默认为 https://github.com/

配置包管理器的选项

`--registries-auth-stdin`

通过传递以逗号分隔的 <registry_url>=<token> 对列表来向 GitHub Enterprise Server 容器注册表进行身份验证。

例如，您可以传递 https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 来向两个 GitHub Enterprise Server 实例进行身份验证。

这将覆盖 CODEQL_REGISTRIES_AUTH 和 GITHUB_TOKEN 环境变量。如果您只需要向 github.com 容器注册表进行身份验证，则可以使用更简单的 --github-auth-stdin 选项进行身份验证。

配置 Windows 跟踪的选项

`--trace-process-name=<process-name>`

[仅限 Windows] 初始化跟踪时，将跟踪器注入到其名称与该参数匹配的 CodeQL CLI 的父进程中。如果多个父进程具有此名称，则选择进程树中级别最低的进程。此选项将覆盖 --trace-process-level，因此如果同时传递这两个选项，则只使用此选项。

`--trace-process-level=<process-level>`

[仅限 Windows] 初始化跟踪时，在当前进程之上注入这么多父进程的跟踪器，其中 0 对应于调用 CodeQL CLI 的进程。如果未传递任何参数，CLI 的默认行为是注入到调用进程的父进程中，对于 GitHub Actions 和 Azure Pipelines 有一些特殊情况。

配置间接构建跟踪的选项

`--extra-tracing-config=<tracing-config.lua>`

[高级] 跟踪器配置文件的路径。它可用于修改构建跟踪器的行为。它可用于挑选作为构建命令一部分运行的编译器进程，并触发其他工具的执行。提取器将提供在大多数情况下都适用的默认跟踪器配置文件。

设置 CodeQL 提取器的选项。extractor-option-name 应采用 extractor_name.group1.group2.option_name 或 group1.group2.option_name 的形式。如果 extractor_option_name 以提取器名称开头，则指示的提取器必须声明选项 group1.group2.option_name。否则，任何声明选项 group1.group2.option_name 的提取器都将设置该选项。value 可以是任何不包含换行符的字符串。

您可以重复使用此命令行选项来设置多个提取器选项。如果您为同一个提取器选项提供多个值，则行为取决于提取器选项期望的类型。字符串选项将使用提供的最后一个值。数组选项将按顺序使用所有提供的值。使用此命令行选项指定的提取器选项在通过 --extractor-options-file 给出的提取器选项之后进行处理。

当传递给 codeql database init 或 codeql database begin-tracing 时，这些选项将仅应用于间接跟踪环境。如果您的工作流程也对 codeql database trace-command 进行调用，则如果需要，也需要在那里传递这些选项。

有关 CodeQL 提取器选项的更多信息（包括如何列出每个提取器声明的选项），请参见 https://codeql.github.com/docs/codeql-cli/extractor-options。

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

指定提取器选项包文件。提取器选项包文件是设置提取器选项的 JSON 文件（扩展名 .json）或 YAML 文件（扩展名 .yaml 或 .yml）。该文件必须具有顶级映射键“extractor”，并在其下具有提取器名称作为二级映射键。更高级别的映射表示嵌套的提取器组，字符串和数组选项是具有字符串和数组值的映射条目。

提取器选项包文件按指定的顺序读取。如果不同的提取器选项包文件指定相同的提取器选项，则行为取决于提取器选项期望的类型。字符串选项将使用提供的最后一个值。数组选项将按顺序使用所有提供的值。使用此命令行选项指定的提取器选项在通过 --extractor-option 给出的提取器选项之前进行处理。

有关 CodeQL 提取器选项的更多信息（包括如何列出每个提取器声明的选项），请参见 https://codeql.github.com/docs/codeql-cli/extractor-options。

谁可以使用此功能？

本文内容