Windows下符号链接指向子模块时Git克隆异常的解决问询

问题根源 #

在Windows环境中开启core.symlinks=true后，用git clone --recurse-submodules克隆包含指向子模块内目录的符号链接的仓库时，会出现链接失效的问题，具体流程如下：

• Git先克隆主仓库，此时子模块还未被拉取，符号链接的目标路径不存在
• NTFS系统严格区分文件符号链接和目录符号链接，Git因无法识别目标类型，默认创建文件符号链接
• 子模块克隆完成后，原文件符号链接指向的是目录，在Windows下直接变成无效链接

拿示例仓库来说：根目录有子模块java-scripting-language，符号链接scripting指向该子模块内的src\main\com\zergatul\scripting目录，克隆后这个scripting链接会变成无效状态。

现有临时方案的不足 #

当前的临时修复步骤是先检出符号链接添加前的版本，再切回主分支：

git checkout 92b072cb536f4628eba0f9b70143e2010163ac58
git switch master

但这个步骤繁琐，而且对于需要快速克隆构建的开源仓库来说，操作成本太高。

更简洁的解决办法 #

方案1：手动拆分克隆流程（推荐，无额外依赖） #

通过调整克隆顺序，避开Git自动创建错误符号链接的环节：

1. 先克隆主仓库，不递归子模块

git clone https://github.com/Zergatul/symlink-test.git
cd symlink-test

2. 删除Git自动生成的无效文件符号链接

del scripting

3. 初始化并拉取子模块

git submodule update --init --recursive

4. 手动创建目录符号链接（需管理员权限，或开启Windows开发者模式允许普通用户创建符号链接）

mklink /D scripting java-scripting-language\src\main\com\zergatul\scripting

5. 让Git确认符号链接已正常修复（无需提交，仅本地同步状态）

git restore --staged scripting

方案2：用钩子脚本自动修复（适合需要批量处理的场景） #

如果需要自动化修复，可以写一个脚本作为Git钩子，在子模块更新后自动修正符号链接：

1. 创建fix-symlinks.bat脚本，内容如下：

@echo off
setlocal enabledelayedexpansion
:: 遍历仓库中所有符号链接，检查并修复指向目录的文件链接
for /f "delims=" %%i in ('git ls-files -s ^| findstr /R "^120000"') do (
    for /f "tokens=2,4" %%a in ("%%i") do (
        set "symlink_hash=%%a"
        set "symlink_path=%%b"
        :: 获取符号链接的目标路径
        for /f "delims=" %%c in ('git cat-file -p !symlink_hash!') do (
            set "target_path=%%c"
            :: 检查目标是否为目录（子模块已克隆后）
            if exist "!target_path!\" (
                :: 如果当前是文件符号链接，删除重建为目录链接
                if exist "!symlink_path!" (
                    del "!symlink_path!"
                    mklink /D "!symlink_path!" "!target_path!"
                )
            )
        )
    )
)
endlocal

2. 将脚本设置为post-submodule-update钩子：

git config core.hooksPath .githooks
mkdir .githooks
copy fix-symlinks.bat .githooks/post-submodule-update

对于开源仓库，可以把这个脚本和钩子配置说明一起纳入仓库，让使用者只需执行少量命令就能完成配置。

能否强制Git创建目录符号链接？ #

目前Git官方没有提供直接配置，让它在目标路径不存在时强制创建目录符号链接——因为Git无法提前预判目标是文件还是目录（尤其是目标在未初始化的子模块里）。所以暂时只能通过上述手动修复或钩子脚本的方式绕开这个问题。

内容的提问来源于stack exchange，提问作者Zergatul