简体中文 ▾ 主题 ▾ 最新版本 ▾ git-submodule 最新更新于 2.54.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>]

将给定的仓库作为子模块添加到给定路径，作为当前项目下一步要提交的变更集：当前项目被称为“父项目（superproject）”。

<repository> 是新子模块 origin 仓库的 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 <name> 指定了逻辑名称。

给定的 URL 将记录在 .gitmodules 中，供后续克隆父项目的用户使用。如果该 URL 是相对于父项目仓库给出的，则假设父项目和子模块仓库将保存在相同的相对位置，并且只需提供父项目的 URL 即可。git-submodule 将使用 .gitmodules 中的相对 URL 正确地定位子模块。

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

status [--cached] [--recursive] [--] [<path>...]

显示子模块的状态。这将打印每个子模块当前检出提交的 SHA-1，以及子模块路径和该 SHA-1 的 git-describe[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，则初始化配置为处于活动状态的子模块，否则初始化所有子模块。

如果 .gitmodules 文件中存在 submodule.$name.update 字段，它还会将其值复制到 .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 将跳过任何已注销的子模块，直到它们被重新初始化。因此，如果您不想在工作区中保留该子模块的本地检出，请使用此命令。

当在不指定路径规格（pathspec）的情况下运行该命令时，为了防止失误，它会报错退出，而不是注销所有内容。

If --force is specified, the submodule’s working tree will be removed even if it contains local modifications.

如果您确实想要从仓库中删除一个子模块并提交该更改，请改用 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>，那么在父项目中为该子模块记录的提交的对象名（object name）将被附加到 <custom-command> 字符串的末尾并执行。请注意，.gitmodules 文件或命令行中不支持此机制。

none

不更新子模块。命令行中不允许此更新程序。

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

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

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

如果指定了 --filter <filter-spec>，则给定的部分克隆（partial clone）过滤器将应用于子模块。有关过滤器规格的详细信息，请参阅 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 <command>。该命令可以访问变量 $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 中指定的值。它只会影响那些在 .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 目录中。

该命令默认是递归的。

选项

-q
--quiet

仅打印错误消息。

--progress

当标准错误流连接到终端时，默认在标准错误流上报告进度状态，除非指定了 -q。即使标准错误流没有指向终端，此标志也会强制显示进度状态。它仅对 add 和 update 命令有效。

--all

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

-b<branch>
--branch=<branch>

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

-f
--force

即使命令本会失败，也强制执行它。该选项仅对 add、deinit 和 update 命令有效。

add

允许添加原本被忽略的子模块路径。此选项还用于绕过子模块名称未被使用的检查。默认情况下，如果建议的名称（派生自路径）已被仓库中的另一个子模块注册，git submodule add 将失败。使用 --force 可以通过在冲突名称后附加数字来自动生成唯一名称（例如，如果存在名为 child 的子模块，它将尝试 child1，依此类推），从而使命令得以继续执行。

deinit

即使子模块工作区包含本地更改，其也将被移除。

update

（仅对检出程序有效）在切换 to 不同提交时，丢弃子模块中的本地更改；并且始终在子模块中运行检出操作，即使包含仓库的索引中列出的提交已经与子模块中检出的提交匹配。

--cached

使用索引而不是 HEAD 来确定提交。该选项仅对 status 和 summary 命令有效。

--files

让 summary 命令将索引中的提交与子模块 HEAD 中的提交进行比较。

-n<n>
--summary-limit=<n>

将 summary 的大小（总共显示的提交数量）限制为 <n>。输入 0 将禁用摘要；负数表示无限制（默认值）。此限制仅适用于已修改的子模块。对于添加、删除或类型更改的子模块，大小始终限制为 1。

--remote

使用子模块远程跟踪分支的状态来更新子模块，而不是使用父项目记录的 SHA-1。该选项仅对 update 命令有效。使用的远程仓库是分支的远程仓库（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 之前会先拉取（fetch）子模块的远程仓库。如果您不想进行拉取，应使用 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

在子模块中以分离的 HEAD 状态检出父项目中记录的提交。该选项仅对 update 命令有效。这是默认行为，该选项的主要用途是在 submodule.<name>.update 被设置为 checkout 以外的值时进行覆盖。如果键 submodule.<name>.update 未显式设置，或被设置为 checkout，则此选项是隐式的。

--merge

将父项目中记录的提交合并到子模块的当前分支中。该选项仅对 update 命令有效。如果给出了此选项，子模块的 HEAD 将不会分离。如果合并失败导致此过程受阻，您将必须使用常用的冲突解决工具在子模块内解决产生的冲突。如果键 submodule.<name>.update 被设置为 merge，则此选项是隐式的。

--rebase

将当前分支变基到父项目中记录的提交上。该选项仅对 update 命令有效。子模块的 HEAD 将不会分离。如果合并失败导致此过程受阻，您将必须使用 git-rebase[1] 来解决这些失败。如果键 submodule.<name>.update 被设置为 rebase，则此选项是隐式的。

--init

在更新之前，初始化到目前为止尚未调用 git submodule init 的所有子模块。该选项仅对 update 命令有效。

--name=<name>

将子模块的名称设置为给定的字符串，而不是默认使用其路径。<name> 必须是有效的目录名称，且不能以 / 结尾。

--reference=<repository>

克隆子模块时，将本地的 <repository> 作为参考（reference）传入。该选项仅对 add 和 update 命令有效。这些命令有时需要克隆远程仓库。在这种情况下，此选项将被传递给 git-clone[1] 命令。

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

在使用参考仓库克隆之后，不再依赖它。该选项仅对 add 和 update 命令有效。these 命令有时需要克隆远程仓库。在这种情况下，此选项将被传递给 git-clone[1] 命令。

注意
 有关注意事项，请参阅上文的 --reference 选项。
--recursive

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

--depth=<depth>

创建一个历史截断为 <depth> 次修订的浅（shallow）克隆。该选项对 add 和 update 命令有效。参见 git-clone[1]

--recommend-shallow
--no-recommend-shallow

建议或不建议对子模块进行浅克隆。该选项仅对 update 命令有效。子模块的首次克隆默认将使用 .gitmodules 文件提供的推荐设置 submodule.<name>.shallow。若要忽略该建议，请使用 --no-recommend-shallow。

-j<n>
--jobs=<n>

以 <n> 个并行作业（jobs）克隆新子模块。该选项仅对 update 命令有效。默认使用 submodule.fetchJobs 选项。

--single-branch
--no-single-branch

更新期间仅克隆一个分支：HEAD 或由 --branch 指定的分支。该选项仅对 update 命令有效。

<path>...

子模块的路径。指定后，此选项将限制命令仅对在指定路径中找到 of 子模块执行操作。（此参数在与 add 一起使用时是必填的）。

文件

初始化子模块时，将使用包含该子模块的仓库顶层目录中的 .gitmodules 文件来查找每个子模块的 URL。此文件的格式应与 $GIT_DIR/config 相同。每个子模块 URL 的键是 submodule.<name>.url。有关详细信息，请参阅 gitmodules[5]。

另请参阅

gitsubmodules[7]，gitmodules[5]。

GIT

Git[1] 套件的一部分