如何制作浅层 git 子模块？

Question

是否可以有浅层子模块？我有一个包含多个子模块的超级项目，每个子模块都有很长的历史，因此它会不必要地拖累所有这些历史。

我所找到的只是这个未答复的线程。

我应该破解 git-submodule 实施这个？

Answer 1

太长了；

git clone --recurse-submodules --shallow-submodules

（但请参阅 Ciro Santilli 答案）
或者：记录子模块应该浅克隆：

git config -f .gitmodules submodule.<name>.shallow true

这意味着下一个 git clone --recurse-submodules 将会浅克隆子模块 '' (深度 1 ），甚至没有--shallow-submodules。

---

接下来是 git submodule/git clone 在浅层克隆方面的演变，从（2013 年）Git 1.8.4 开始，并以此为基础。

---

即将推出的 Git 1.8.4（2013 年 7 月）< /a>:

“git submodule update”可以选择浅层克隆子模块存储库。

（git 2.10 Q3 2016 允许使用 git config -f .gitmodules submodule..shallow true 来记录。
请参阅此答案的末尾）

请参阅提交275cd184d52b5b81cb89e4ec33e540fb2ae61c1f：

在“git submodule”的添加和更新命令中添加--depth选项，然后将其传递给clone命令。当子模块很大并且您对除最新提交之外的任何内容都不感兴趣时​​，这非常有用。

添加了测试并进行了一些缩进调整，以符合测试文件的其余部分“子模块更新可以处理 pwd 中的符号链接”。

签署人：Fredrik Gustafsson <[电子邮件受保护] >
确认者：Jens Lehmann <[电子邮件受保护]> ;

这意味着这有效

# add shallow submodule
git submodule add --depth 1 <repo-url> <path>
git config -f .gitmodules submodule.<path>.shallow true

# later unshallow
git config -f .gitmodules submodule.<path>.shallow false
git submodule update <path>

：命令可以按任何顺序运行。 git submodule 命令执行实际克隆（这次使用深度 1）。并且 git config 命令使该选项对于稍后将递归克隆存储库的其他人来说是永久的。

例如，假设您有存储库 https://github.com/foo/bar 并且您想要添加 https://github.com/lorem/ipsum作为子模块，位于您的存储库中的 path/to/submodule 中。命令可能如下所示：

git submodule add --depth 1 [email protected]:lorem/ipsum.git path/to/submodule
git config -f .gitmodules submodule.path/to/submodule.shallow true

以下结果也会产生相同的结果（相反的顺序）：

git config -f .gitmodules submodule.path/to/submodule.shallow true
git submodule add --depth 1 [email protected]:lorem/ipsum.git path/to/submodule

下次有人运行 git clone --recursive [email protected]:foo/bar.git，它将提取 https://github.com/foo/bar 的整个历史记录，但它只会按预期浅克隆子模块。

和：

<前><代码>--深度

此选项对 add 和 update 命令有效。
创建一个“浅”克隆，其历史记录被截断为指定的修订数量。

---

atwyman 添加了在评论中：

据我所知，此选项不适用于不密切跟踪 master 的子模块。如果您设置深度 1，则只有您想要的子模块提交是最新的主模块时，子模块更新才能成功。 否则你会得到“致命：引用不是树”。

确实如此。
也就是说，直到 git 2.8（2016 年 3 月）。在 2.8 中，即使可以从远程存储库 HEAD 之一直接访问 SHA1，子模块 update --depth 又有了一次成功的机会。

请参阅 commit fb43e31（2016 年 2 月 24 日），作者：斯特凡·贝勒（stefanbeller）。
帮助者：Junio C Hamano (gitster)。
^{（由 Junio C Hamano -- gitster -- 合并于 提交9671a76，2016 年 2 月 26 日）}

子模块：通过直接获取 sha1 来更加努力地获取所需的 sha1

在审查同时更新 Gerrit 中的子模块的更改时，常见的审查做法是在本地下载并挑选补丁来测试它。
然而，在本地测试时，“git submodule update”可能无法获取正确的子模块 sha1，因为子模块中相应的提交尚未成为项目历史记录的一部分，而也只是建议的更改。< /p>

如果 $sha1 不是默认提取的一部分，我们会尝试直接提取 $sha1。然而，某些服务器不支持 sha1 直接获取，这会导致 git-fetch 很快失败。
我们可能会在这里失败，因为仍然丢失的 sha1 无论如何都会导致稍后在结账阶段失败，所以在这里失败是我们能得到的最好的结果。

---

MVG 指出在评论中到提交 fb43e31 （git 2.9，2016 年 2 月）

在我看来，提交fb43e31通过SHA1 id请求丢失的提交，所以 uploadpack.allowReachableSHA1InWant 和服务器上的 uploadpack.allowTipSHA1InWant 设置可能会影响此功能是否有效。
我今天在 git 列表中写了一篇帖子，指出了如何使用浅层子模块可以在某些情况下更好地工作，即如果提交也是一个标签。
让我们拭目以待。

我想这就是为什么 fb43e31 在获取默认分支之后将特定 SHA1 的获取作为后备的原因。
尽管如此，在“--深度 1”的情况下，我认为尽早中止是有意义的：如果列出的引用均不与请求的引用匹配，并且服务器不支持 SHA1 请求，则没有意义获取任何内容，因为无论如何我们都无法满足子模块的要求。

---

2016 年 8 月更新（3 年后）

使用 Git 2.10（2016 年第 3 季度），您将能够执行

 git config -f .gitmodules submodule.<name>.shallow true

查看“无需额外重量的 Git 子模块< /a>”了解更多。

---

Git 2.13（2017 年第 2 季度）请添加 commit 8d3047c（2017 年 4 月 19 日），作者：塞巴斯蒂安·舒伯特 (sschuberth)。
^{（由 Sebastian Schuberth -- sschuberth -- 合并于 提交8d3047c，2017 年 4 月 20 日）}

此子模块的克隆将作为浅克隆执行（历史深度为1）

但是，Ciro Santilli 添加 评论中（以及详细信息在他的回答中）

.gitmodules 上的

shallow = true 仅影响使用 --recurse-submodules 时远程 HEAD 跟踪的引用，甚至如果目标提交由分支指向，即使您也将 branch = mybranch 放在 .gitmodules 上。

---

Git 2.20（2018 年第 4 季度）改进了子模块支持，当工作中缺少 .gitmodules 文件时，子模块支持已更新为从 HEAD:.gitmodules 处的 blob 读取树。

请参阅 提交 2b1257e，提交 76e9bdc（2018 年 10 月 25 日），以及 提交 b5c259f, 提交 23dd8f5, 提交 b2faad4, 提交 2502ffc, 提交 996df4d, 提交 d1b13df, 提交 45f5ef3, 提交 bcbc780（2018 年 10 月 5 日），作者：安东尼奥·奥斯皮特（ao2）。
^{（由 Junio C Hamano -- gitster -- 合并于 提交abb4824，2018 年 11 月 13 日）}

submodule：支持读取不在工作树中的.gitmodules

当 .gitmodules 文件在工作树中不可用时，请尝试
使用索引和当前分支中的内容。
这涵盖了文件是存储库的一部分但对于某些情况
未签出的原因，例如由于签出稀疏。

这使得至少可以使用“git submodule”命令
读取 gitmodules 配置文件而不完全填充
工作树。

写入.gitmodules仍然需要签出该文件，
因此，在调用config_set_in_gitmodules_file_gently之前检查一下。

还在 git-submodule.sh::cmd_add() 中添加类似的检查，以预测“git submodule add”命令在 时最终失败.gitmodules 不可安全写入；这可以防止命令使存储库处于虚假状态（例如，子模块存储库已克隆，但 .gitmodules 未更新，因为 config_set_in_gitmodules_file_gently 失败）。

此外，由于 config_from_gitmodules() 现在访问全局对象
存储，有必要保护调用该函数的所有代码路径
反对并发访问全局对象存储。
目前这只发生在builtin/grep.c::grep_submodules()中，所以调用
在调用涉及 config_from_gitmodules() 的代码之前 grep_read_lock()。

注意：在极少数情况下，此新功能不起作用
尚未正确：工作树中没有 .gitmodules 的嵌套子模块。

---

注意：Git 2.24（2019 年第 4 季度）修复了浅克隆子模块时可能出现的段错误。

请参阅 提交 ddb3c85（2019 年 9 月 30 日），作者：阿里·乌特库·塞伦（auselen）。
^{（由 Junio C Hamano -- gitster -- 合并于 提交678a9ca，2019 年 10 月 9 日）}

---

Git 2.25（2020 年第一季度）澄清了 git 子模块更新 文档。

请参阅 提交 f0e58b3（2019 年 11 月 24 日），作者：菲利普·布莱恩（phil-blain）。
^{（由 Junio C Hamano -- gitster -- 合并于 提交ef61045，2019 年 12 月 5 日）}

doc：提及“git子模块更新”获取缺失的提交

^{帮助者：Junio C Hamano
帮助者：约翰内斯·辛德林
签字人：Philippe Blain}

'git 子模块更新'将如果未找到超级项目中记录的 SHA-1，则从子模块远程获取新提交。文档中没有提到这一点。

---

警告：在 Git 2.25（2020 年第 1 季度）中，“git clone --recurse-submodules”和备用对象存储之间的交互设计不当。

文档和代码已被教导可以在用户看到失败时提出更清晰的建议。

请参阅提交4f3e57e，提交 10c64a0（2019 年 12 月 2 日），作者：乔纳森·谭（jhowtan）。
^{（由 Junio C Hamano -- gitster -- 合并于 提交5dd1d59，2019 年 12 月 10 日）}

submodule--helper：关于致命替代的建议错误

^{签字人：Jonathan Tan
确认者：Jeff King}

当递归克隆一个超级项目并在其 .gitmodules 中定义了一些浅层模块，然后使用“--reference=”重新克隆时，会发生错误。例如：

git clone --recurse-submodules --branch=master -j8 \
  https://android.googlesource.com/platform/superproject \
  掌握
git clone --recurse-submodules --branch=master -j8 \
  https://android.googlesource.com/platform/superproject \
  --参考master master2

失败：

致命：子模块“”无法添加备用：参考存储库
'<剪断>'很浅

当无法添加从超级项目的替代项计算得出的替代项时，无论是在这种情况还是其他情况，请建议配置“submodule.alternateErrorStrategy”配置选项并使用“--reference-”克隆时使用“if-able”而不是“--reference”。

详细信息请参阅：

在 Git 2.25（2020 年第一季度）中，“git clone --recurse-submodules”和备用对象存储之间的交互设计不当。

Doc：解释 submodule.alternateErrorStrategy

^{签字人：Jonathan Tan
确认者：Jeff King}

提交31224cbdc7（“克隆：递归和引用选项触发子模块替代”，2016-08-17，Git v2.11.0-rc0 -- 合并在batch #1) 教 Git 支持配置选项“submodule.alternateLocation ”和超级项目上的“submodule.alternateErrorStrategy”。

如果“submodule.alternateLocation”在超级项目上配置为“superproject”，则每当克隆该超级项目的子模块时，它都会计算类似的备用路径来自超级项目的 $GIT_DIR/objects/info/alternates 的子模块，并引用它。

“submodule.alternateErrorStrategy”选项确定如果无法引用该替代项会发生什么情况。
但是，尚不清楚当该选项未设置为“die”时，克隆是否会像未指定替代项一样继续进行（如 31224cbdc7)。
因此，请相应地记录下来。

配置子模块文档现在包括：

submodule.alternateErrorStrategy::

指定如何处理通过 submodule.alternateLocation 计算的子模块替代项的错误。
可能的值为ignore、info、die。
默认为die。
请注意，如果设置为 ignore 或 info，并且如果计算的替代项出现错误，则克隆将继续进行，就像未指定替代项一样 .

---

注意：“git 子模块更新 --quiet< /代码>“(man) 未传播安静选项深入到底层git fetch( man)，已使用 Git 2.32（2021 年第 2 季度）进行更正。

请参阅 提交 62af4bd（2021 年 4 月 30 日），作者：尼古拉斯·克拉克（nwc10）。
^{（由 Junio C Hamano -- gitster -- 合并于 提交74339f8，2021 年 5 月 11 日）}

子模块更新：使用“<代码>--安静"

^{签字人：尼古拉斯·克拉克}

命令如

$ git 子模块更新 --quiet --init --深度=1

涉及浅克隆，请调用 shell 函数 fetch_in_submodule，该函数又调用 git fetch。
向前传递 --quiet 选项。

Answer 2

Git 2.9.0 支持浅层子模块直接克隆，所以现在你可以调用：

git clone url://to/source/repository --recursive --shallow-submodules

Answer 3

按照 Ryan 的回答，我能够想出这个简单的脚本，它迭代所有子模块和浅层克隆它们：

#!/bin/bash
git submodule init
for i in $(git submodule | sed -e 's/.* //'); do
    spath=$(git config -f .gitmodules --get submodule.$i.path)
    surl=$(git config -f .gitmodules --get submodule.$i.url)
    git clone --depth 1 $surl $spath
done
git submodule update

Answer 4

自 Git 2.14.1 起的错误/意外/烦人行为摘要

1. .gitmodules 中的shallow = true 仅影响 git clone --recurse-submodules 如果远程子模块的 HEAD 指向所需的提交，即使目标提交由分支指向，并且即使您放置 分支= mybranch 也位于 .gitmodules 上。

   本地测试脚本。 GitHub 2017-11 上的行为相同，其中 HEAD 由默认分支存储库设置控制：

   git clone --recurse-submodules https://github.com/cirosantilli/test-shallow-submodule-top-branch-shallow
   cd 测试浅子模块顶部分支浅/mod
   git 日志
   # 多次提交，不浅。
   

2. git clone --recurse-submodules --shallow-submodules 如果出现以下情况则失败提交既未被分支引用，也未被带有消息的标记引用：错误：服务器不允许请求未通告的对象。

   本地测试脚本。 GitHub 上的相同行为：

   git clone --recurse-submodules --shallow-submodules https://github.com/cirosantilli/test-shallow-submodule-top-sha
   ＃ 错误
   

   我还在邮件列表上询问：https://marc.info /?l=git&m=151863590026582&w=2 回复是：

   <块引用>

   理论上这应该很容易。 :)

   不幸的是，实际上并没有那么多。这是因为克隆只会获得
   分支（通常是 master）的最新提示。克隆中没有机制
   指定所需的确切 sha1。

   有线协议支持询问精确的 sha1，因此应该涵盖这一点。
   （警告：它仅在服务器运营商启用时才有效
   uploadpack.allowReachableSHA1InWant github上没有AFAICT）

   git-fetch 允许获取任意 sha1，因此作为解决方法，您可以运行 fetch
   在递归克隆之后使用“git submodule update”，因为这将使用
   在初始克隆之后获取。

TODO 测试：allowReachableSHA1InWant。

Answer 5

通读 git-submodule “source”，看起来 git submodule add 可以处理已经存在存储库的子模块。在这种情况下......

$ git clone $remote1 $repo
$ cd $repo
$ git clone --depth 5 $remotesub1 $sub1
$ git submodule add $remotesub1 $sub1
#repeat as necessary...

您需要确保所需的提交位于子模块存储库中，因此请确保设置适当的 --深度。

编辑：您也许能够摆脱多个手动子模块克隆，然后进行一次更新：

$ git clone $remote1 $repo
$ cd $repo
$ git clone --depth 5 $remotesub1 $sub1
#repeat as necessary...
$ git submodule update

Answer 6

您的子模块的规范位置是否远程？如果是这样，您可以克隆一次吗？换句话说，您是否想要浅层克隆只是因为您正在遭受频繁的子模块（重新）克隆的带宽浪费？

如果您想要浅克隆来节省本地磁盘空间，那么 Ryan Graham 的答案似乎是一个不错的选择。手动克隆存储库，使其变浅。如果您认为它有用，请调整 git submodule 以支持它。发送电子邮件至列表询问相关信息（实施建议、建议界面等）。在我看来，那里的人们非常支持那些真诚地希望以建设性方式增强 Git 的潜在贡献者。

如果您可以对每个子模块进行一次完整克隆（加上稍后的获取以使其保持最新），您可以尝试使用 git submodule update 的 --reference 选项> （在 Git 1.6.4 及更高版本中）引用本地对象存储（例如，制作规范子模块存储库的 --mirror 克隆，然后使用 --reference在你的子模块中指向这些本地克隆）。在使用 --reference 之前，请务必阅读有关 git clone --reference/git clone --shared 的内容。引用镜像唯一可能出现的问题是它们是否最终获取非快进更新（尽管您可以启用引用日志并扩展其过期窗口以帮助保留任何可能导致问题的废弃提交）。只要

• 您不进行任何本地子模块提交，或者
• 规范存储库可能发布的非快进悬空的任何提交不是本地子模块提交的祖先，或者
• 您很勤奋 ，您就不应该遇到任何问题关于将本地子模块提交重新基于规范子模块存储库中可能发布的任何非快进内容。

如果您采用类似的方法，并且有可能在工作树中进行本地子模块提交，那么创建一个自动化系统可能是一个好主意，该系统可确保签出子模块引用的关键对象不会被删除。在镜像存储库中悬空（如果找到的话，将它们复制到需要它们的存储库）。

而且，就像 git clone 手册页所说的那样，如果您不理解这些含义，请不要使用 --reference 。

# Full clone (mirror), done once.
git clone --mirror $sub1_url $path_to_mirrors/$sub1_name.git
git clone --mirror $sub2_url $path_to_mirrors/$sub2_name.git

# Reference the full clones any time you initialize a submodule
git clone $super_url super
cd super
git submodule update --init --reference $path_to_mirrors/$sub1_name.git $sub1_path_in_super
git submodule update --init --reference $path_to_mirrors/$sub2_name.git $sub2_path_in_super

# To avoid extra packs in each of the superprojects' submodules,
#   update the mirror clones before any pull/merge in super-projects.
for p in $path_to_mirrors/*.git; do GIT_DIR="$p" git fetch; done

cd super
git pull             # merges in new versions of submodules
git submodule update # update sub refs, checkout new versions,
                     #   but no download since they reference the updated mirrors

---

或者，您可以使用本地镜像作为子模块的源，将镜像克隆与 git clone 的默认硬链接功能结合使用，而不是使用 --reference。在新的超级项目克隆中，执行 git submodule init ，编辑 .git/config 中的子模块 URL 以指向本地镜像，然后执行 git submodule update 。您需要重新克隆任何现有的签出子模块才能获取硬链接。您只需下载一次到镜像中，然后从本地提取到您签出的子模块中，即可节省带宽。硬链接将节省磁盘空间（尽管提取往往会累积并在签出子模块的对象存储的多个实例之间重复；您可以定期从镜像中重新克隆签出子模块，以重新获得由硬链接）。

Answer 7

参考如何克隆具有特定修订/变更集的git存储库？< /a>

我编写了一个简单的脚本，当您的子模块引用远离主模块时，该脚本没有问题

git submodule foreach --recursive 'git rev-parse HEAD | xargs -I {} git fetch origin {} && git reset --hard FETCH_HEAD'

。此语句将获取子模块的引用版本。

它速度很快，但您无法在子模块上提交编辑（您必须在 https://stackoverflow.com/a/ 之前获取 unshallow 子模块） 17937889/3156509）

完整：

#!/bin/bash
git submodule init
git submodule foreach --recursive 'git rev-parse HEAD | xargs -I {} git fetch origin {} && git reset --hard FETCH_HEAD'
git submodule update --recursive

Answer 8

我创建了一个稍微不同的版本，当它没有在最前沿运行时，并非所有项目都这样做。标准子模块添加不起作用，上面的脚本也不起作用。因此，我为标签引用添加了一个哈希查找，如果没有，它将回退到完整克隆。

#!/bin/bash
git submodule init
git submodule | while read hash name junk; do
    spath=$(git config -f .gitmodules --get submodule.$name.path)
    surl=$(git config -f .gitmodules --get submodule.$name.url)
    sbr=$(git ls-remote --tags $surl | sed -r "/${hash:1}/ s|^.*tags/([^^]+).*\$|\1|p;d")
    if [ -z $sbr ]; then
        git clone $surl $spath
    else
        git clone -b $sbr --depth 1 --single-branch $surl $spath
    fi
done
git submodule update 

Answer 9

子模块的浅克隆是完美的，因为它们在特定修订/变更集上进行快照。从网站下载 zip 很容易，所以我尝试了一个脚本。

#!/bin/bash
git submodule deinit --all -f
for value in $(git submodule | perl -pe 's/.*(\w{40})\s([^\s]+).*/\1:\2/'); do
  mysha=${value%:*}
  mysub=${value#*:}
  myurl=$(grep -A2 -Pi "path = $mysub" .gitmodules | grep -Pio '(?<=url =).*/[^.]+')
  mydir=$(dirname $mysub)
  wget $myurl/archive/$mysha.zip
  unzip $mysha.zip -d $mydir
  test -d $mysub && rm -rf $mysub
  mv $mydir/*-$mysha $mysub
  rm $mysha.zip
done
git submodule init

git submodule deinit --all -f 清除子模块树，使脚本可以重用。

git submodule 检索 40 个字符的 sha1，后跟与 .gitmodules 中相同的路径相对应。我使用 perl 连接这些信息，并用冒号分隔，然后使用变量转换将值分成 mysha 和 mysub。

这些是关键键，因为我们需要下载 sha1 以及关联 .gitmodules 中 url 的路径。

给定一个典型的子模块条目：

[submodule "label"]
    path = localpath
    url = https://github.com/repository.git

path = 上的 myurl 键，然后查看 2 行以获取值。此方法可能无法始终如一地发挥作用，需要改进。 url grep 通过匹配最后一个 / 以及 . 之前的任何内容来去除任何剩余的 .git 类型引用。

mydir 是 mysub 减去最后的 /name，后者是通向子模块名称的目录。

接下来是一个 wget ，其格式为可下载的 zip 存档 url。这将来可能会改变。

将文件解压缩到 mydir ，它是子模块路径中指定的子目录。生成的文件夹将是 url-sha1 的最后一个元素。

检查子模块路径中指定的子目录是否存在并将其删除以允许重命名提取的文件夹。

mv 将包含 sha1 的提取文件夹重命名为其正确的子模块路径。

删除下载的 zip 文件。

子模块 init

这更多的是一个 WIP 概念证明，而不是一个解决方案。当它工作时，结果是指定变更集的子模块的浅克隆。

如果存储库将子模块重新定位到不同的提交，请重新运行脚本进行更新。

像这样的脚本唯一有用的时候是源项目的非协作本地构建。

Answer 10

当我无法影响主存储库的克隆时，我需要一个浅层克隆子模块的解决方案。
基于上述一种解决方案：

#!/bin/bash
git submodule init
for i in $(git submodule | sed -e 's/.* //'); do
    git submodule update --init --depth 1 -- $i
done