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”。