<link rel="stylesheet" type="text/css" media="screen"  href="css/screen.css" />

<h1>Submodules</h1>

<h2>Creating Submodules</h2>

<p>This is the equivalent to SVN externals. <a href="http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html">Submodules are subdirectories of a Git project that point to another Git project</a>.</p>

<p>Starting in an existing Git repository, add a submodule.</p>

<pre><code>git submodule add git://somehost/someproject.git mysubproj
</code></pre>

<p>This will create a subfolder named <code>mysubproj</code> in the current directory and a new file called <code>.gitmodules</code> that contains mappings to the repositories.</p>

<p>Git tracks the submodule and the parent module separately. To change, update, or modify the submodule, <code>cd</code> into its directory.</p>

<p>Git helps the parent project precisely track the commit (not a symbolic <code>master</code> or <code>HEAD</code>) hash that the submodule is at for this parent project. This commit point can be different than another parent project that points to this submodule at a different commit point.</p>

<h2>Updating Submodule Pointers</h2>

<p>Start any submodule updating by executing <code>cd &lt;SUBMODULE&gt;</code> to navigate into the submodule directory.</p>

<p>If there's new code to be pulled, it can be retrieved via <code>git fetch</code>. There's no need to merge it into a branch as submodules are meant to represent a point in time and a hash (sans branch or tag name) is exactly that -- a point in time.</p>

<p>To visualize if all the new code has been retrieved, type <code>git log --all -5</code> top see the last five commits regardless if they are merged into any local branch. Copy the hash of the desired submodule snapshot.</p>

<p>Next, <code>git checkout &lt;HASH&gt;</code> to the desired commit.  The submodule's working directory now reflects the new snapshot state.</p>

<p>Lastly, <code>cd ..</code> back to the master repository hosing the submodule. The <code>git status</code> command will show that the subdirectory has been modified. <code>git add &lt;SUBMODULE&gt;</code> will add the submodule's update HASH pointer to the staging area. Git commit will seal it into the master repository.</p>

<h2>Restoring Submodules</h2>

<p>To check out a project and set up the submodules:</p>

<pre><code>git clone &lt;git://url/yourrepo.git&gt;
cd &lt;yourrepo&gt;
# Setup the submodule .gitmodules file
git submodule init
# Retrieve the submodules' code
git submodule update
</code></pre>

<p>If another developer changes the submodule, then commits the parent project and you pull and retrieve that, you'll need to update the submodules again to stop your <code>git status</code> from telling you the tree is dirty.</p>

<pre><code>git submodule update
</code></pre>

<p>The main concept is just to put the submodule in whatever state you want it to be in, then add and commit from the parent project. If a colleague does that and then you pull the parent project, you need to <code>update</code> to get the latest submodule code.</p>

<h2>Coding in Submodules</h2>

<p>Remember that submodule code changes need to be committed and pushed from within the submodule repository. In fact, it is better if submodule coding happens from a separate clone of the repository. If a submodule-coding developer fails to push updated code to the team-accessible host for the submodule code, her colleagues won't be able to retrieve the commits; the parent project will be pointing to a submodule hash that isn't publicly available.</p>