Let's say I have a project that has multiple components: a server component, a web app component, an iOS component, an Android component, etc. These components are all separate codebases, but are also loosely coupled (eg. a change to the server code could require a change to all other components too)

What is the most efficient way in Git to organize this project? If you put it all in one repository, you would always have the latest versions but things become quite messy when you start changing one component and not the others.

On the other hand, if you make each component as a separate repository, how would you be able to "link" these repositories so that you would know that version 2.0 of the app requires version 1.5 of the server component, etc?

Is there a feature in git outside of keeping up to date readmes(or some better solution I don't see) to more effectively manage multiple, related repos?

  • Do these components actually depend on each other, like a the relationship between a releasable component and a library? Or are you just trying to keep all your releasable components in sync?
    – Useless
    Oct 8, 2014 at 18:33
  • Here's an older discussion on StackOverflow (miraculously not closed yet). Aug 18, 2015 at 16:46

3 Answers 3


Sub-projects is the place were distributed version control systems (DVCS) start to, if not unravel, certainly become a little wonky.

Git submodules and Mercurial subrepositories both aim for sub-project support. Both have improved release-by-release (to the point that Mercurial's old "this feature exists, but you probably shouldn't use it" warning is no longer front-and-center.)

Still, multi-project repos remain more of a speciality use case rather than an everyone-uses-it feature. The documentation contain numerous caveats and "how to use this" instructions that make clear that managing "projects of projects" is a two-level concern, with the meta management slightly but genuinely different than the direct, single-level project management. As a result, there is much less experience out there. And there is no shortage of "don't use git submodules!" and "avoid mercurial subrepos!" comments and blog posts.

My own experience with subrepos was mixed. It worked...but it was also annoying. I love the idea of sub-projects, but in practice find the alternatives--either large all-in-one repos or companion sibling projects--to be more easily wrangled (though less elegant). I look forward to the day subrepos are mainstream and not a pain, but I haven't experienced that yet.

This isn't to say that managing submodules/subrepos won't work for you, but it's something that should be done with care, and definitely some prior experimentation and planning.

Given that you're focused on Git, you should also explore Git subtrees, which some find to be a better alternative to git submodules.

  • 1
    Revisiting in 2016: Hg docs still call subrepos a feature of last resort. Git docs are more enthusiastic, and its submodule feature is now more integrated. Both also now handle nested repos well (recognizing the nested repo "has the ball" with files it's managing), giving another useful sub-repo option. But DVCS tools still major on single-level repos, so "sub-repos => multiple level management" and "dragons be here" warnings remain relevant. Nov 21, 2016 at 18:48

If you use C#, you can use NuGet.

Make each component a library and keep them in their own repository. Make releases of the basic components that you version according to semantic versioning.

Finally, get your buildserver to package the libraries into NuGet packages, and consume those NuGet packages in the projects for the front-end components (iOS, Android).

The same basic approach (version and package dependencies) can be used in other languages as well, but might not be as convenient.

I would not recommend you to use Git Submodules. While it can be used for these kind of issues in theory, I feel it's a bigger hassle than it's worth.


In my opinion, this would depend on how much they are actually coupled. It is really nice to be able to run an automated git bisect when tracking down a regression, but this will be difficult to do if every commit depends on a different version of your other dependencies to run.

Two possible options would be one repository with submodules or multiple repositories with good versioning practices in place.

how would you be able to "link" these repositories so that you would know that version 2.0 of the app requires version 1.5 of the server component, etc?

This is usually the domain of some dependency management framework (e.g. Gradle, Maven), not Git itself.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.