Cheat Sheet for Git submodules

git-submodule-cheatsheet.md

Git Submodule Cheatsheet

Think about Git submodules as managing nested repositories. You have an outer (parent) repository and one or more inner (child) repositories. The child repositories are called submodules. When you register the child repository as a submodule with the parent repository, it will register the presence of the submodule in a .gitmodules file.

Creating a Submodule

This section explains how to create an register a new submodule in your parent repository.

Create your outer repository and make at least one commit:

mkdir parent-repo
cd parent-repo
git init
touch README.md
git add .
git commit -m "initial commit"

From inside the parent repository, create a child repository and add at least one commit:

# from parent-repo directory
mkdir child-repo
cd child-repo
git init
touch README.md
git commit -m "initial commit"

Now we have one repository inside of another. Next, you'll want to register the inner repository as a submodule.

# from parent-repo directory
git submodule add ./child-repo

This command created the .gitmodules file and staged the changes. At this point you can commit the changes to the parent repository. There will be a single file representing the submodule that you've added.

Cloning a Repo with Submodules

If you were to push the parent-repo to a remote, you have the ability to clone this repo along with any submodules. If you do a normal git clone command, you'll need to manually synchronize and download the submodule with another set of commands. If you would like to clone the parent repo and all submodules, use the following:

git clone --recurse-submodules [url]

If you did not use --recurse-submodules, you can use the following commands to pull in the submodule content:

git submodule init
git submodule update

• git submodule init initializes the submodules, which copies information from .gitmodules to the .git/config file.
• git submodule update actually clones the submodule repositories and checks out the appropriate commits. This is the step that pulls the actual content from the submodule remotes.

Command Summary

• git submodule add [url] [path]: Add a new submodule to your project.
• git submodule init: Initialize your submodule.
• git submodule update: Fetch all the data from the submodule project.
• git submodule status: Show the status of your submodule.
• git submodule foreach [command]: Use this to run a command in each submodule.
• git submodule sync: Synchronize submodules' remote URL configuration setting.
• git submodule deinit [path]: Remove a submodule from your project.
• git submodule update --remote [path]: Update a submodule to the latest commit.
• git clone --recurse-submodules [url]: Clone a project with all submodules.