Checkout creates incorrect symlink type file instead of directory.

[kcieplak]

Existing issues matching what you're seeing

• I was not able to find an open or closed issue matching what I'm seeing

Git for Windows version

git --version --build-options
git version 2.51.2.windows.1
cpu: aarch64
built from commit: bd2ecbae58213046a468256b95fc4864de25bdf5
sizeof-long: 4
sizeof-size_t: 8
shell-path: C:/git-sdk-arm64-build-installers/usr/bin/sh
feature: fsmonitor--daemon
libcurl: 8.16.0
OpenSSL: OpenSSL 3.5.4 30 Sep 2025
zlib: 1.3.1
SHA-1: SHA1_DC
SHA-256: SHA256_BLK
default-ref-format: files
default-hash: sha1

Windows version

Windows 11

Windows CPU architecture

ARM64

Additional Windows version information

Microsoft Windows [Version 10.0.26200.7623]

Options set during installation

Defaults

Other interesting things

No response

Terminal/shell

cmd

Commands that trigger the issue

The swift-package-manager https://github.com/swiftlang/swift-package-manager uses git repositories for dependant packages. The manager invokes git.exe to cache and create working copies of dependent packages.

In this case the dependent package that has symlinks is the swift-docc-plugin package https://github.com/swiftlang/swift-docc-plugin.

.package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0"),

The package manager does the following to bring in a dependent package

git clone <URL> --mirror <repository cache path>

Then it clones from the mirror into a working directory
git clone --no-checkout <repository cache path> <repository working path>

'git checkout ' in CWD of

To recreate this failure.
Install the swift-toolchain for windows.
https://www.swift.org/install/windows/

git clone https://github.com/swiftlang/swift-package-manager
cd swift-package-manager
swift build -vv

The logs indicate that there are invalid symlinks.

warning: 'swift-docc-plugin': ignoring broken symlink S:\swift-package-manager\.build-native\checkouts\swift-docc-plugin\Plugins\Swift-DocC Convert\Symbolic Links\SwiftDocCPluginUtilities
warning: 'swift-docc-plugin': ignoring broken symlink S:\swift-package-manager\.build-native\checkouts\swift-docc-plugin\Plugins\Swift-DocC Preview\Symbolic Links\SwiftDocCPluginUtilities

Looking at the working checkout at S:\swift-package-manager\.build-native\checkouts\swift-docc-plugin

02/04/2026  09:03 AM    <DIR>          .
02/04/2026  09:03 AM    <DIR>          ..
02/04/2026  09:03 AM               304 README.md
02/04/2026  09:03 AM    <SYMLINKD>     SharedPackagePluginExtensions [..\..\SharedPackagePluginExtensions]
02/04/2026  09:03 AM    <SYMLINK>      SwiftDocCPluginUtilities [..\..\..\Sources\SwiftDocCPluginUtilities]
               2 File(s)            304 bytes
               3 Dir(s)  162,349,457,408 bytes free

The symlink is a file symlink yet the source is actually a directory.

 Directory of C:\Users\jenkins\workspace\swift_oss\swift-package-index-metrics\spi-workdir\F24B67B2-92EF-46C6-8DBB-36249A7CD64E\swift-package-manager\.build-native\checkouts\swift-docc-plugin\Sources

02/04/2026  09:03 AM    <DIR>          .
02/04/2026  09:03 AM    <DIR>          ..
02/04/2026  09:03 AM    <DIR>          snippet-extract
02/04/2026  09:03 AM    <DIR>          Snippets
02/04/2026  09:03 AM    <DIR>          SwiftDocCPluginDocumentation
02/04/2026  09:03 AM    <DIR>          SwiftDocCPluginUtilities
               0 File(s)              0 bytes
               6 Dir(s)  162,348,146,688 bytes free

Expected behaviour

I expect that the 'SwiftDocCPluginUtilities' symlink above is a directory symlink.

Actual behaviour

The 'SwiftDocCPluginUtilities' symlink is a file symlink, and thus when we try to validate the symlink it fails, hence the warning. This causes a failure in completion as we are missing some of the target .swift files.

Repository

https://github.com/swiftlang/swift-docc-plugin

[dscho]

My interpretation of this report leads to this as the most likely explanation: At the time Git creates the symbolic link, the target does not exist (or isn't a directory). I do not really know what else Git for Windows can do to help this scenario in addition to the already-existing support for setting the symbolic link type via the Git attributes.

[kcieplak]

I did not call this out earlier but it is interesting in that there are two symlinks one of which is correct and one that is not.
'SwiftDocCPluginUtilities' is invalid as it should be SYMLINKD

02/04/2026  09:03 AM    <SYMLINKD>     SharedPackagePluginExtensions [..\..\SharedPackagePluginExtensions]
02/04/2026  09:03 AM    <SYMLINK>      SwiftDocCPluginUtilities [..\..\..\Sources\SwiftDocCPluginUtilities]

The depth of the source in the symlink is different. Maybe there is some race condition where the underlying filesystem has not been populated yet at that depth, at the time the second symbolic link is created.

[becm]

@kcieplak since Git processes paths in lexical order, the described behavior should be expected and reproducable:

Plugins/SharedPackagePluginExtensions
Plugins/Swift-DocC Convert
Plugins/Swift-DocC Preview
Sources

The files below Sources are just not available yet when it's time to create the symlink files in Plugins/Swift-DocC *.