Symlinks stored in the repository cannot be overwritten without --force

[Flashmueller]

Hello,

I'm experiencing issues with the symlinks generated by Gitman in my repository. My current understanding is that these symlinks should not be committed to the repository because doing so requires future gitman install commands to use the --force flag. However, I couldn't find any specific guidance on this in the documentation.

These symlinks are not ignored by default, which leads me to wonder if I might be misunderstanding how they should be managed. One approach I'm considering is adding the symlinks to the .git/info/exclude file to prevent them from being tracked. Has anyone tried this method, or perhaps addressed this issue through a script?

I would appreciate any insights or recommendations on best practices for handling these symlinks.

Thank you!

PS: im on Windonws

[jacebrowning]

doing so requires future gitman install commands to use the --force flag

Is that the case? I don't think that's expected but perhaps this is a Windows quirk that needs a workaround.

[Flashmueller]

When I initially clone the repository and run gitman install for the first time, I can uninstall and reinstall dependencies without needing the --force flag, and everything works fine. The symlinks are not deleted during the uninstall and become functional again after a fresh gitman install.

However, after committing the symlinks and cloning the repository again, I cannot install without using --force. During installation, I receive the following error message: Preexisting link location at C:\Git_Repos\plcdevproject_test\src\PrimaryPlc\Logical\Libraries\BurDefaultLibraries Run again with --force/--force-interactive to discard changes or '--skip-changes' to skip this dependency

After using --force for the initial installation in the fresh clone including symlinks, I can uninstall and reinstall safely without the --force flag. Git shows no differences after the symlinks have been "repaired" via the forced install. It seems that after a fresh clone, the symlink appears as a plain text file containing the relative path it points to. Adding core.symlinks true to my global .gitconfig does not change this behavior.

To work around this issue, I have decided not to commit the symlinks to the repository. Instead, I add them to .git/info/exclude using the following commands:

mkdir -p .git/info
touch .git/info/exclude
git ls-files -o --exclude-standard > /tmp/unstaged_files
cat /tmp/unstaged_files >> .git/info/exclude
rm /tmp/unstaged_files

[jacebrowning]

I don't know enough about how Windows stores symlinks on the filesystem, but ignoring them and letting Gitman create them each time seems reasonable to me. If someone with more Windows development experience wants to try to make this work without needed the --force option I would be open to a pull request.

[Flashmueller]

Hi,

I've done further investigation into using symlinks in Git repositories on Windows and have some good news! Summary: Gitman works as intended on Windows when both Git and Windows settings are configured correctly.

Key Points:

1. Symlinks must be enabled either during the Git installation or later through the global gitconfig file.
2. The user must have permission to create symlinks:
   • Enable Developer Mode in Windows, or
   • Grant permission via Group Policy.

For more detailed information, this thread is a great starting point: Git symbolic links in Windows

It's also worth mentioning that Windows distinguishes between file and directory symlinks. Git cannot handle this distinction without some assistance, so the symlink type needs to be defined in the .gitattributes file. For more details, you can refer to this StackOverflow discussion.

[jacebrowning]

That's great news. Thanks for the research!

Perhaps there could be an additional section explaining this in the documentation?

https://github.com/jacebrowning/gitman/blob/main/docs/setup/git.md

[Flashmueller]

Absolutely. Will make a PR within the next days/weeks.