设置和配置
获取和创建项目
基本快照
分支与合并
共享和更新项目
检查和比较
打补丁
调试
电子邮件
外部系统
服务器管理
指南
管理
底层命令
- 2.47.1 → 2.50.1 无更改
-
2.47.0
2024-10-06
- 2.44.1 → 2.46.4 无更改
-
2.44.0
2024-02-23
- 2.42.1 → 2.43.7 无变更
-
2.42.0
2023-08-21
- 2.36.1 → 2.41.3 无更改
-
2.36.0
2022-04-18
- 2.28.1 → 2.35.8 无更改
-
2.28.0
2020-07-27
- 2.26.1 → 2.27.1 无更改
-
2.26.0
2020-03-22
- 2.25.2 → 2.25.5 无更改
-
2.25.1
2020-02-17
-
2.25.0
2020-01-13
- 2.24.1 → 2.24.4 无更改
-
2.24.0
2019-11-04
- 2.22.1 → 2.23.4 无更改
-
2.22.0
2019-06-07
- 2.19.1 → 2.21.4 无更改
-
2.19.0
2018-09-10
- 2.18.1 → 2.18.5 无更改
-
2.18.0
2018-06-21
- 2.17.0 → 2.17.6 无更改
-
2.16.6
2019-12-06
- 2.15.4 无更改
-
2.14.6
2019-12-06
-
2.13.7
2018-05-22
-
2.12.5
2017-09-22
- 2.11.4 无更改
-
2.10.5
2017-09-22
-
2.9.5
2017-07-30
-
2.8.6
2017-07-30
- 2.7.6 无更改
-
2.6.7
2017-05-05
- 2.5.6 无更改
-
2.4.12
2017-05-05
-
2.3.10
2015-09-28
- 2.1.4 → 2.2.3 无更改
-
2.0.5
2014-12-17
概要
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>,则使用源仓库的规范部分(“repo”表示“/path/to/repo.git”,“foo”表示“host.xz:foo/.git”)。如果 <path> 存在且已是有效的 Git 仓库,则它将在不进行克隆的情况下暂存以供提交。<path> 也用作子模块在其配置条目中的逻辑名称,除非使用
--name
指定逻辑名称。给定的 URL 将记录在
.gitmodules
中,供后续克隆父项目的用户使用。如果 URL 是相对于父项目的仓库给出的,则假定父项目和子模块仓库将保持在相同的相对位置,并且只需提供父项目的 URL。git-submodule 将使用.gitmodules
中的相对 URL 正确地找到子模块。如果指定了
--ref-format
<format>,新克隆的子模块的引用存储格式将相应设置。 - 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,则将初始化配置为活动的子模块,否则将初始化所有子模块。
它还将
.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
的调用将跳过任何未注册的子模块,直到它们再次初始化,因此,如果您不再希望在工作树中拥有子模块的本地检出,请使用此命令。当不带路径规范运行此命令时,它会报错,而不是注销所有内容,以防止误操作。
如果指定了
--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
文件中的内容无关紧要;请参阅上面的git
submodule
init
以了解.gitmodules
的使用方式)。命令行和通过submodule.
<name>.update
配置支持的 更新 过程有以下更新过程有额外的限制
如果子模块尚未初始化,并且您只想使用
.gitmodules
中存储的设置,您可以使用--init
选项自动初始化子模块。如果指定了
--recursive
,此命令将递归进入已注册的子模块,并更新其中的任何嵌套子模块。如果指定了
--ref-format
<format>,新克隆的子模块的引用存储格式将相应设置。如果指定了
--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
选项或提供显式提交)。使用带
--submodule=log
选项的 git-diff[1] 也将提供该信息。 - 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
中指定的值。它只会影响那些在 .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
-
此选项仅对 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 的方式检出父项目中记录的提交。这是默认行为,此选项的主要用途是在
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
-
此选项仅对 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]。