I believe that the discussion in #506 concluded that you should use symlinks instead of a submodule. I don't think you want to put the entire GUT repo into your project (all the tests and documentation) so using it as a submodule isn't a good fit. To use GUT with a symlink you should clone the repo to somewhere outside your project and symlink addons/gut to each project.

I think the documentation should probably just mention symlinks as an approach for managing plugin code (in general). It isn't specific to GUT and I'm not sure I want to maintain documentation explaining symlinks. I can't ever remember if Windows has real symlinks yet and if they do, what the differences are or if you can just make normal symlinks now using the WSL.

The downside to this approach is that it could get messy if you have multiple projects using different versions of GUT. It doesn't seem like you would need to manage more than two versions of GUT at a time (Godot 3.x and 4.x).

Thoughts?

Ah, that's a misunderstanding on my part then. I had thought using a submodule in conjunction with a symlink was the most attractive option because you wouldn't have to do any extra copying after cloning the project, and I didn't really see any downsides to this as the GUT repo takes up very little storage (in my eyes, at least). I can certainly see why you'd want the documentation not to spend too much time explaining symlinks in depth though.

Are these the sort of docs you were looking for in your last comment in #506 then?

I've not used submodules much, but is there a benefit to having GUT cloned as a submodule if it does not reside in the same directory as the project? I was thinking that you would either use a submodule if you could, or do the symlink approach, but not both.

If that makes ense, then I think the help should say something like:

The GUT repo is not organized to be used as a Git submodule. You can achieve a similar effect if you clone the GUT repo and symlink addons/gut/ into each project you wish to install GUT into.

I believe submodules necessarily exist in the same directory as the main project since the point of submodules is to "allow you to keep a Git repository as a subdirectory of another Git repository" (git-scm). That's why adding a symlink is currently required if you want to use GUT as a submodule - if it's a submodule it will be in a subdirectory, and any paths in GUT ("res://addons/gut/...") won't be valid anymore unless you make a certain symlink. You wouldn't use either a submodule or a symlink - you'd need both. The two options are cloning GUT separately from your repository and symlinking it in, or adding GUT as a submodule to your repository and symlinking it in.

It doesn't make sense to me to say that

You can achieve a similar effect if you clone the GUT repo and symlink...

because this doesn't achieve two certain effects that a submodule would. First, this approach would not allow the superproject's git repo to record what version/commit of GUT the superproject was using. Second, this would not allow a user to clone the superproject and its GUT dependency in a single command - they would have to manually/separately clone GUT and manually write a symlink. With submodules, when you clone the superproject, it will also bring a copy of GUT with it with the symlink already created. It makes more sense to me to word it like this then:

GUT's file structure is not organized to be used as a Git submodule. You can work around this and still use GUT as a submodule by symlinking addons/gut into the addons directory of your project. You could also clone GUT separately from your project and create the same symlink if you are not interested in Git submodules.

This is the part I was missing.

Second, this would not allow a user to clone the superproject and its GUT dependency in a single command

I can see how having all your dependencies as submodules would be useful but I have a hard time recommending having the entire GUT Repo inside your project. It just feels wrong...it's hundreds extra files. What we really need is dependency handling for the asset library. It looks like its in the works and there is also a plugin created for it but nothing official has been created yet.

• Add dependency handling and enable users to organize and publish addons and addon-collections as packages godotengine/godot-proposals#142
• https://github.com/chickensoft-games/GodotEnv/

I guess the help should state:

If you would like to have GUT as a git-submodule of your project you could:
* Add GUT as a submodule at `wherever/gut/`
* Symlink `wherever/gut/addons/gut` to `addons/gut`
This will include the entire GUT repository including all of its documentation and tests but it works.  It might be better to keep GUT outside your project and symlink it from there instead.

Gotcha. I've basically copied that last example statement you gave and added a single line notice that if you decide to symlink to GUT outside your project, anyone who clones it must have GUT in the same location on their device for the symlink to work, because that seems like an important thing to keep in mind (I can also remove this notice if you think it is unnecessary). Would this satisfy your original call for documentation in #506?

## Installing from this repository
GUT's file structure is not organized to be used as a Git submodule.  If you would like to have GUT as a submodule of your project you could:
1. Add GUT as a submodule at `<path to gut>/gut`
1. Symlink `<path to gut>/gut/addons/gut` to `addons/gut`

This will clone the entire GUT repository, including all of its documentation and tests (which are unnecessary).  It may be better to clone GUT outside your project and symlink to it from there instead (contributors must all have a copy of GUT at the same location for the symlink to work).