/workbook/htmls/24-Submodules.html

 1<link rel="stylesheet" type="text/css" media="screen"  href="css/screen.css" />
 2
 3<h1>Submodules</h1>
 4
 5<h2>Creating Submodules</h2>
 6
 7<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>
 8
 9<p>Starting in an existing Git repository, add a submodule.</p>
10
11<pre><code>git submodule add git://somehost/someproject.git mysubproj
12</code></pre>
13
14<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>
15
16<p>Git tracks the submodule and the parent module separately. To change, update, or modify the submodule, <code>cd</code> into its directory.</p>
17
18<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>
19
20<h2>Updating Submodule Pointers</h2>
21
22<p>Start any submodule updating by executing <code>cd &lt;SUBMODULE&gt;</code> to navigate into the submodule directory.</p>
23
24<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>
25
26<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>
27
28<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>
29
30<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>
31
32<h2>Restoring Submodules</h2>
33
34<p>To check out a project and set up the submodules:</p>
35
36<pre><code>git clone &lt;git://url/yourrepo.git&gt;
37cd &lt;yourrepo&gt;
38# Setup the submodule .gitmodules file
39git submodule init
40# Retrieve the submodules' code
41git submodule update
42</code></pre>
43
44<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>
45
46<pre><code>git submodule update
47</code></pre>
48
49<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>
50
51<h2>Coding in Submodules</h2>
52
53<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>