Introduction

Git understands symbolic links as a repository object type, but Windows support depends on both the filesystem and the local machine configuration. That means a symlink committed on one machine may check out as a real symbolic link on one Windows system and as a plain text file containing the target path on another.

How Git Stores Symlinks

In Git, a symlink is not stored as a copy of the target file. Git stores:

• a special file mode for symlink entries
• the target path as the blob contents

On Unix-like systems, checkout usually recreates the symlink directly. On Windows, checkout behavior depends on whether the environment actually supports creating symlinks.

Why Windows Is Different

Windows can support symbolic links, but historically creation required elevated privileges. On newer systems, Developer Mode makes symlink creation easier for normal development workflows.

The important practical variables are:

• NTFS filesystem support
• whether the user can create symlinks
• whether Git believes symlinks are supported in that working tree

If those conditions are not met, Git may fall back to checking out a regular file that contains the link target as plain text.

The core.symlinks Setting

Git uses core.symlinks to decide whether to checkout symlinks as real symlinks.

Check the current value:

git config --get core.symlinks

Enable it for the repository if the machine is ready to support symlinks:

git config core.symlinks true

This setting matters most when the repository is created or cloned on Windows, because Git probes the filesystem capability and may set behavior accordingly.

Creating a Symlink on Windows

From Command Prompt, a file symlink can be created with mklink.

mklink link.txt target.txt

For directories:

mklink /D linkdir targetdir

After creating the link, Git will see the symlink entry if symlink support is active.

git add link.txt
git commit -m "Add symlink"

If core.symlinks is disabled or the OS refuses symlink creation, the result will not behave the same way.

Developer Mode Helps a Lot

On modern Windows versions, enabling Developer Mode is often the easiest way to make symlink workflows usable without running every shell as Administrator.

Once Developer Mode is on, tools such as Git Bash, Command Prompt, or PowerShell are much more likely to create and checkout symlinks successfully under normal user accounts.

Without it, many developers run into inconsistent behavior where the repository technically contains symlinks but local checkout does not reproduce them correctly.

Cross-Platform Repositories Need Care

A repository shared across macOS, Linux, and Windows can use symlinks successfully, but only if the Windows contributors have working symlink support. Otherwise, they may see broken builds or odd text files where links were expected.

This is why symlink-heavy repositories should document the Windows prerequisites clearly.

A small diagnostic command:

git ls-files -s

A symlink entry typically appears with mode 120000, which confirms that Git has recorded it as a link in the index.

When Symlinks Are a Bad Idea on Windows

Sometimes the right answer is to avoid symlinks entirely in a Windows-heavy workflow. This is especially true when:

• contributors have locked-down corporate machines
• build tools do not handle symlinks consistently
• the repository is consumed by software that expects normal files only

In those cases, duplication, generated files, or a different project layout may be more reliable than fighting the platform.

Common Pitfalls

A common mistake is assuming Git symlink support is purely a Git feature. On Windows, the OS and permissions matter just as much.

Another issue is forgetting core.symlinks. If it is disabled, checkout behavior may look wrong even when the repository stores the symlink correctly.

Developers also sometimes create a Windows shortcut and expect Git to treat it like a symlink. A shortcut file is not the same thing.

Finally, do not assume that because a symlink works on one teammate's Windows machine it will work on all Windows machines. Developer Mode, privileges, and filesystem configuration can differ.

Summary

• Git stores symlinks as special entries whose contents are the target path.
• On Windows, real checkout support depends on OS capability and permissions.
• 'core.symlinks controls whether Git recreates links as symlinks in the working tree.'
• Developer Mode makes symlink workflows much easier on modern Windows.
• For cross-platform repositories, document Windows symlink requirements clearly.