Git 子模块命令（git-submodule） - 初始化、更新或检查子模块

描述

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

概要

​ git submodule [—quiet] [—cached]
​ git submodule [—quiet] add [] [—] []
​ git submodule [—quiet] status [—cached] [—recursive] [—] […]
​ git submodule [—quiet] init [—] […]
​ git submodule [—quiet] deinit [-f | —force] (—all| [—] …)
​ git submodule [—quiet] update [] [—] […]
​ git submodule [—quiet] set-branch [] [—]
​ git submodule [—quiet] set-url [—]
​ git submodule [—quiet] summary [] [—] […]
​ git submodule [—quiet] foreach [—recursive]
​ git submodule [—quiet] sync [—recursive] [—] […]
​ git submodule [—quiet] absorbgitdirs [—] […]

命令

git submodules不带任何参数时，则显示现有子模块的状态相当于git submodule status。

git add

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

git submodule add 命令用于向 Git 仓库添加一个新的子模块。它的参数如下：

  • <repository>：必需参数，指定子模块的 Git 仓库 URL。
  • [<path>]：可选参数，指定子模块在你的项目中的路径，默认为项目根文件夹。
  • -b <branch> 或 --branch <branch>：可选参数，指定要跟踪的分支。如果没有指定，将使用远程仓库的默认分支。
  • --force 或 -f：可选参数，强制添加子模块，即使它已经存在。
  • --name <name>：可选参数，指定子模块的名称。如果没有指定，将使用 <path> 作为名称。
  • --reference <repository>：可选参数，指定一个参考仓库，Git 将从这个仓库复制对象，而不是从网络上下载。
  • --depth <depth>：可选参数，创建一个浅克隆，只克隆最近的 <depth> 次提交。

git submodule status

1
git submodule status [--cached] [--recursive] [--] [<path>...]

git submodule status 命令用于显示子模块的当前状态。它的参数如下：

  • <path>：可选参数，指定要查看状态的子模块的路径。如果没有指定，将显示所有子模块的状态。
  • --cached：可选参数，显示在索引中的子模块提交而不是在工作树中检查出的提交。
  • --recursive 或 -r：可选参数，递归地显示所有子模块的状态。

git submodule init

1
git submodule init [--] [<path>...]

git submodule init 命令用于初始化子模块。初始化子模块意味着 Git 将在 .git/config 文件中设置子模块的 URL。这个命令的参数如下：

  • <path>：可选参数，指定要初始化的子模块的路径。如果没有指定，将初始化所有子模块。

请注意，git submodule init 只是设置子模块的 URL，它不会 checkout 出子模块的内容。要检出子模块的内容，你需要运行 git submodule update。

git submodule deinit

1
git submodule deinit [-f | --force] (--all|[--] <path>...)

git submodule deinit 命令用于取消初始化子模块。取消初始化子模块意味着 Git 将从 .git/config 文件中删除子模块的 URL。这个命令的参数如下：

  • <path>：必需参数，指定要取消初始化的子模块的路径。

  • --force 或 -f：可选参数，强制取消初始化，即使子模块包含有未提交的更改或未推送的提交。

  • --all：可选参数，取消初始化所有子模块。

请注意，git submodule deinit 只是从 .git/config 文件中删除子模块的 URL，它不会删除子模块的内容或 .gitmodules 文件中的条目。要完全删除子模块，你需要手动删除 .gitmodules 文件中的条目和子模块的内容。

git submodule update

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

git submodule update 命令用于更新子模块。更新子模块意味着 Git 将 checkout 到 .gitmodules 文件中指定的提交。这个命令的参数如下：

  • <path>：可选参数，指定要更新的子模块的路径。如果没有指定，将更新所有子模块。
  • --init：可选参数，如果子模块尚未初始化，将自动初始化它。
  • --remote：可选参数，将子模块更新到上游仓库的最新提交，而不是 .gitmodules 文件中指定的提交。
  • -N 或 --no-fetch：可选参数，不从远程仓库获取子模块的最新更改。
  • --[no-]recommend-shallow：可选参数，推荐或不推荐浅克隆。默认情况下，Git 会尝试创建一个浅克隆。
  • -f 或 --force：可选参数，强制检出子模块，即使它包含有未提交的更改。
  • --checkout、--rebase 或 --merge：可选参数，指定更新子模块时使用的策略。默认策略是 checkout。
  • --reference <repository>：可选参数，指定一个参考仓库，Git 将从这个仓库复制对象，而不是从网络获取。
  • --depth <depth>：可选参数，创建一个浅克隆，只克隆最近的 <depth> 次提交。
  • --recursive 或 -r：可选参数，递归地更新所有子模块。
  • --jobs <n>：可选参数，指定并行获取或 checkout 的子模块的数量。

git submodule set-branch

1
2
git submodule set-branch (-b | --branch) <branch> [--] <path>
git submodule set-branch (-d | --default) [--] <path>

git submodule set-branch 命令用于设置或清除子模块的分支。这个命令的参数如下：

  • (-b | --branch) <branch>：必需参数，设置子模块的分支。<branch> 是你想要设置的分支的名称。
  • (-d | --default)：必需参数，清除子模块的分支，使其回到默认状态。默认情况下，子模块的分支是 master。
  • <path>：必需参数，指定要设置或清除分支的子模块的路径。

请注意，这个命令只是设置或清除 .gitmodules 文件中的分支条目，它不会检出或更新子模块的内容。要检出或更新子模块的内容，你需要运行 git submodule update。

git submodule set-url

1
git submodule set-url [--] <path> <newurl>

git submodule set-url 命令用于更改子模块的 URL。这个命令的参数如下：

  • <path>：必需参数，指定要更改 URL 的子模块的路径。

  • <newurl>：必需参数，新的 URL。

请注意，这个命令只是更改 .gitmodules 文件中的 URL 条目，它不会获取或更新子模块的内容。要获取或更新子模块的内容，你需要运行 git submodule update。

git submodule summary

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

git submodule summary 命令用于显示子模块的更改摘要。这个命令的参数如下：

  • --cached：可选参数，显示索引（即将要提交的）和指定提交之间的差异。如果没有指定提交，那么将使用 HEAD。
  • --files：可选参数，显示工作树和索引之间的差异。
  • (-n | --summary-limit) <n>：可选参数，限制显示的提交数量。<n> 是你想要显示的提交数量。
  • commit：可选参数，指定要比较的提交。如果没有指定，那么将使用 HEAD。
  • <path>：可选参数，指定要显示摘要的子模块的路径。如果没有指定，将显示所有子模块的摘要。

git submodue foreach

1
foreach [--recursive] <command>

git submodule foreach 命令用于在每个子模块上执行指定的命令。这个命令的参数如下：

  • <command>：必需参数，要在每个子模块上执行的命令。

  • --recursive：可选参数，递归地在每个子模块的子模块上执行命令。

请注意，<command> 必须是一个单引号括起来的字符串，以防止 shell 提前解析它。在 <command> 中，你可以使用 $name、$path 和 $sha1 变量，它们分别代表子模块的名称、路径和当前检出的提交。

git submodule sync

1
git submodule sync [--recursive] [--] [<path>...]

git submodule sync 命令用于同步子模块的 URL。这个命令的参数如下：

  • --recursive：可选参数，递归地同步每个子模块的子模块的 URL。
  • <path>：可选参数，指定要同步 URL 的子模块的路径。如果没有指定，将同步所有子模块的 URL。

同步子模块的 URL 意味着 Git 将更新 .git/config 文件中的子模块 URL，使其与 .gitmodules 文件中的 URL 匹配。这在你更改了 .gitmodules 文件中的 URL，或者子模块的远程仓库已经移动到新的 URL 时可能会有用。

git submodule absorbgitdirs

1
git submodule absorbgitdirs

git submodule absorbgitdirs 命令用于将子模块的 Git 目录移动到父项目的 .git/modules 目录下。这在你将一个常规的 Git 仓库转换为子模块时可能会有用。

当你将一个常规的 Git 仓库添加为子模块时，它的 .git 目录将保留在子模块的根目录下。这可能会导致一些问题，例如，如果你在父项目中删除了子模块，那么子模块的 .git 目录将被删除，这可能会导致数据丢失。

git submodule absorbgitdirs 命令可以解决这个问题，它将子模块的 .git 目录移动到父项目的 .git/modules 目录下，并在子模块的根目录下留下一个指向父项目的 .git/modules 目录的链接。这样，即使你在父项目中删除了子模块，子模块的 .git 目录也会保留在父项目的 .git/modules 目录下。

请注意，这个命令只适用于已经初始化和更新的子模块。如果子模块尚未初始化，你需要先运行 git submodule init 和 git submodule update。

公用参数

这些选项允许你定制 git submodule 的行为。以下是一些关键选项的解释：

  • -q, --quiet：只打印错误消息，不打印其他信息。
  • --progress：对于 add 和 update 命令，显示进度状态。

.gitsubmodule 文件

.gitmodules 文件位于包含子模块的顶级仓库目录中，用于在初始化子模块时找到每个子模块的 URL。这个文件的格式应该与 $GIT_DIR/config 文件的格式相同。每个子模块的 URL 的键是 “submodule.$name.url”，其中 $name 是子模块的名称。例如，如果你有一个名为 “my-submodule” 的子模块，那么它的 URL 的键就是 “submodule.my-submodule.url”。