Git Submodules

NOTE: This document is now deprecated. iOS was the only discipline using submodules, and is now switching to CocoaPods for future projects.

This document will remain available for the purposes of maintaining older projects.

Submodules allow foreign repositories to be embedded within a dedicated subdirectory of the source tree, always pointed at a particular commit.
-- git-submodule(1) Manual Page

Basic Usage

This example uses AFNetworking as a Git submodule for the project.

Cloning Repos with Submodules

$ git clone --recursive <url>

Adding Submodules

In the main repo working directory:

$ mkdir Lib
$ git submodule add https://github.com/vokal/AFNetworking.git Lib/AFNetworking

Then commit the change.

Notes:

iOS projects should add submodules into the Lib subdirectory.
Web projects should use bower instead
Use https access for GitHub. This makes updating the build server much easier.
Submodules should be Vokal repositories, as explained in Working With Frameworks.
When in doubt ask someone!

##Removing Submodules
Removing submodules is a manual process, frought with terror.

Delete the relevant section from the .gitmodules file. It will look similar to this:

 [submodule "Lib/AFNetworking"]
         path = Lib/AFNetworking
         url = https://github.com/vokal/AFNetworking.git

Delete the relevant section from the .git/config file. It will look similar to this:

 [submodule "Lib/AFNetworking"]
     url = https://github.com/vokal/AFNetworking.git

Remove the directory from git's tracking. git rm --cached Lib/path/to/submodule (no trailing slash).
Commit your changes.
Delete the now untracked submodule files. rm -rf Lib/path/to/submodule

Updating Submodules

In the main repo working directory:

$ git submodule update --init --recursive

Changing Repo Addresses For Submodules

If you need to change the repo address for a submodule (for instance, if you initially cloned your submodule directly from a vendor repo instead of the Vokal fork), follow these steps:

Delete your entire local repository. All the git files, all the project files. Everything. Nuke it from orbit, it's the only way to be sure.
Go to your fork of the project repository on GitHub, and find the portion of the .gitsubmodules file where you are pointing at the incorrect repo (in this example, pointed directly at a Square repo):
```
 [submodule "Cyfr-iOS/Utilities/Vendor/SocketRocket"]
      path = Cyfr-iOS/Utilities/Vendor/SocketRocket
      url = https://github.com/square/SocketRocket.git
```

Using the Edit button on GitHub, update the url to point to Vokal's fork of the submodule's repo:

  [submodule "Cyfr-iOS/Utilities/Vendor/SocketRocket"]
     path = Cyfr-iOS/Utilities/Vendor/SocketRocket
     url = https://github.com/vokal/SocketRocket.git

Clone your updated repo from GitHub. The submodule will now be pointed at the Vokal fork.

Vokal Engineering

Quality, Integrity, and Efficiency.