Documentation 2.0: Describe symlinks

[insspb]

Symlinks can make unexpected things with templates developers and templates users.

So symlinks behaviour should be deeply described and actual defaults should be selected.

Issues and PRs that should be reworked and merged or at least considered:

• Copy symlinks as symlinks when supported by the platform #982 Copy symlinks as symlinks when supported by the platform
• Symlinks become normal directories when cookiecutter is run #865 Symlinks become normal directories when cookiecutter is run
• Add support for symlinks #934 Add support for symlinks on posix systems
• Don't dereference symlinks when using copytree #929 Don't dereference symlinks when using copytree
• Add support for symlinks in cookiecutter templates #868 Add support for symlinks in cookiecutter templates

[dbzm]

I have to confess I'm somewhat confused as to the "intended" behavior of symlinks. I see people saying that they don't want them dereferenced when the repo is stamped, which makes sense.

At the same time, however, without symlinks directories become a whole lot less useful. They're called out in that part of the documentation:

This allows using symlinks for general files.

What is the plan for them going forward?

[samschott]

To chime in on this, I think there are many project structures, especially targeting Unix-like systems, where symlinks play an essential role and should be copied as-is instead of followed. One example are macOS Frameworks which rely on symlinks in their folder structure.

I've just looked through the docs and can see how symlinks are useful to refer to the same file in multiple templates. However, when there is a choice between convenience in setting up the templates (by following symlinks) and not being able to generate a certain type of project at all (projects containing symlinks, relative or absolute), I would probably prefer the versatility in types of projects that can be created.

A good compromise probably is to have a flag / option. My intuition would say that such a flag should default to copying symlinks as-is. But maybe there is an active user base that relies on resolving symlinks...

[seanh]

Please don't change the current behavior of following symlinks, at least not without an option to restore the current behavior.. As noted by @dbzm it has been advertised as a feature in the docs. Changing cookiecutter to copy symlinks as symlinks would break our cookiecutters which rely heavily on the current behavior.

Cookiecutters that want to have actual symlinks in the generated project can easily do that with a post-generate hook:

# hooks/post_gen_project.sh
ln -s one two
ln -s three four

On the other hand if cookiecutter is changed to copy symlinks as symlinks then people who want to share template files between multiple cookiecutters will no longer have an easy solution.

[mforbes]

@seanh I agree that there should be a flag that allows the current behaviour to be maintained (probably by default), but it would be really nice if there was some way for template manager to be able to use symlinks as symlinks where they make sense. As I discuss in #865 (comment), I can almost do this now with a post-generate hook, but this requres hard-coding them in the hook (or in the template). Can someone more knowledgable comment if there might be some way to use a pre-generate hook to detect these and pass the information along to cookiecutter so they can be generated by the post-generate hook? (Or tell me if this is not easily doable because there is no way to scan the original template first if running on a platform that does not support symlinks, etc.)

An alternative might be to only preserve in-tree symlinks, but this is clever/tricky and would probably be a pain to maintain.