Git 子模块命令（git-submodule） - 初始化、更新或检查子模块
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 submodule
git submodules不带任何参数时，则显示现有子模块的状态相当于git submodule status。
git submodule add
1 | git submodule add [-b <branch>] [-f | --force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>] |
git submodule add 命令用于向 Git 仓库添加一个新的子模块。将子模块数据 .gitmodules 和 .git/config 。它的参数如下：
<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 命令用于在本地初始化子模块。这个命令把 .submodule 中的子目录条目添加到本地仓库的 .git/config 文件中记录子模块的 URL 信息。通常这个命令用于刚 clone 的仓库。这个命令的参数如下：
<path>：可选参数，指定要初始化的子模块的路径。如果没有指定，将初始化所有子模块。
请注意，git submodule init 只是设置子模块的 URL，它不会 clone 子模块，也不会 checkout 到指定的子模块分支，要完成这个操作需要运行 git submodule update。
git submodule deinit
1 | git submodule deinit [-f | --force] (--all|[--] <path>...) |
git submodule deinit 命令用于取消初始化子模块。这个命令从 .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 | git submodule set-branch (-b | --branch) <branch> [--] <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”。