Design: submodule vs subtree vs fetchcontent

[Youw]

Originally this question was started by @ankurvdev:

@Youw
I'm wondering what your thoughts are on using subtree (https://www.atlassian.com/git/tutorials/git-subtree) for managing the repository rather than a submodule.

I don't have too much experience with subtree but I used it in a project and liked it.
It does require a little discipline to keep things simple (for eg: just based on my limited experience)

Forbidding local commits to upstream
Keeping the folder hierarchy same (commit history becomes harder to navigate since paths dont line up)
But in the end the experience for users and downstream projects would be quite neat.

Users wont have to worry about recursive submodule
The project layout here would be essentially same as libusb with the added file (CMakeLists.txt in the root)
we might even petition vcpkg (and rtlsdr) to switch to this repo for expanding support for libusb to more platforms

Let me extend this conversation to using one of the:

• git submodule;
• git subtree;
• CMake FetchContent;

git submodule

It is generally convenient/usable to use submodules by my experience, but it has at least one big drawback: git submodule support is not always present in the project's environment. And the fact that after git clone/pull you have to perform git submodule init/update and, possibly, --recursive is also a bit unconvenience.
There are other reasons why people can't or don't like using it and I generally understand those reasons.

git subtree

I'll only name one big plus of this aproach (in scope for libusb-cmake project): it would make a single solid repository.
But, there is "but"s:

1. Not everything as perfect as one might have thought:

The project layout here would be essentially same as libusb with the added file (CMakeLists.txt in the root)

git subtree can only be done in a sub-folder, ie it is not possible to have a git subtree in the root of the repo.

2. A history of a subtree might leak into the main project, i.e. when doing a subtree update with missing --squash. I don't believe git history of a subtree should be a part of the main project in our case and it is just an additional step/check a maintainer has to perform.

3. It is possible to commit into a subtree locally (in the context of a main project). Some may think that is a good thing (i.e. to to fix some small thing w/o needing to update the upstream), but I can imagine when it could go too far, may case further merge conflicts, and essentially - how different would it be from a fork?

4. "Random people from the internet" might simply confuse you with the upstream project and start opening bugs/issues/suggesting PRs that are unrelated to the main project.

I'd summarize all of those - it requires some level of discipline from the maintainer and contributors to make things nice long-term.

CMake FetchContent

For those who don't know what is it: https://cmake.org/cmake/help/latest/module/FetchContent.html

My biggest consern with it - it would fetch the upstream subproject at a CMake configuration time, i.e. it might be the issue for projects that practice something like "internet connection allowed only during the git clone stage" or so.
It is also harder to poke-around in the source code of the subproject locally during the main project development, if you need to (i.e. need to configure CMake/IDE to show the content of the fetched subfolder).

Beside those conserns, I'd say that I like this aproach the most.

---

I'd like to hear alternative opinions on this.

[Youw]

After giving it a good though, I think I'd rather go with the subtree solution.
The biggest downside is - more discipline required from the maintainer. Which I think I can live with.
Second biggest downside - it is not simple to use a different version of sources of upstream libusb than the one provided by libusb-cmake. But I think I can easily workaround that by making the LIBUSB_ROOT cmake variable optionally configurable.
Other than that - it is super friendly for most/straight-forward/intended usages.