database init

注意

此内容描述了 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 数据库。

为尚未拥有原始 QL 数据集但已经准备好运行提取器步骤的 CodeQL 数据库创建一个骨架结构。此命令完成后，运行一个或多个 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>`

[高级] 读取一个代码扫描配置文件，指定如何创建 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 应用令牌或个人访问令牌。

这会覆盖 GITHUB_TOKEN 环境变量。

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

要使用的 GitHub 实例的 URL。如果省略，CLI 将尝试从检出路径自动检测；若无法检测，则默认使用 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 以提取器名称开头，则对应的提取器必须声明该 option group1.group2.option_name。否则，声明了该 option 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。

谁可以使用此功能？

本文内容