Sharing a sub-project and some users are git beginners?

Question

We have two teams, each using git, and would like to share a small project between them. Git submodules sounded like an obvious answer until I started searching and found lots of "submodules will bring you pain!" opinions out there. An answer to a related question here suggests git subtree, which seems to be baked in to some of our git clients but not others. I'm looking for a path forward.

More specifically: we have a dev team, a doc team, and a desire to add doc's examples to dev's test suite. We don't want to require doc to check out the whole dev tree (and there's a technical barrier anyway). We want both groups to be able to update the examples; for example, if a dev change is not backward-compatible, we want fixing the example to be part of the dev task and not technical debt. Both the doc build and the dev tests require the presence of the examples.

Members of the dev team are fluent in git. The doc team includes git beginners (though at least we have gotten them onto branches and off of master, finally). Dev is working on Linux (Ubuntu and RHEL) and doc is working on Windows using Tortoise Git (or in some cases the command line). It's ok if setting up a solution requires some work (I'm one of the more git-fluent doc-team members and this will be my responsibility), but we want using it to be straightforward for both groups. (If it's not, all those support requests will come to me.)

From what I've read, git subtree sounds like a viable option, but I can't tell if a repository can be a sub to two parents (doc and dev). How should I approach my sharing problem? Does git subtree do what we need, or is there something else we should do instead?

In case it matters, we're using our own server (with Bitbucket), not GitHub.

Answer 1

You will not find a completely satisfactory solution. Either approach will work, but submodules are likely to be the best approach in your scenario.

The asymmetry between the dev and doc teams is helpful here because in either case, the docs team can experience the documentation repository as a standalone repository. It is the dev team that will have to use some more complicated solution.

Git subtree lets you import a branch into a directory, and lets you export a directory as a branch. This feels like manually copying directory contents around, but automagically keeps the history of that directory intact. In the parent repository, a subtree does not feel special – because subtree is not a Git object, it is just a tool to splice and merge Git repositories. The repositories are not directly linked therefore the question whether a subtree can have “two parents” doesn't arise.

A Git submodule is just a reference to a commit in another repository. The repositories are linked but separate. This complicates some Git operations in the parent repository, e.g. changes to the submodule must be committed separately in the submodule repository (to commit the actual changes) and in the parent (to update the linked commit to the commit including our changes). You must also push the repositories separately.

The crucial difference between these approaches is that subtree includes the contents of a repository and submodule references another repository. This has consequences for the branching strategies you can use. Submodule makes it easy to switch the parent repository between different branches of the submodule, just like you can git checkout various branches.

You do not have this flexibility with subtree as the dev repository is not aware of the docs repository. That can also be an advantage because the devs will branch the code and the docs together. But in your case this will likely make cooperation with the docs team more difficult, e.g. when a dev wants to make a pull request for the documentation repository. With subtree they will first have to split of the docs directory as a new branch and then make the PR.

So neither approach offers seamless interaction. I'd recommend git-submodule because it is more flexible: here you want the devs to collaborate on the docs repository, not on a copy of the docs repository contents.