git子模块

1 子模块管理的关键文件和配置

在 git 中使用子模块时，git 会利用几个特殊的文件和配置来管理子模块。以下是涉及子模块管理的关键文件和配置：

1.1 .gitmodules

• 这是一个文本文件，位于 git 仓库的根目录下。
• 它记录了子模块的信息，包括每个子模块的路径、url 和分支。
• 这个文件应该被添加到版本控制中，以便其他克隆了主仓库的人也能获取和初始化子模块。

示例 .gitmodules 文件内容：

[submodule "aigc/opencompass"]
    path = aigc/opencompass
    url = https://github.com/open-compass/opencompass.git
    branch = master

1.2 .git/config

• 这是 git 仓库的本地配置文件。
• 它也包含有关子模块的信息，通常在运行 git submodule init 时，子模块的信息会从 .gitmodules 被复制到 .git/config 中。
• .git/config 文件存储的子模块信息是本地特有的，不会被推送到远程仓库。

1.3 .git/modules

• 这是存储子模块 git 仓库数据的目录。
• 当您初始化子模块时，git 会在这个目录下创建一个子目录来存储每个子模块的 git 数据（例如对象、引用等）。
• 这个结构使得主仓库能够维护干净的目录结构，同时保持子模块作为独立仓库的数据。

1.4 子模块目录

• 子模块的实际内容被克隆到主仓库的子目录中，该目录由 .gitmodules 中的 path 指定。
• 子模块目录内部会有一个 .git 文件，该文件指向实际的 git 数据存储位置，通常是 ../../.git/modules/path/to/submodule。

1.5 处理子模块的 git 命令

虽然这些不是文件，但了解相关的 git 命令对于管理子模块同样重要：

• git submodule add <url> <path>：添加新的子模块。
• git submodule init：初始化子模块，即将 .gitmodules 中的信息复制到 .git/config。
• git submodule update：更新子模块到在主仓库中记录的特定提交。
• git submodule update --init --recursive：递归地初始化并更新子模块及其所有嵙套的子模块。

通过正确使用这些文件和命令，可以有效地管理包含子模块的 git 仓库。这对于包含第三方依赖或库的项目尤其重要。

2 子模块和主仓库的提交

需要分开处理当您在一个包含子模块的 git 仓库中修改了子模块的内容，不能直接使用 git commit -a -m 'xxx 来提交主仓库和子模块的变更。这是因为子模块在 git 中被视为独立的仓库，它们有自己的独立版本历史。

2.1 提交子模块的变更

首先，您需要进入子模块的目录，并对子模块内的变更进行提交：

cd aigc/opencompass  # 进入子模块目录
git add .            # 添加所有变更到暂存区
git commit -m "describe changes made in the submodule"

这一步确保了子模块的变更被记录在子模块的版本历史中。如果您尝试在主仓库中使用 git commit -a，它只会记录子模块的新提交引用，而不会提交子模块内部的实际文件变更。

2.2 提交主仓库的变更

返回到主仓库目录，提交子模块的新状态（这实际上是子模块的新提交哈希）到主仓库：

cd ../..             # 返回到主仓库根目录
git add aigc/opencompass  # 将子模块的新状态添加到暂存区
git commit -m "update submodule reference to the latest commit"

这一步是必要的，因为虽然子模块的内容已经在子模块的仓库中被提交，但是主仓库需要更新其记录的子模块的引用（即子模块的提交哈希），以反映子模块的最新状态。

3.3 推送变更

完成以上步骤后，推送主仓库和子模块的变更到远程仓库：

git push origin master  # 推送主仓库变更
cd aigc/opencompass      # 再次进入子模块
git push origin master  # 推送子模块变更

3 清理并重新添加子模块（如果需要）

3.1 清理子模块

git submodule deinit -f aigc/opencompass
rm -rf .git/modules/aigc/opencompass
git rm -f aigc/opencompass
git add .
git commit -m "remove submodule"

3.2 重新添加子模块

git submodule add https://github.com/open-compass/opencompass.git aigc/opencompass
git submodule update --init --recursive

4 管理远程仓库拉取更新并推送到另一个远程仓库的子模块

要按照以下步骤操作：

4.1确保子模块正确初始化和更新

首先，确保子模块已经正确初始化并链接到正确的远程仓库。

cd aigc/opencompass
git submodule update --init

4.2 将子模块的远程仓库设置为 github

进入子模块目录，并将其远程仓库设置为 github 上的 url。

cd aigc/opencompass
git remote add upstream https://github.com/open-compass/opencompass.git

这里使用 upstream 作为远程仓库的名称，表示原始源头仓库。如果 upstream 已经存在，您可能需要先用 git remote remove upstream 删除旧的远程配置。

4.3 从 github 拉取最新更新

从 github 的仓库拉取最新的更新到本地。

git fetch upstream
git checkout master  # 或者您需要同步的分支
git merge upstream/master

处理可能出现的合并冲突，并提交这些更改。

4.4 推送更新到您的公司仓库

将更新后的内容推送到公司的远程仓库。首先确认您有权限推送到该仓库，并且已经设置了正确的远程仓库地址。

git remote add origin ssh://100@10.95.243.146:29418/systemtestdep/testtesttoolsoftware/jingzhun/aigc/opencompass
git push origin master

这里使用 origin 作为远程仓库的名称，如果已经设置了不同的仓库地址，可能需要更新或使用不同的远程名称。

4.5 确保主项目中的子模块引用更新

回到主项目目录，更新子模块的引用并提交这些更改。

cd ../..
git add aigc/opencompass
git commit -m "update submodule reference to the latest commit"
git push

这确保了主项目引用了子模块的最新提交。

4.6 注意事项

1. 合并冲突：在合并 github 上的更改时，您可能会遇到冲突。确保仔细解决所有冲突，并在本地测试所有更改以确保一切功能正常。

2. 权限：确保您拥有所有远程仓库的推送权限。如果不确定，与您的系统管理员确认。

3. 验证远程 url：使用 git remote -v 查看远程仓库的 url 是否正确设置。

通过这些步骤，您可以有效地管理涉及多个远程仓库的子模块更新和推送操作。

5 错误信息 fatal: 远程 origin 已经存在

表示 git 仓库中已经有一个名为 origin 的远程仓库配置。如果您想更改 origin 的 url 或者添加一个新的远程仓库，您可以采取以下几个不同的步骤：

5.1 查看当前的远程仓库配置

首先，检查现有的 origin 远程仓库配置，看看它指向哪里：

git remote -v

这会显示所有远程仓库的名称及其对应的 url。

5.2 更改现有的远程仓库 url

如果您想要更改已存在的 origin 远程仓库的 url，可以使用以下命令：

git remote set-url origin ssh://100@10.95.243.146:29418/systemtestdep/testtesttoolsoftware/jingzhun/aigc/opencompass

这个命令会更新 origin 的 url 到新的地址。

5.3 移除并重新添加远程仓库

如果您想完全重新配置 origin，可以先删除现有的远程仓库，然后再添加新的：

git remote remove origin
git remote add origin ssh://100@10.95.243.146:29418/systemtestdep/testtesttoolsoftware/jingzhun/aigc/opencompass

这将删除旧的 origin 并用新的 url 添加它。

5.4 添加一个不同名称的远程仓库

如果您想保留 origin 并添加另一个远程仓库，可以选择一个不同的名称：

git remote add another-origin ssh://100@10.95.243.146:29418/systemtestdep/testtesttoolsoftware/jingzhun/aigc/opencompass

这样，您可以有多个远程仓库配置，可以自由地推送和拉取到不同的远程仓库。

6 在主工程中包含一个第三方库作为子目录同时保留所做的修改并定期更新

6.1 使用 git 子模块（submodule）

git 子模块允许您将一个git仓库作为另一个git仓库的子目录，它可以在主仓库中保持自己的独立版本历史。

优点：

• 子模块和主仓库独立管理，易于跟踪第三方库的更新。
• 可以选择性地更新子模块，同时保持对子模块的更改。

操作步骤：

1. 将第三方库作为子模块添加到您的主工程中：

   git submodule add <repository-url> <path/to/submodule>
   

2. 当第三方库有更新时，您可以进入子模块目录，拉取最新的更改：

   cd <path/to/submodule>
   git pull origin master  # 假设您关注的是 master 分支
   

3. 解决可能出现的合并冲突，确保您的修改得以保留。
4. 提交更新到主仓库，包括子模块的新提交引用：

   cd <path/to/main/project>
   git add .
   git commit -m "update submodule to latest version"
   

6.2 使用 git 子树（subtree）

git 子树允许您将第三方库合并到您的主仓库中，作为项目的一部分处理，同时仍然能够从上游库拉取更新。

优点：

• 子树是主仓库的一部分，不需要初始化或更新子模块。
• 方便同时提交对主仓库和子树的更改。

操作步骤：

1. 将第三方库作为子树添加到您的主工程中：

   git subtree add --prefix <path/to/subtree> <repository-url> master --squash
   

2. 拉取并合并第三方库的更新：

   git subtree pull --prefix <path/to/subtree> <repository-url> master --squash
   

3. 解决合并中出现的冲突，保留您的更改。
4. 提交更新到您的主仓库。

6.3 简单嵌套的方式

将一个第三方库的git仓库简单地克隆到您的主仓库的子目录中，但不使用git的子模块或子树功能，确实是一种可行的方法，特别是如果您想保持操作的简便性。简单嵌套的方式在操作上可能更直接，特别是对于小型项目或者不需要频繁同步第三方库更新的情况。然而，如果第三方库更新频繁，或者需要精确追踪第三方库的变更，使用git子模块或子树可能是更好的选择，因为这些方法提供了更好的工具来管理和集成外部库的更新。

优点

• 简单易懂：不需要配置子模块或子树，对git新手来说更加直观。
• 独立操作：第三方库完全独立于主仓库，可以单独进行版本控制和管理。

缺点

• 更新复杂：当第三方库需要更新时，需要手动处理可能出现的合并冲突，并确保自己的修改不会被覆盖。
• 版本跟踪不便：主仓库无法直接追踪子目录库的版本变化，不易管理子目录库的具体版本。
• 忽略处理：为了防止主仓库对子目录进行版本控制，可能需要在 .gitignore 中添加规则来忽略子目录。

如果选择简单嵌套的方式，以下是一个基本的操作流程：

1. 克隆第三方库到子目录

   cd path/to/your/main/project
   git clone https://github.com/third-party/library path/to/subdirectory
   

2. 在主项目的 .gitignore 文件中忽略该子目录 (可选)

   # .gitignore
   path/to/subdirectory/
   

3. 定期更新第三方库

   • 进入子目录，拉取最新的更新：

     cd path/to/subdirectory
     git pull origin master
     

   • 解决可能出现的合并冲突，并确保您的修改被适当地合并。

4. 将修改提交到第三方库的本地或远程分支（如果有权限）

   git add .
   git commit -m "your custom changes"
   git push origin your-branch