git-submodule

原文： https://git-scm.com/docs/git-submodule

名称

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

概要

  1. git submodule [--quiet] add [<options>] [--] <repository> [<path>]
  2. git submodule [--quiet] status [--cached] [--recursive] [--] [<path>…​]
  3. git submodule [--quiet] init [--] [<path>…​]
  4. git submodule [--quiet] deinit [-f|--force] (--all|[--] <path>…​)
  5. git submodule [--quiet] update [<options>] [--] [<path>…​]
  6. git submodule [--quiet] summary [<options>] [--] [<path>…​]
  7. git submodule [--quiet] foreach [--recursive] <command>
  8. git submodule [--quiet] sync [--recursive] [--] [<path>…​]
  9. git submodule [--quiet] absorbgitdirs [--] [<path>…​]

描述

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

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

COMMANDS

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

如果你真的想要从存储库中删除子模块并提交使用 git-rm [1] 。有关删除选项，请参阅 gitsubmodules [7] 。

  1.  update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>…​]

通过克隆缺失的子模块并更新子模块的工作树，更新已注册的子模块以匹配超级项目所期望的内容。 “更新”可以通过多种方式完成，具体取决于命令行选项和submodule.&lt;name&gt;.update配置变量的值。命令行选项优先于配置变量。如果两者都没有给出，则执行检出。从命令行以及通过submodule.&lt;name&gt;.update配置支持的更新程序是：

  1.  checkout

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

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

  1.  rebase

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

  1.  merge

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

以下更新程序仅可通过submodule.&lt;name&gt;.update配置变量获得：

  1.  custom command

执行带有单个参数的任意shell命令（超级项目中记录的提交的sha1）。当submodule.&lt;name&gt;.update设置为！命令时，感叹号后面的余数是自定义命令。

  1.  none

子模块未更新。

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

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

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

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

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

  1.  foreach [--recursive] <command>

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

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

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

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

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

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

  1.  absorbgitdirs

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

独立克隆并随后作为子模块或旧设置添加的存储库在子模块内部具有子模块git目录，而不是嵌入到superprojects git目录中。

默认情况下，此命令是递归的。

OPTIONS

  1.  -q
  1.  --quiet

仅打印错误消息。

  1.  --progress

此选项仅对添加和更新命令有效。除非指定了-q，否则在将标准错误流附加到终端时，默认情况下会报告进度状态。即使标准错误流未定向到终端，此标志也会强制进度状态。

  1.  --all

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

  1.  -b
  1.  --branch

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

  1.  -f
  1.  --force

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

  1.  --cached

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

  1.  --files

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

  1.  -n
  1.  --summary-limit

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

  1.  --remote

此选项仅对update命令有效。不使用超级项目记录的SHA-1来更新子模块，而是使用子模块的远程跟踪分支的状态。使用的遥控器是分支的遥控器（branch.&lt;name&gt;.remote），默认为origin。使用的远程分支默认为master，但可以通过在.gitmodules或.git/config中设置submodule.&lt;name&gt;.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.&lt;name&gt;.branch，而git pull使用子模块的branch.&lt;name&gt;.merge。如果您想在超级项目中分配默认上游分支，请选择submodule.&lt;name&gt;.branch，如果您希望在子模块本身工作时想要更原始的感觉，请选择branch.&lt;name&gt;.merge。

  1.  -N
  1.  --no-fetch

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

  1.  --checkout

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

  1.  --merge

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

  1.  --rebase

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

  1.  --init

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

  1.  --name

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

  1.  --reference <repository>

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

注：不是使用此选项除非您已阅读 git-clone [1] 的--reference，--shared和--dissociate选项仔细。

  1.  --dissociate

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

注：参见--reference选项的注意事项。

  1.  --recursive

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

  1.  --depth

此选项对添加和更新命令有效。创建一个浅克隆，其历史记录被截断为指定的修订数。见 git-clone [1]

  1.  --[no-]recommend-shallow

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

  1.  -j <n>
  1.  --jobs <n>

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

  1.  <path>…​

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

FILES

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

也可以看看

gitsubmodules [7] ， gitmodules [5] 。

GIT

部分 git [1] 套件