title: Git subrepositories
body: <p>I am a member of a small firmware team and we use a private Git server for version control. Our codebase typically has folders for platform specific code, common code used by multiple platforms and an SDK provided by the manufacturer of the microprocessor we develop on.</p>
  
  <p>Currently our repositories are centered around common code; each platform has a folder in the repository. This has at least two serious consequences;</p>
  
  <ol>
  <li><p>When we push changes for one platform it's visible for all other platforms which share the same common code. This clutters the commit history with releases for multiple platforms and in the past has led to confusion about which platform we're reviewing changes for.</p></li>
  <li><p>Changes to common code need to be verified for all platforms in the repository before they can be committed, causing unnecessary pain. (Somebody didn’t do this yesterday and made changes that caused a couple of our older platforms to fail to build. This particular repository has 5 platforms in it)</p></li>
  </ol>
  
  <p>I'm pushing to have a repository for each platform so we can make changes to common code and upgrade the SDK periodically without being forced to update and verify <em>all</em> of the platforms we're supporting. Since we're a five person team and these problems typically rear up during the crunch-time leading up to a release this would save us a ton of unnecessary brain damage and time. Naturally the hard part is in the implementation.</p>
  
  <p>Right now I'm imagining a system where each platform has its own repository, each common code base has its own repository and each of the SDKs we use have their own repository. The platform repositories would link to or otherwise reference the common code and SDK they use as "sub-repositories."</p>
  
  <p>I've read about submodules but I think they would cause more issues than they would fix; recently we had to debug three year old firmware, which required resetting our local codebase to the problem release to do static analysis. As I understand the local version of the submodule is detached from the repository in which it resides, which means resetting the repository to an old commit will leave the submodule in the "future" with respect to the rest of the repository. In the context of debugging old code this behavior is 100% unacceptable.</p>
  
  <p>Here's a bulleted list of what I want to achieve; (in order of importance)</p>
  
  <ol>
  <li><p>Break platform specific code away from common code so changes to common code and/or the SDK don't have unforeseen consequences on other platforms.</p></li>
  <li><p>Create new repositories for each platform, each common code base and each SDK.</p></li>
  <li><p>Cloning a remote repository to a local machine should be a one step process; new users should not be forced to pull each sub-repository before the platform will build.</p>
  
  <ul>
  <li><p>In addition; restoring old code, including the common code and SDK that was used to build version XXX-YYY of any given platform, <strong>must</strong> be possible.</p></li>
  <li><p><strong>Edit:</strong> The last time I had to "restore" code I used a hard reset to the build I was debugging and a soft reset to a build a year older than it that I knew was good, but only so the Git plugin in my syntax highlighter would display changes between the known-good and known-bad for me.</p>
  
  <p>Incidentally this particular platform is monolithic and this question does not apply to it, but for the sake of argument we'll say it does apply.</p></li>
  </ul></li>
  <li><p>Modifying the common code should not effect the platforms until the maintainer of the platform pulls in the new common code. (I believe this is possible with subtrees by adding one of the common code's tagged commits instead of the common code's master)</p></li>
  <li><p>A read-only sub-repository is an acceptable limitation. (i.e. the sub-repository either cannot be modified in the platform's repository or changes to the sub-repository cannot be pushed from the platform's repository)</p></li>
  <li><p>SmartGit/HG support is desirable as all but one of our members uses it.</p></li>
  <li><p>Scripting one-time tasks is acceptable, but I don't want to pollute platforms with scripts that do Git's job for it.</p></li>
  </ol>
  
  <p>I've also read about subtrees but at this moment I'm unsure of whether they would intuitively permit the behavior I desire. My main question is this: does Git support this kind of functionality? If yes, is that functionality implemented by subtrees or by another method I am not yet aware of?</p>