git submodule

git-submodule

Name

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

概要

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] 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> --name <name> --depth <depth> <repository> <path>

将给定的存储库作为子模块添加到要在当前项目旁提交的变更集的给定路径：当前项目称为“超级项目”。

<repository> 是新子模块的源存储库的 URL 。这可能是一个绝对 URL ，或者（如果它以./或者../开始），相对于上层项目的默认远程仓库的位置（请注意，指定仓库foo.git位于旁边的一个上层项目bar.git，你”必须使用 - ../foo.git而不是./foo.git- 遵循相对 URL 的规则时所期望的 - 因为 Git 中的相对 URL 的评估与相对目录的相同 URL 相同）。

默认远程是当前分支的远程追踪分支的远程。如果不存在这样的远程跟踪分支或 HEAD 被分离，则“origin”被假定为默认远程。如果超级项目没有配置默认远程，则超级项目是其自己的权威上游，而是使用当前工作目录。

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

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

status --cached --

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

如果--recursive指定，则此命令将递归嵌套子模块，并显示其状态。

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

init --

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

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

当存在时，它也将复制值submodule.$name.update。该命令不会改变 .git / config 中的现有信息。然后，您可以在 .git / config 中为您的本地设置定制子模块克隆 URL 并继续git submodule update; 如果您不打算自定义任何子模块位置，则也可以在git submodule update --init没有明确init步骤的情况下使用。

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

deinit -f|--force

取消注册给定的子模块，submodule.$name即将 .git / config 中的整个部分与其工作树一起移除。进一步呼吁git submodule update，git submodule foreach并git submodule sync会跳过所有未注册的子模块，直到再次初始化，所以使用这个命令，如果你不想在你的工作树子模块的本地结账了。

当命令在没有 pathspec 的情况下运行时，它会出错，而不是取消所有内容，以防止出错。

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

如果您确实想从存储库中移除子模块并提交使用 git-rm [1]来代替。有关移除选项，请参阅 gitsubmodules [7]。

update --init -N | --no-fetch - no-recommend-shallow] -f | --force --reference <repository> --recursive -

通过克隆缺失子模块和更新子模块的工作树，更新已注册的子模块以匹配超级项目所期望的内容。根据命令行选项和submodule.<name>.update配置变量的值，“更新”可以通过多种方式完成。命令行选项优先于配置变量。如果两者均未给出，则执行结账。更新过程支持从命令行以及设置submodule.<name>.update：

checkout

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

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

rebase

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

merge

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

以下过程仅通过submodule.<name>.update配置变量可用：

自定义命令

执行采用单个参数（超级项目中记录的提交的sha1）的任意 shell 命令。当submodule.<name>.update设置!command为时，感叹号后的剩余部分是自定义命令。

none

子模块没有更新。

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

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

summary --cached | --files commit <path> ...

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

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

foreach --recursive <command>

在每个签出的子模块中评估一个任意的 shell 命令。该命令可以访问变量 $ name，$ path，$ sha1 和 $ toplevel：$ name 是相关子模块部分.gitmodules的名称，$ path 是相对于超级项目的子模块目录的名称，$ sha1 是提交记录在超级项目中，而 $ toplevel 是超级项目顶级的绝对路径。在超级项目中定义但未检出的任何子模块都将被此命令忽略。除非给出--quiet，否则 foreach 在评估命令之前打印每个子模块的名称。如果--recursive给出子模块递归地遍历（即，给定的 shell 命令也在嵌套子模块中进行评估）。来自任何子模块中的命令的非零返回会导致处理终止。这可以通过添加|| :到命令的末尾来覆盖。

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

git submodule foreach 'echo $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 目录，而不是嵌入到 superprojects git 目录中。

该命令默认是递归的。

选项

-q --quiet

只打印错误消息。

--all

该选项仅对 deinit 命令有效。取消注册工作树中的所有子模块。

-b --branch

将存储库的分支添加为子模块。分支的名称记录submodule.<name>.branch在.gitmodules了update --remote。特殊值.用于指示子模块中分支的名称应与当前存储库中当前分支的名称相同。

-f --force

该选项仅适用于添加，删除和更新命令。在运行 add 时，允许添加一个否则忽略的子模块路径。在运行 deinit 时，即使子模块包含本地更改，也将删除子模块工作树。在运行 update 时（只对 checkout 程序有效），在切换到其他提交时丢弃子模块中的本地更改; 并且始终在子模块中运行检出操作，即使包含存储库的索引中列出的提交与在子模块中检出的提交匹配也是如此。

--cached

该选项仅对状态和汇总命令有效。这些命令通常使用在子模块 HEAD 中找到的提交，但使用此选项时，将使用存储在索引中的提交。

--files

该选项仅对汇总命令有效。当使用此选项时，此命令会将索引中的提交与子模块 HEAD 中的提交进行比较。

-n --summary-limit

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

--remote

该选项仅对更新命令有效。使用子模块的远程跟踪分支的状态，而不是使用超级项目的已记录的 SHA-1 来更新子模块。使用的远程是分支的远程（branch.<name>.remote），默认为origin。远程分支使用默认为master，但分支名称可以通过设置覆盖submodule.<name>.branch选项在任一.gitmodules或.git/config（与.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

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

--checkout

该选项仅对更新命令有效。检查子模块中分离的 HEAD 上超级项目中记录的提交。这是默认行为，此选项的主要用途是将其submodule.$name.update设置为除以外的值时覆盖checkout。如果密钥submodule.$name.update未明确设置或设置为checkout，则此选项是隐含的。

--merge

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

--rebase

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

--init

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

--name

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

--reference <repository>

该选项仅适用于添加和更新命令。这些命令有时需要克隆远程存储库。在这种情况下，这个选项将被传递给 git-clone [1] 命令。

注意：不要不，除非你已经阅读说明了混帐克隆[1]的使用此选项--reference与--shared选项仔细。

--recursive

此选项仅适用于foreach，更新，状态和同步命令。递归地遍历子模块。该操作不仅在当前回购的子模块中执行，而且在子模块内的任何嵌套子模块中执行（依此类推）。

--depth

该选项对添加和更新命令有效。创建一个shallow历史截断为指定修订版本的克隆。参见 git-clone [1]

--no-recommend-shallow

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

-j <n> --jobs <n>

该选项仅对更新命令有效。与多个作业并行克隆新的子模块。默认为submodule.fetchJobs选项。

<path>…​

子模块的路径。指定时，将限制该命令仅对在指定路径中找到的子模块进行操作。（这个参数是需要添加的）。

文档

初始化子模块时，将.gitmodules使用包含存储库的顶级目录中的文件来查找每个子模块的 url 。这个文件的格式应该和$GIT_DIR/config。每个子模块网址的关键是“submodule。$ name.url”。有关详细信息，请参阅 gitmodules [5]。