设置和配置
获取和创建项目
基本快照
分支与合并
共享和更新项目
检查和比较
打补丁
调试
电子邮件
外部系统
服务器管理
指南
管理
底层命令
- 2.44.1 → 2.50.1 无更改
-
2.44.0
2024-02-23
- 2.43.1 → 2.43.7 无更改
-
2.43.0
2023-11-20
- 2.35.1 → 2.42.4 无更改
-
2.35.0
2022-01-24
- 2.29.1 → 2.34.8 无更改
-
2.29.0
2020-10-19
- 2.27.1 → 2.28.1 无变更
-
2.27.0
2020-06-01
- 2.25.1 → 2.26.3 无更改
-
2.25.0
2020-01-13
- 2.22.1 → 2.24.4 无更改
-
2.22.0
2019-06-07
- 2.19.3 → 2.21.4 无更改
-
2.19.2
2018-11-21
- 2.19.1 无更改
-
2.19.0
2018-09-10
- 2.17.0 → 2.18.5 无更改
-
2.16.6
2019-12-06
- 2.15.4 无更改
-
2.14.6
2019-12-06
描述
子模块是一个嵌入在另一个仓库中的仓库。子模块有自己的历史记录;嵌入它的仓库称为超级项目。
在文件系统上,子模块通常(但并非总是如此 - 参见下文的“形式”)由以下部分组成:(i) 位于其超级项目 $GIT_DIR/modules/
目录下的 Git 目录,(ii) 位于超级项目工作目录内的子模块工作目录,以及 (iii) 位于子模块工作目录根目录下的一个指向 (i) 的 .git
文件。
假设子模块的 Git 目录位于 $GIT_DIR/modules/foo/
,工作目录位于 path/to/bar/
,则超级项目通过 path/to/bar
树中的 gitlink
条目及其 .gitmodules
文件(参见 gitmodules[5])中形式为 submodule.foo.path
=
path/to/bar
的条目来跟踪子模块。
gitlink
条目包含超级项目期望子模块工作目录所处的提交的对象名称。
.gitmodules
文件中的 submodule.foo.*
部分为 Git 的高级命令层提供了额外的提示。例如,submodule.foo.url
设置指定了从何处获取子模块。
子模块至少可用于两种不同的用例
-
在使用另一个项目时保持独立的开发历史。子模块允许您将另一个项目的工作树包含在您自己的工作树中,同时保持两个项目的历史记录相互独立。此外,由于子模块固定在任意版本上,因此其他项目可以独立开发而不会影响超级项目,从而允许超级项目仅在需要时才固定到新版本。
-
将一个(逻辑上单一的)项目拆分为多个仓库并将其重新关联起来。这可用于克服 Git 当前实现的限制,以实现更细粒度的访问
-
Git 仓库的大小:在其当前形式下,对于包含未通过树之间增量计算压缩的内容的大型仓库,Git 的扩展性较差。例如,您可以使用子模块来存储大型二进制资产,并且这些仓库可以进行浅克隆,这样您就不会在本地拥有大量的历史记录。
-
传输大小:在当前形式下,Git 要求整个工作树都存在。它不允许在抓取或克隆时传输部分树。如果您工作的项目由多个作为子模块连接到超级项目中的仓库组成,则可以避免抓取您不感兴趣的仓库的工作树。
-
访问控制:通过限制用户对子模块的访问,这可用于实现不同用户的读/写策略。
-
子模块的配置
子模块操作可以通过以下机制进行配置(按优先级从高到低)
-
支持将子模块作为路径规范一部分的命令的命令行。大多数命令都有一个布尔标志
--recurse-submodules
,用于指定是否递归进入子模块。例如grep
和checkout
。一些命令接受枚举,例如fetch
和push
,您可以在其中指定子模块受到的影响方式。 -
子模块内部的配置。这包括子模块中的
$GIT_DIR/config
,但也包括树中的设置,例如指定子模块内部命令行为的.gitattributes
或.gitignore
文件。例如,当您在超级项目中运行
git
status
--ignore-submodules=none
时,会观察到子模块.gitignore
文件的效果。这通过在子模块中运行status
并注意子模块的.gitignore
文件来收集子模块工作目录中的信息。当在超级项目中运行
git
push
--recurse-submodules=check
时,子模块的$GIT_DIR/config
文件将发挥作用,因为这将检查子模块是否有任何未发布到任何远程的更改。远程仓库像往常一样在子模块的$GIT_DIR/config
文件中配置。 -
超级项目中的配置文件
$GIT_DIR/config
。Git 只会递归处理活动的子模块(参见下文的“活动子模块”部分)。如果子模块尚未初始化,则子模块内部的配置尚不存在,因此从何处获取子模块的配置将在此处进行。
-
超级项目中的
.gitmodules
文件。项目通常使用此文件来建议上游仓库集合的默认值,以实现子模块名称与其路径之间所需的映射。此文件主要用于超级项目中子模块名称和路径之间的映射,以便可以定位子模块的 Git 目录。
如果子模块从未初始化,这是唯一可以找到子模块配置的地方。它作为指定从何处获取子模块的最后回退。
形式
子模块可以采用以下形式
-
DESCRIPTION 中描述的基本形式,包含一个 Git 目录、一个工作目录、一个
gitlink
和一个.gitmodules
条目。 -
“旧形式”子模块:一个包含嵌入式
.git
目录的工作目录,以及超级项目中的跟踪gitlink
和.gitmodules
条目。这通常在使用旧版本 Git 生成的仓库中发现。可以手动构建这些旧形式的仓库。
当去初始化或删除(参见下文)时,子模块的 Git 目录会自动移动到超级项目的
$GIT_DIR/modules/
<name>/
。 -
去初始化子模块:一个
gitlink
和一个.gitmodules
条目,但没有子模块工作目录。子模块的 Git 目录可能仍然存在,因为去初始化后 Git 目录会被保留。原本应该是工作目录的目录是空的。子模块可以通过运行
git
submodule
deinit
来去初始化。除了清空工作目录外,此命令只修改超级项目的$GIT_DIR/config
文件,因此超级项目的历史记录不会受到影响。这可以通过使用git
submodule
init
来撤销。 -
已删除的子模块:子模块可以通过运行 git rm <submodule-path> && git commit 来删除。这可以通过使用
git
revert
来撤销。删除操作会移除超级项目的跟踪数据,即
gitlink
条目和.gitmodules
文件中的对应部分。子模块的工作目录会从文件系统中移除,但 Git 目录会被保留,以便在不从其他仓库抓取的情况下检出过去的提交。要完全删除子模块,请手动删除
$GIT_DIR/modules/
<name>/
。
活动的子模块
子模块被视为活动状态,
-
如果
submodule.
<name>.active
设置为true
或
-
如果子模块的路径匹配
submodule.active
中的路径规范或
-
如果
submodule.
<name>.url
已设置。
并且它们按此顺序进行评估。
例如
[submodule "foo"] active = false url = https://example.org/foo [submodule "bar"] active = true url = https://example.org/bar [submodule "baz"] url = https://example.org/baz
在上述配置中,只有子模块 bar 和 baz 是活动的,bar 是由于 (1),baz 是由于 (3)。foo 是非活动的,因为 (1) 优先于 (3)。
请注意,(3) 是一个历史遗留物,如果 (1) 和 (2) 指定子模块不活动,则 (3) 将被忽略。换句话说,如果我们有 submodule.
<name>.active
设置为 false
,或者子模块的路径在 submodule.active
中的路径规范中被排除,则 URL 是否存在都不重要。这在下面的示例中得到了说明。
[submodule "foo"] active = true url = https://example.org/foo [submodule "bar"] url = https://example.org/bar [submodule "baz"] url = https://example.org/baz [submodule "bob"] ignore = true [submodule] active = b* active = :(exclude) baz
在这里,除了 baz 之外的所有子模块(foo, bar, bob)都是活动的。foo 是由于其自身的活动标志,而所有其他子模块是由于子模块活动路径规范,该规范指定除了 baz 之外任何以 b 开头的子模块也是活动的,无论 .url 字段是否存在。
第三方库的工作流程
# Add a submodule git submodule add <URL> <path>
# Occasionally update the submodule to a new version: git -C <path> checkout <new-version> git add <path> git commit -m "update submodule to new version"
# See the list of submodules in a superproject git submodule status
# See FORMS on removing submodules
人工拆分仓库的工作流程
# Enable recursion for relevant commands, such that # regular commands recurse into submodules by default git config --global submodule.recurse true
# Unlike most other commands below, clone still needs # its own recurse flag: git clone --recurse <URL> <directory> cd <directory>
# Get to know the code: git grep foo git ls-files --recurse-submodules
注意
|
git ls-files 也需要其自己的 --recurse-submodules 标志。 |
# Get new code git fetch git pull --rebase
# Change worktree git checkout git reset
实现细节
克隆或拉取包含子模块的仓库时,子模块默认不会被检出;您可以指示 clone
递归处理子模块。git
submodule
的 init
和 update
子命令将使子模块在您的工作树中保持检出并处于适当的版本。或者,您可以设置 submodule.recurse
以使 checkout
递归处理子模块(请注意,submodule.recurse
也会影响其他 Git 命令,完整列表请参见 git-config[1])。