923

如何git submodule add -b工作?

添加具有特定分支的子模块后,新的克隆存储库(之后git submodule update --init)将位于特定提交处,而不是分支本身(git status子模块上显示“当前不在任何分支上”)。

我找不到关于子模块分支或任何特定提交的任何信息.gitmodules.git/config那么 Git 是如何计算出来的呢?

另外,是否可以指定标签而不是分支?

我正在使用版本 1.6.5.2。

4

13 回答 13

882

注意:Git 1.8.2 添加了跟踪分支的可能性。请参阅下面的一些答案。


习惯这一点有点令人困惑,但子模块不在分支上。正如您所说,它们只是指向子模块存储库的特定提交的指针。

这意味着,当其他人签出您的存储库或提取您的代码并执行 git submodule update 时,子模块将签出到该特定提交。

这对于不经常更改的子模块非常有用,因为项目中的每个人都可以在同一个提交中拥有子模块。

如果要将子模块移动到特定标签:

cd submodule_directory
git checkout v1.0
cd ..
git add submodule_directory
git commit -m "moved submodule to v1.0"
git push

然后,另一个想要将 submodule_directory 更改为该标签的开发人员,这样做

git pull
git submodule update --init

git pull提交其子模块目录指向的更改。 git submodule update实际上合并到新代码中。

于 2009-11-22T09:19:34.167 回答
874

我想在这里添加一个答案,它实际上只是其他答案的集合,但我认为它可能更完整。

当你拥有这两个东西时,你就知道你有一个 Git 子模块。

  1. .gitmodules的条目如下:

    [submodule "SubmoduleTestRepo"]
        path = SubmoduleTestRepo
        url = https://github.com/jzaccone/SubmoduleTestRepo.git
    
  2. 您的 Git 存储库中有一个子模块对象(在此示例中名为 SubmoduleTestRepo)。GitHub将这些显示为“子模块”对象。或者git submodule status从命令行执行。Git 子模块对象是特殊类型的 Git 对象,它们保存特定提交的 SHA 信息。

    每当您执行 agit submodule update时,它都会使用来自提交的内容填充您的子模块。它知道在哪里可以找到提交,因为.gitmodules.

    现在,要做的就是在文件-b中添加一行。.gitmodules因此,按照相同的示例,它看起来像这样:

    [submodule "SubmoduleTestRepo"]
        path = SubmoduleTestRepo
        url = https://github.com/jzaccone/SubmoduleTestRepo.git
        branch = master
    

    注意:.gitmodules文件中只支持分支名称,不支持 SHA 和 TAG!(取而代之的是,可以使用“”来跟踪和更新每个模块的分支提交git add .,例如like git add ./SubmoduleTestRepo,您不需要.gitmodules每次都更改文件)

    子模块对象仍然指向特定的提交。该选项给您带来的唯一好处是能够根据 Vogella 的回答为您的更新-b添加一个标志:--remote

    git submodule update --remote
    

    它不是将子模块的内容填充到子模块指向的提交中,而是用主分支上的最新提交替换该提交,然后用该提交填充子模块。这可以通过 djacobs7 回答分两步完成。由于您现在已经更新了子模块对象指向的提交,因此您必须将更改的子模块对象提交到您的 Git 存储库中。

    git submodule add -b并不是让分支保持最新状态的神奇方式。它只是在文件中添加有关分支的信息,.gitmodules并为您提供在填充之前将子模块对象更新为指定分支的最新提交的选项。

于 2013-09-14T02:33:57.213 回答
427

(Git 2.22, Q2 2019, 已引入git submodule set-branch --branch aBranch -- <submodule_path>)

请注意,如果您有一个尚未跟踪分支的现有子模块,那么(如果您有 git 1.8.2+):

  • 确保父 repo 知道它的子模块现在跟踪一个分支:

      cd /path/to/your/parent/repo
      git config -f .gitmodules submodule.<path>.branch <branch>
    
  • 确保您的子模块实际上是该分支的最新版本:

      cd path/to/your/submodule
      git checkout -b branch --track origin/branch
        # if the master branch already exist:
        git branch -u origin/master master
    

         ('origin' 是子模块已从中克隆的上游远程仓库
的名称。该子模块内          的 Agit remote -v将显示它。通常,它是 'origin')

  • 不要忘记在父仓库中记录子模块的新状态:

      cd /path/to/your/parent/repo
      git add path/to/your/submodule
      git commit -m "Make submodule tracking a branch"
    
  • 该子模块的后续更新必须使用以下--remote选项:

      # update your submodule
      # --remote will also fetch and ensure that
      # the latest commit from the branch is used
      git submodule update --remote
    
      # to avoid fetching use
      git submodule update --remote --no-fetch 
    

请注意,使用Git 2.10+(2016 年第三季度),您可以使用 ' .' 作为分支名称:

分支名称记录submodule.<name>.branch.gitmodulesfor update --remote
一个特殊的值.用于表示子模块中的分支名称应该与当前存储库中的当前分支名称相同

但是,正如LubosD所评论的那样

git checkout如果要遵循的分支名称是“ .”,它将杀死您未提交的工作!
改为使用git switch

这意味着 Git 2.23(2019 年 8 月)或更高版本。

见“迷惑git checkout


如果要更新分支后的所有子模块:

    git submodule update --recursive --remote

请注意,对于每个更新的子模块,结果几乎总是一个分离的 HEAD,正如Dan Cameron在他的回答中指出的那样。

Clintm在评论中指出,如果您运行git submodule update --remote并且生成的 sha1 与子模块当前所在的分支相同,则它不会做任何事情并使子模块仍然“在该分支上”,而不是处于分离的头状态。 )

为了确保实际签出分支(并且不会修改代表父 repo 的子模块的特殊条目的 SHA1),他建议:

git submodule foreach -q --recursive 'branch="$(git config -f $toplevel/.gitmodules submodule.$name.branch)"; git switch $branch'

每个子模块仍将引用相同的 SHA1,但如果您确实进行了新提交,您将能够推送它们,因为它们将被您希望子模块跟踪的分支引用。
在子模块中推送之后,不要忘记返回父仓库,为那些修改过的子模块添加、提交和推送新的 SHA1。

注意Alexander Pogrebnyak在评论$toplevel推荐的使用。于 2010 年 5 月在 git1.7.2 中引入:commit f030c96
$toplevel

它包含顶级目录的绝对路径(在哪里.gitmodules)。

dtmland在评论中添加:

foreach 脚本将无法检出未跟随分支的子模块。
但是,此命令为您提供了两个:

 git submodule foreach -q --recursive 'branch="$(git config -f $toplevel/.gitmodules submodule.$name.branch)"; [ "$branch" = "" ] && git checkout master || git switch $branch' –

相同的命令但更易于阅读:

git submodule foreach -q --recursive \
    'branch="$(git config -f $toplevel/.gitmodules submodule.$name.branch)"; \
     [ "$branch" = "" ] && \
     git checkout master || git switch $branch' –
  

umläute在评论中使用简化版本改进了 dtmland的命令:

git submodule foreach -q --recursive 'git switch $(git config -f $toplevel/.gitmodules submodule.$name.branch || echo master)'

多行:

git submodule foreach -q --recursive \
  'git switch \
  $(git config -f $toplevel/.gitmodules submodule.$name.branch || echo master)'

在 Git 2.26(2020 年第一季度)之前,被告知以递归方式获取子模块中的更新的 fetch 不可避免地会产生大量输出,并且很难发现错误消息。

该命令已被教导枚举在操作结束时出现错误的子模块

请参阅Emily Shaffer ( ) 的提交 0222540(2020 年 1 月 16 日(由Junio C Hamano 合并 -- --提交 b5c71cc中,2020 年 2 月 5 日)nasamuffin
gitster

fetch:强调子模块获取期间的失败

签字人:Emily Shaffer

在有许多子模块时子模块获取失败的情况下,如果有多个子模块返回,则来自单独失败的子模块获取的错误会被隐藏在其他子模块上的活动中fetch-by-oid
延迟调用失败,以便用户知道出了什么问题,以及在哪里

因为fetch_finish()run_processes_parallel,需要通过互斥来同步调用submodules_with_errors


请注意,在 Git 2.28(2020 年第三季度)中,脚本化的“git submodule”Porcelain 命令的部分重写将继续;这次git submodule set-branch轮到 " " 子命令了。

请参阅Shourya Shukla ( ) 的提交 2964d6e(2020 年 6 月 2日(由Junio C Hamano 合并 -- --提交 1046282中,2020 年 6 月 25 日)periperidip
gitster

submodule: 从 shell 到 C 的端口子命令 'set-branch'

指导者:Christian Couder
指导者:Kaartic Sivaraam
帮助者:Denton Liu
帮助者:Eric Sunshine
帮助者:Đoàn Trần Công Danh
签字者:Shourya Shukla

将子模块子命令 'set-branch' 转换为内置命令并通过git submodule.sh.

于 2013-09-14T06:59:18.890 回答
272

Git 1.8.2 增加了跟踪分支的可能性。

# add submodule to track branch_name branch
git submodule add -b branch_name URL_to_Git_repo optional_directory_rename

# update your submodule
git submodule update --remote 

另请参阅Git 子模块

于 2013-04-03T08:44:33.253 回答
69

我如何使用 Git 子模块的示例。

  1. 创建一个新的存储库
  2. 然后克隆另一个存储库作为子模块
  3. 然后我们让该子模块使用一个名为 V3.1.2 的标签
  4. 然后我们承诺。

这看起来有点像这样:

git init 
vi README
git add README
git commit 
git submodule add git://github.com/XXXXX/xxx.yyyy.git stm32_std_lib
git status

git submodule init
git submodule update

cd stm32_std_lib/
git reset --hard V3.1.2 
cd ..
git commit -a

git submodule status 

也许它有帮助(即使我使用标签而不是分支)?

于 2009-11-22T09:53:15.883 回答
43

根据我的经验,在超级项目中切换分支或将来的结帐仍然会导致子模块的 HEAD 分离,无论是否正确添加和跟踪子模块(即@djacobs7 和@Johnny Z 的答案)。

而不是手动或通过脚本手动检查正确的分支并且可以使用git submodule foreach

这将检查分支属性的子模块配置文件并签出设置的分支。

git submodule foreach -q --recursive 'branch="$(git config -f $toplevel.gitmodules submodule.$name.branch)"; git checkout $branch'

于 2013-11-09T04:54:45.243 回答
40

Git 子模块有点奇怪——它们总是处于“分离头”模式——它们不会像你想象的那样更新到分支上的最新提交。

但是,当您考虑它时,这确实是有道理的。假设我使用子模块bar创建存储库foo。我推送我的更改并告诉您从存储库foo签出提交 a7402be 。

然后想象有人在您进行克隆之前提交了对存储库栏的更改。

当您从存储库foo签出提交 a7402be 时,您希望得到与我推送的相同的代码。这就是为什么子模块在您明确告诉它们然后进行新提交之前不会更新的原因。

我个人认为子模块是 Git 中最令人困惑的部分。有很多地方可以比我更好地解释子模块。我推荐Scott Chacon 的Pro Git

于 2009-11-22T05:22:58.740 回答
23

要为子模块切换分支(假设您已经将子模块作为存储库的一部分):

  • cd到包含子模块的存储库的根目录
  • 打开.gitmodules编辑
  • 在下面添加一行path = ...url = ...表示branch = your-branch每个子模块;保存文件.gitmodules
  • 然后不改变目录做$ git submodule update --remote

...这应该为每个这样修改的子模块拉入指定分支上的最新提交。

于 2016-06-12T13:34:53.900 回答
14

我的.gitconfig档案里有这个。它仍然是一个草案,但到目前为止证明是有用的。它可以帮助我始终将子模块重新附加到它们的分支。

[alias]

######################
#
# Submodules aliases
#
######################

# git sm-trackbranch: places all submodules on their respective branch specified in .gitmodules
# This works if submodules are configured to track a branch, i.e if .gitmodules looks like:
# [submodule "my-submodule"]
#   path = my-submodule
#   url = git@wherever.you.like/my-submodule.git
#   branch = my-branch
sm-trackbranch = "! git submodule foreach -q --recursive 'branch=\"$(git config -f $toplevel/.gitmodules submodule.$name.branch)\"; git checkout $branch'"

# sm-pullrebase:
# - pull --rebase on the master repo
# - sm-trackbranch on every submodule
# - pull --rebase on each submodule
#
# Important note:
# - have a clean master repo and subrepos before doing this!
# - this is *not* equivalent to getting the last committed
#   master repo + its submodules: if some submodules are tracking branches
#   that have evolved since the last commit in the master repo,
#   they will be using those more recent commits!
#
#   (Note: On the contrary, git submodule update will stick
#   to the last committed SHA1 in the master repo)
sm-pullrebase = "! git pull --rebase; git submodule update; git sm-trackbranch ; git submodule foreach 'git pull --rebase' "

# git sm-diff will diff the master repo *and* its submodules
sm-diff = "! git diff && git submodule foreach 'git diff' "

# git sm-push will ask to push also submodules
sm-push = push --recurse-submodules=on-demand

# git alias: list all aliases
# useful in order to learn git syntax
alias = "!git config -l | grep alias | cut -c 7-"
于 2015-04-01T16:27:47.347 回答
4

我们使用Quack从另一个 Git 存储库中提取特定模块。我们需要在没有提供存储库的整个代码库的情况下提取代码——我们需要从那个巨大的存储库中获取一个非常具体的模块/文件,并且每次运行更新时都应该更新。

所以我们是这样实现的:

创建配置

name: Project Name

modules:
  local/path:
    repository: https://github.com/<username>/<repo>.git
    path: repo/path
    branch: dev
  other/local/path/filename.txt:
    repository: https://github.com/<username>/<repo>.git
    hexsha: 9e3e9642cfea36f4ae216d27df100134920143b9
    path: repo/path/filename.txt

profiles:
  init:
    tasks: ['modules']

通过上述配置,它从提供的 GitHub 存储库创建一个目录,如第一个模块配置中指定的那样,另一个是从给定存储库中提取并创建一个文件。

其他开发者只需要运行

$ quack

它从上述配置中提取代码。

于 2015-10-22T14:35:13.230 回答
4

为子模块选择分支的唯一效果是,每当您--remote在命令行中传递选项时git submodule update,Git 都会以分离的 HEAD模式(如果选择了默认--checkout行为)签出该选定远程分支的最新提交。

如果您使用子模块的浅层克隆,则在为 Git 子模块使用此远程分支跟踪功能时必须特别小心。您在子模块设置中为此目的选择的分支不是git submodule update --remote. 如果你还传递了--depth参数并且你没有告诉 Git 你想要克隆哪个分支——实际上你不能git submodule update命令行中!- ,当显式参数丢失时,它将隐含地表现得像git-clone(1)文档中解释的那样,因此它只会克隆主分支git clone --single-branch--branch

毫不奇怪,在该git submodule update命令执行的克隆阶段之后,它最终会尝试检查您之前为子模块设置的远程分支的最新提交,并且,如果这不是主要的,则它不是您的本地浅克隆,因此它将失败

致命的:需要一次修订

无法在子模块路径“mySubmodule”中找到当前来源/ NotThePrimaryBranch修订版

于 2018-05-29T15:52:16.390 回答
3

git submodule add -b develop --name 分支名称 -- https://branch.git

于 2019-03-07T09:04:07.217 回答
2

现有答案缺少第二步,并且细节过多。

要切换现有子模块以跟踪新的远程 url 和/或新分支:

  1. 在 中编辑事实来源.gitmodules

例如,从

[submodule "api"]
    path = api
    url = https://github.com/<original_repo>/api.git

[submodule "api"]
    path = api
    url = https://github.com/<another_repo>/api.git
    branch = work-in-progress
  1. 从运行.git/modules中指定的刚刚编辑的真实来源更新 git 缓存的子模块的描述。.gitmodulesgit submodule sync

  2. 使用 . 更新工作副本中签出的子模块git submodule update --init --recursive --remote

  3. 提交更改。

于 2022-02-08T00:15:08.757 回答