Git
英语 ▾ 主题 ▾ 最新版本 ▾ git-submodule 最后更新于 2.47.0

名称

git-submodule - 初始化、更新或检查子模块

概要

git submodule [--quiet] [--cached]
git submodule [--quiet] add [<options>] [--] <repository> [<path>]
git submodule [--quiet] status [--cached] [--recursive] [--] [<path>…​]
git submodule [--quiet] init [--] [<path>…​]
git submodule [--quiet] deinit [-f|--force] (--all|[--] <path>…​)
git submodule [--quiet] update [<options>] [--] [<path>…​]
git submodule [--quiet] set-branch [<options>] [--] <path>
git submodule [--quiet] set-url [--] <path> <newurl>
git submodule [--quiet] summary [<options>] [--] [<path>…​]
git submodule [--quiet] foreach [--recursive] <command>
git submodule [--quiet] sync [--recursive] [--] [<path>…​]
git submodule [--quiet] absorbgitdirs [--] [<path>…​]

描述

检查、更新和管理子模块。

有关子模块的更多信息，请参见 gitsubmodules[7]。

命令

在没有参数的情况下，显示现有子模块的状态。有几个子命令可用于对子模块执行操作。

add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]

将给定的存储库作为子模块添加到给定路径，并将更改集提交到下一个要提交到当前项目中的更改集：当前项目称为“超级项目”。

<repository> 是新子模块的源存储库的 URL。这可以是绝对 URL，也可以是（如果以 ./ 或 ../ 开头）相对于超级项目的默认远程存储库的路径（请注意，要指定一个位于超级项目 bar.git 旁边的存储库 foo.git，您必须使用 ../foo.git 而不是 ./foo.git - 正如人们在遵循相对 URL 规则时所期望的那样 - 因为 Git 中对相对 URL 的评估与对相对目录的评估相同）。

默认远程是当前分支的远程跟踪分支的远程。如果没有这样的远程跟踪分支，或者 HEAD 是分离的，则假设 "origin" 是默认远程。如果超级项目没有配置默认远程，则超级项目就是它自己的权威上游，并且当前工作目录将被用作替代。

可选参数 <path> 是克隆的子模块在超级项目中存在的相对位置。如果未给出 <path>，则使用源存储库的规范部分（对于 "/path/to/repo.git" 为 "repo"，对于 "host.xz:foo/.git" 为 "foo"）。如果 <path> 存在并且已经是有效的 Git 存储库，则它将被暂存以进行提交，而不会克隆。<path> 也用作其配置条目中的子模块的逻辑名称，除非使用 --name 指定逻辑名称。

给定的 URL 被记录到 .gitmodules 中，供随后克隆超级项目的使用者使用。如果给定的 URL 相对于超级项目的存储库，则假设超级项目和子模块存储库将保存在同一个相对位置，并且只需要提供超级项目的 URL。git-submodule 将使用 .gitmodules 中的相对 URL 正确地找到子模块。

如果指定了 --ref-format <format>，则新克隆的子模块的 ref 存储格式将相应地设置。

status [--cached] [--recursive] [--] [<path>…​]

显示子模块的状态。这将打印每个子模块当前签出的提交的 SHA-1，以及子模块路径和 git describe 对 SHA-1 的输出。每个 SHA-1 可能以 - 为前缀，如果子模块未初始化，则以 + 为前缀，如果当前签出的子模块提交与包含存储库的索引中找到的 SHA-1 不匹配，则以 U 为前缀，如果子模块有合并冲突。

如果指定了 --cached，则此命令将改为打印每个子模块在超级项目中记录的 SHA-1。

如果指定了 --recursive，则此命令将递归到嵌套的子模块中，并显示它们的状态。

如果您只对当前已初始化的子模块相对于索引或 HEAD 中记录的提交的更改感兴趣，git-status[1] 和 git-diff[1] 也将提供这些信息（并且还可以报告对子模块工作树的更改）。

init [--] [<path>…​]

通过在 .git/config 中设置 submodule.$name.url 来初始化索引中记录的子模块（这些子模块在其他地方添加和提交），使用 .gitmodules 中的相同设置作为模板。如果 URL 是相对的，它将使用默认远程解析。如果没有默认远程，则当前存储库将被认为是上游。

可选的 <path> 参数限制将要初始化的子模块。如果未指定路径并且已配置 submodule.active，则将初始化配置为活动的子模块，否则将初始化所有子模块。

它还将复制 submodule.$name.update 的值（如果存在于 .gitmodules 文件中）到 .git/config，但是 (1) 此命令不会更改 .git/config 中的现有信息，并且 (2) submodule.$name.update 设置为自定义命令不会出于安全原因而被复制。

然后，您可以在 .git/config 中自定义子模块克隆 URL 以适应您的本地设置，然后继续执行 git submodule update；如果您不打算自定义任何子模块位置，也可以只使用 git submodule update --init 而不执行显式的 init 步骤。

有关默认远程的定义，请参见 add 子命令。

deinit [-f|--force] (--all|[--] <path>…​)

注销给定的子模块，即从 .git/config 中删除整个 submodule.$name 部分及其工作树。对 git submodule update、git submodule foreach 和 git submodule sync 的进一步调用将跳过任何注销的子模块，直到它们再次初始化，因此如果您不再希望在工作树中拥有子模块的本地签出，请使用此命令。

当命令在没有路径规范的情况下运行时，它会出错，而不是注销所有内容，以防止错误发生。

如果指定了 --force，即使子模块的工作树包含本地修改，它也会被删除。

如果您真的想从存储库中删除子模块并提交该操作，请改用 git-rm[1]。有关删除选项，请参见 gitsubmodules[7]。

update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>…​]

更新注册的子模块以匹配超级项目期望的内容，方法是克隆丢失的子模块，获取子模块中丢失的提交，并更新子模块的工作树。 "更新" 可以通过几种方式完成，具体取决于命令行选项和 submodule.<name>.update 配置变量的值。命令行选项优先于配置变量。如果两者都没有给出，则执行 checkout。（注意：此时 .gitmodules 文件中的内容无关紧要；有关如何使用 .gitmodules 的信息，请参见上面的 git submodule init）。从命令行以及通过 submodule.<name>.update 配置支持的 update 过程如下

checkout

将在超级项目中记录的提交将被签出到子模块的分离的 HEAD 中。

如果指定了--force，即使包含存储库的索引中指定的提交与子模块中签出的提交匹配，子模块也会被签出（使用git checkout --force）。

rebase

子模块的当前分支将被重新定位到超级项目中记录的提交。

merge

超级项目中记录的提交将被合并到子模块的当前分支。

以下更新过程有额外的限制

custom command

用于使用提交 ID 作为参数运行任意命令的机制。具体来说，如果submodule.<name>.update 配置变量设置为!custom command，则超级项目为子模块记录的提交的对象名称将附加到custom command 字符串中并执行。请注意，此机制在.gitmodules 文件或命令行中不受支持。

none

不会更新子模块。此更新过程在命令行中不允许。

如果子模块尚未初始化，并且您只想使用.gitmodules 中存储的设置，您可以使用--init 选项自动初始化子模块。

如果指定了--recursive，此命令将递归进入注册的子模块，并更新其中的任何嵌套子模块。

如果指定了 --ref-format <format>，则新克隆的子模块的 ref 存储格式将相应地设置。

如果指定了--filter <filter-spec>，则给定的部分克隆过滤器将应用于子模块。有关过滤器规范的详细信息，请参见git-rev-list[1]。

set-branch (-b|--branch) <branch> [--] <path>
set-branch (-d|--default) [--] <path>

设置子模块的默认远程跟踪分支。--branch 选项允许指定远程分支。--default 选项删除 submodule.<name>.branch 配置键，这会导致跟踪分支默认为远程 HEAD。

set-url [--] <path> <newurl>

将指定子模块的 URL 设置为 <newurl>。然后，它会自动同步子模块的新远程 URL 配置。

summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>…​]

显示给定提交（默认为 HEAD）和工作树/索引之间的提交摘要。对于要查询的子模块，将显示子模块中给定超级项目提交和索引或工作树（由--cached 切换）之间的系列提交。如果给出了选项--files，则显示超级项目的索引和子模块的工作树之间子模块中的一系列提交（此选项不允许使用--cached 选项或提供显式提交）。

使用git-diff[1] 中的--submodule=log 选项也会提供该信息。

foreach [--recursive] <command>

在每个签出的子模块中评估任意 shell 命令。该命令可以访问变量 $name、$sm_path、$displaypath、$sha1 和 $toplevel：$name 是.gitmodules 中相关子模块部分的名称，$sm_path 是立即超级项目中记录的子模块的路径，$displaypath 包含从当前工作目录到子模块根目录的相对路径，$sha1 是立即超级项目中记录的提交，$toplevel 是立即超级项目的顶层的绝对路径。请注意，为了避免与 Windows 上的 $PATH 冲突，$path 变量现在是 $sm_path 变量的已弃用同义词。此命令会忽略超级项目中定义但未签出的任何子模块。除非给出--quiet，否则 foreach 在评估命令之前会打印每个子模块的名称。如果给出--recursive，则会递归遍历子模块（即，给定的 shell 命令也会在嵌套子模块中评估）。任何子模块中命令的非零返回值会导致处理终止。这可以通过在命令末尾添加 || : 来覆盖。

例如，下面的命令将显示每个子模块的路径和当前签出的提交

git submodule foreach 'echo $sm_path `git rev-parse HEAD`'
sync [--recursive] [--] [<path>…​]

将子模块的远程 URL 配置设置同步到.gitmodules 中指定的 value。它只会影响那些已经在 .git/config 中有 URL 条目的子模块（当它们被初始化或新添加时就是这样）。这在子模块 URL 在上游发生更改并且您需要相应地更新本地存储库时很有用。

git submodule sync 同步所有子模块，而git submodule sync -- A 只同步子模块“A”。

如果指定了--recursive，此命令将递归进入注册的子模块，并同步其中的任何嵌套子模块。

absorbgitdirs

如果子模块的 git 目录在子模块内部，将子模块的 git 目录移动到其超级项目的$GIT_DIR/modules 路径中，然后通过设置core.worktree 并添加一个指向嵌入在超级项目 git 目录中的 git 目录的 .git 文件来连接 git 目录及其工作目录。

独立克隆的存储库后来被添加为子模块或旧的设置，其子模块 git 目录在子模块内部，而不是嵌入到超级项目的 git 目录中。

此命令默认是递归的。

OPTIONS

-q
--quiet

仅打印错误消息。

--progress

此选项仅对 add 和 update 命令有效。进度状态默认情况下在标准错误流中报告（当它连接到终端时），除非指定 -q。此标志即使标准错误流未定向到终端也会强制进度状态。

--all

此选项仅对 deinit 命令有效。注销工作树中的所有子模块。

-b <branch>
--branch <branch>

要添加为子模块的存储库的分支。分支的名称被记录为.gitmodules 中的submodule.<name>.branch 用于update --remote。特殊值. 用于指示子模块中的分支名称应与当前存储库中的当前分支名称相同。如果未指定此选项，则默认为远程 HEAD。

-f
--force

此选项仅对 add、deinit 和 update 命令有效。在运行 add 时，允许添加一个原本被忽略的子模块路径。在运行 deinit 时，即使子模块工作树包含本地更改，也会将其删除。在运行 update 时（仅对 checkout 过程有效），在切换到不同的提交时丢弃子模块中的本地更改；并且始终在子模块中运行 checkout 操作，即使包含存储库的索引中列出的提交与子模块中签出的提交匹配。

--cached

此选项仅对 status 和 summary 命令有效。这些命令通常使用子模块 HEAD 中找到的提交，但使用此选项时，会使用索引中存储的提交。

--files

此选项仅对 summary 命令有效。使用此选项时，此命令将比较索引中的提交与子模块 HEAD 中的提交。

-n
--summary-limit

此选项仅对 summary 命令有效。限制摘要大小（总共显示的提交数量）。给出 0 将禁用摘要；负数表示无限制（默认值）。此限制仅适用于已修改的子模块。对于已添加/已删除/类型已更改的子模块，大小始终限制为 1。

--remote

此选项仅对 update 命令有效。不要使用超级项目的记录的 SHA-1 来更新子模块，而是使用子模块的远程跟踪分支的状态。使用的远程是分支的远程（branch.<name>.remote），默认为origin。使用的远程分支默认为远程 HEAD，但分支名称可以通过在.gitmodules 或.git/config 中设置submodule.<name>.branch 选项来覆盖（.git/config 优先）。

这适用于任何支持的更新过程（--checkout、--rebase 等）。唯一的变化是目标 SHA-1 的来源。例如，submodule update --remote --merge 将将上游子模块更改合并到子模块中，而submodule update --merge 将将超级项目 gitlink 更改合并到子模块中。

为了确保当前的跟踪分支状态，update --remote 在计算 SHA-1 之前会获取子模块的远程存储库。如果您不想获取，则应使用submodule update --remote --no-fetch。

使用此选项将上游子项目的更改与子模块的当前 HEAD 集成。或者，您可以在子模块中运行git pull，它等效，除了远程分支名称：update --remote 使用默认的上游存储库和submodule.<name>.branch，而git pull 使用子模块的branch.<name>.merge。如果您想将默认的上游分支与超级项目一起分发，请使用submodule.<name>.branch；如果您想要在子模块本身中更本地化的感觉，请使用branch.<name>.merge。

-N
--no-fetch

此选项仅对 update 命令有效。不要从远程站点获取新对象。

--checkout

此选项仅对 update 命令有效。在子模块的游离 HEAD 上检出超级项目中记录的提交。这是默认行为，此选项的主要用途是在设置为除 `checkout` 之外的值时覆盖 `submodule.$name.update`。如果键 `submodule.$name.update` 未显式设置或设置为 `checkout`，则此选项为隐式。

--merge

此选项仅对 update 命令有效。将超级项目中记录的提交合并到子模块的当前分支。如果给出此选项，子模块的 HEAD 将不会游离。如果合并失败阻止了此过程，您将不得不使用通常的冲突解决工具解决子模块中的冲突。如果键 `submodule.$name.update` 设置为 `merge`，则此选项为隐式。

--rebase

此选项仅对 update 命令有效。将当前分支重新定位到超级项目中记录的提交。如果给出此选项，子模块的 HEAD 将不会游离。如果合并失败阻止了此过程，您将不得不使用 git-rebase[1] 解决这些失败。如果键 `submodule.$name.update` 设置为 `rebase`，则此选项为隐式。

--init

此选项仅对 update 命令有效。在更新之前，初始化所有尚未调用 “git submodule init” 的子模块。

--name

此选项仅对 add 命令有效。它将子模块的名称设置为给定的字符串，而不是默认设置为其路径。名称必须是有效的目录名称，并且不能以 */* 结尾。

--reference <repository>

此选项仅对 add 和 update 命令有效。这些命令有时需要克隆远程仓库。在这种情况下，此选项将传递给 git-clone[1] 命令。

注意：除非您仔细阅读了 git-clone[1] 的 `--reference`、`--shared` 和 `--dissociate` 选项的说明，否则不要使用此选项。

--dissociate

此选项仅对 add 和 update 命令有效。这些命令有时需要克隆远程仓库。在这种情况下，此选项将传递给 git-clone[1] 命令。

注意：请参阅 `--reference` 选项的说明。

--recursive

此选项仅对 foreach、update、status 和 sync 命令有效。递归遍历子模块。操作不仅在当前仓库的子模块中执行，而且在这些子模块中的任何嵌套子模块中执行（等等）。

--depth

此选项对 add 和 update 命令有效。创建浅层克隆，其历史记录截断到指定数量的修订版。参见 git-clone[1]

--[no-]recommend-shallow

此选项仅对 update 命令有效。默认情况下，子模块的初始克隆将使用 ` .gitmodules` 文件提供的推荐 `submodule.<name>.shallow`。要忽略建议，请使用 `--no-recommend-shallow`。

-j <n>
--jobs <n>

此选项仅对 update 命令有效。使用尽可能多的作业并行克隆新的子模块。默认为 `submodule.fetchJobs` 选项。

--[no-]single-branch

此选项仅对 update 命令有效。仅克隆一个分支进行更新：HEAD 或 `--branch` 指定的一个分支。

<path>…​

子模块的路径。指定此路径将限制命令仅对指定路径中找到的子模块进行操作。（此参数对于 add 是必需的）。

文件

初始化子模块时，包含仓库的顶层目录中的 ` .gitmodules` 文件用于查找每个子模块的 url。此文件应以与 `$GIT_DIR/config` 相同的方式格式化。每个子模块 url 的键是 “submodule.$name.url”。有关详细信息，请参见 gitmodules[5]。

另请参见

gitsubmodules[7]、gitmodules[5]。

GIT

是 git[1] 套件的一部分

scroll-to-top