Git submodule执行报错：.git非目录，无法确定Git目录绝对路径

出现.../.git: Not a directory和Unable to determine absolute path of git directory错误，核心原因是当前操作的主仓库不符合Git仓库规范，具体可能有以下几种情况：

• 当前所在目录不是合法的Git仓库根目录：比如误在主仓库子目录执行submodule命令，或主仓库未完成git init初始化。
• 主仓库的.git目录损坏：比如.git被误改为文件（而非目录），或目录内关键文件丢失、权限异常，导致Git无法识别它为仓库核心配置目录。
• 权限不足：当前操作系统用户没有读取或写入主仓库.git目录的权限，导致Git无法访问目录内容。

1. 确认当前目录是主仓库根目录
   执行git status命令，若返回仓库状态信息，说明当前目录是合法Git仓库；若报错，说明未在正确目录，或主仓库未初始化。

2. 检查.git是否为目录

   • Linux/macOS执行：ls -la .git
   • Windows执行：dir .git
     若输出显示.git是文件而非目录，说明仓库已损坏，需从备份恢复.git目录，或重新初始化仓库（注意：重新初始化会丢失现有提交历史，谨慎操作）。

3. 修复权限问题
   若.git是目录但仍报错，检查目录权限：

   • Linux/macOS执行：chmod -R 755 .git（赋予读写执行权限）
   • Windows右键.git目录，进入「属性-安全」，确保当前用户有完全控制权限。

如果submodule命令暂时无法使用，可以尝试以下两种替代方案：

1. 手动配置子模块 #

手动完成submodule的配置流程，步骤如下：

• 在主仓库根目录创建目标文件夹：mkdir documents
• 克隆子仓库到该文件夹：git clone https://<login>:<pass>@bitbucket.[hidden]/documents.git documents
• 在主仓库根目录创建或编辑.gitmodules文件，添加以下内容：

  [submodule "documents"]
      path = documents
      url = https://<login>:<pass>@bitbucket.[hidden]/documents.git
  

• 执行git add .gitmodules documents，然后提交变更：git commit -m "Add documents submodule manually"

2. 使用Git Subtree #

Subtree是将子仓库代码直接合并到主仓库目录的方案，无需单独维护子模块的.git目录，适合不需要独立管理子仓库生命周期的场景：

• 添加子仓库作为subtree：

  git subtree add --prefix=documents https://<login>:<pass>@bitbucket.[hidden]/documents.git 主分支名 --squash
  

  （将「主分支名」替换为子仓库的默认分支，比如main或master）
• 后续更新子仓库代码：

  git subtree pull --prefix=documents https://<login>:<pass>@bitbucket.[hidden]/documents.git 主分支名 --squash
  

内容的提问来源于stack exchange，提问作者Михаил