core.symlinks configuration without automatic fallback in restricted environments

Answer to the Core Question

Git does not automatically fall back to plain files when a symlink cannot be created. If core.symlinks is true and the process lacks the necessary privileges, the checkout will abort or leave the working tree incomplete. To guarantee identical checkouts across developer workstations and production servers that cannot create symlinks, you must disable symlink creation explicitly.

Recommended Workflow

1. Set core.symlinks to false on every host that cannot create symlinks. This can be done globally or per‑repository.
   • Global: git config --global core.symlinks false
   • Repository: git config --local core.symlinks false (writes to .git/config)
2. Clone the repository fresh. After setting the option, run git clone . Symlink entries in the commit will be checked out as ordinary files containing the target path.
3. Optional conversion on privileged hosts. If a host can create symlinks and you want them, add a post-checkout hook that turns plain‑text symlink files into real symlinks.

Repository‑Level Override

Running git config --local core.symlinks false inside the repository writes the setting to .git/config. This file is part of the repository’s metadata and will be shipped to any clone, so all users on that machine will inherit the non‑symlink behavior without requiring privileged access. It does not affect users who clone the repo on machines that can create symlinks unless they override locally.

Important Caveats

• Disabling core.symlinks on a system that supports symlinks will break tools that rely on real symlinks. Use this setting only on restricted hosts.
• Changing the setting after a repository has been cloned can leave the working tree in an inconsistent state; a fresh clone is recommended.
• Repository‑level settings apply only to the local clone; they do not change the commit history or the way the repository is stored on Git servers.

Assumptions & Verification

These recommendations assume Git 2.30+ and a standard POSIX or Windows environment. Verify by running:

git config --local core.symlinks
# Should output "false"

After cloning, check a symlink entry:

git ls-tree HEAD | grep symlink
# Should show a blob entry, not a gitlink

Missing Detail Prompt

To tailor the hook conversion step precisely, what is the exact pattern used for symlink target files (e.g., file extension or naming convention) in your repository?