【git的摸鱼技巧】之工欲善其事

Git 常见问题与操作记录

本文档记录了在处理 Git 仓库（特别是含有子模块、分支迁移）时遇到的一系列问题及解决方法。

一、子模块添加失败："已经存在于索引中"

错误现象

bash 复制代码

git submodule add -b master <url> baseline
# 错误：'baseline' 已经存在于索引中

原因

索引（staging area）中已经存在该子模块（或同名的普通文件/目录）的记录。

可能是之前不完整的添加、残留的 .gitmodules 配置或工作目录中的冲突。

解决方法

从索引中强制移除

bash 复制代码

git rm -f --cached baseline

删除 Git 内部子模块元数据

bash 复制代码

rm -rf .git/modules/baseline

bash 复制代码

rm -rf baseline

清理配置文件

bash 复制代码

git config -f .gitmodules --remove-section submodule.baseline 2>/dev/null
git config --remove-section submodule.baseline 2>/dev/null

提交删除

bash 复制代码

git add .gitmodules
git commit -m "Remove broken submodule baseline"

重新添加子模块

bash 复制代码

git submodule add -b master <正确的URL> baseline
git submodule update --init --recursive

二、合并冲突导致索引损坏

错误现象

bash 复制代码

error: 'baseline' appears as both a file and as a directory
fatal: cannot drop to stage #0
fatal: 不能重置索引文件至版本 'HEAD'

原因

之前的 git merge 或 git pull 产生了冲突，且冲突文件中有子模块。
索引状态不一致。

解决方法

放弃当前合并/变基

bash 复制代码

git merge --abort   # 如果是 merge 冲突
git rebase --abort  # 如果是 rebase 冲突

如果上述命令失败，硬重置到 HEAD（注意会丢失未提交的修改）

bash 复制代码

git reset --hard HEAD

三、子模块内文件无法直接 add 到主仓库

错误现象

bash 复制代码

git add /path/to/baseline/CMakeLists.txt
# fatal: 路径规格 '...' 在子模组 'baseline' 中

原因

子模块是一个独立的 Git 仓库，不能从主仓库直接添加其内部文件。

解决方法

bash 复制代码

cd baseline
git add CMakeLists.txt
git commit -m "Update files"

然后在主仓库中更新子模块引用：

bash 复制代码

cd ../..
git add baseline
git commit -m "Update submodule baseline"

四、分支迁移：将旧仓库的本地分支导入新仓库

场景

旧仓库中有一个本地分支 breach，从未推送到远程。
新仓库（cfsdev_zx）需要获得该分支及其完整提交历史。

方法一：使用 git bundle（推荐）

在旧仓库中打包分支

bash 复制代码

cd /path/to/old-repo
git bundle create breach.bundle breach

bash 复制代码

cp breach.bundle /path/to/new-repo/

在新仓库中解包并创建分支

bash 复制代码

cd /path/to/new-repo
git bundle unbundle breach.bundle
git checkout -b breach FETCH_HEAD

推送到新仓库的远程

bash 复制代码

git push -u origin breach

方法二：添加旧仓库为本地远程

添加远程

bash 复制代码

cd /path/to/new-repo
git remote add old-local /path/to/old-repo
# 或使用远程 URL（如果有）
# git remote add old-repo ssh://.../xxxx.git

获取分支

bash 复制代码

git fetch old-local

创建本地分支

bash 复制代码

git checkout -b breach old-local/breach

删除临时远程

bash 复制代码

git remote remove old-local

五、远程分支在本地可见但服务器上不存在

现象

git branch -r 显示 origin/breach。
但在 GitLab 网页上看不到该分支，且 git fetch 也获取不到。

原因

该分支曾经被推送到远程，但后来被删除或从未真正推送成功。
本地存储的远程跟踪引用可能是旧的缓存。

解决方法

删除本地无效的远程跟踪引用：

bash 复制代码

git remote prune origin

如果确实需要该分支，从其他有该分支的本地仓库导入（参考"分支迁移"）。

六、拉取远程分支失败："Couldn't find remote ref breach"

错误

bash 复制代码

git pull --tags origin breach
# fatal: Couldn't find remote ref breach

原因

远程仓库中没有名为 breach 的分支。

解决方法

检查远程分支列表：git branch -r。
如果该分支确实不存在，则需从其他地方（如本地备份）恢复，或创建新的分支。

七、CMake 构建时子模块目录缺少 CMakeLists.txt

错误

text 复制代码

CMake Error at .../CMakeLists.txt:18 (add_subdirectory):
  The source directory .../time/baseline does not contain a CMakeLists.txt file.

原因

子模块 time/baseline 没有正确初始化或克隆。

解决方法

初始化并更新子模块

bash 复制代码

git submodule update --init --recursive

如果子模块配置损坏，按照第一节"子模块添加失败"中的方法彻底清理并重新添加。

八、安装时找不到配置文件

错误

text 复制代码

file INSTALL cannot find "sample_defs/yhlog.conf".

解决方法

创建空文件（临时）

bash 复制代码

touch sample_defs/yhlog.conf

从其他正常构建目录复制该文件。
修改 CMakeLists.txt，注释或删除安装该文件的指令。

总结

处理子模块时，务必确保索引干净，及时提交 .gitmodules 的更改。
合并冲突导致索引损坏时，优先尝试 git merge --abort 或 git reset --hard HEAD。
本地分支迁移使用 git bundle 或添加本地路径远程是最可靠的方法。
远程跟踪引用无效时，使用 git remote prune origin 清理。
确保远程分支信息是最新的

九、合并另一个仓库远程分支的某一个提交

获取最新

bash 复制代码

git fetch first

2. 查看远程分支的提交历史，找到目标 commit 的哈希值

bash 复制代码

git log first/qicongjie --oneline

记下你需要的那一行开头的短哈希（例如 abc1234）。

3. 切换到目标本地分支（例如 first_dev 或 master）

bash 复制代码

git checkout first_dev

（如果本地分支不存在，可以先创建：git checkout -b first_dev）

4. 使用 cherry-pick 应用该 commit

bash 复制代码

git cherry-pick <commit-hash>

示例：

bash 复制代码

git cherry-pick abc1234

5. 如果出现冲突，解决冲突后继续

bash 复制代码

# 手动解决冲突文件
git add .
git cherry-pick --continue

如果不想继续，可以 git cherry-pick --abort 放弃操作。

示例完整流程

bash 复制代码

git fetch first
git log first/xxx --oneline
# 输出：abc1234 Fix something
#       def5678 Update config
git checkout first_dev
git cherry-pick abc1234