Fun with git submodules

Git submodules are amazingly useful. Because they provide a way for you to connect external, separate git repositories they can be used to organize your vim scripts, your dotfiles, or even a whole mediawiki deployment.

As incredibly useful as git submodules are, they can also be a bit confusing to use. This goal of this article is to walk you through the most common git submodule tasks: adding, removing and updating. We’ll also review briefly how to make changes to code you have checked out as a submodule.

I’ve created some practice repositories. Fork submodule-practice if you’d like to follow along. We’ll used these test repositories as submodules:

I’ve used version 2.3.0 of the git client for these examples. If you’re seeing something different, check your version with git --version.

Initializing a repository with submodules

First, let’s clone our practice repository:

[skade ;) ~/Work] 
christie$ git clone git@github.com:christi3k/submodule-practice.git
Cloning into 'submodule-practice'...
remote: Counting objects: 63, done.
remote: Compressing objects: 100% (16/16), done.
remote: Total 63 (delta 9), reused 0 (delta 0), pack-reused 47
Receiving objects: 100% (63/63), 6.99 KiB | 0 bytes/s, done.
Resolving deltas: 100% (25/25), done.
Checking connectivity... done.

And then cd into the working directory:

christie$ cd submodule-practice/

Currently, this project has two submodules: furry-octo-nemesis and psychic-avenger.

When we run ls we see directories for these submodules:

[skade ;) ~/Work/submodule-practice (master)] 
christie$ ll
▕ drwxrwxr-x▏christie:christie│4  min │   4K│furry-octo-nemesis
▕ drwxrwxr-x▏christie:christie│4  min │   4K│psychic-avenger
▕ -rw-rw-r--▏christie:christie│4  min │  29B│README.md
▕ -rw-rw-r--▏christie:christie│4  min │ 110B│README.mediawiki

But if we run ls for either submodule directory we see they are empty. This is because the submodules have not yet been initialized or updated.

[skade ;) ~/Work/submodule-practice (master)] 
christie$ git submodule init
Submodule 'furry-octo-nemesis' (git@github.com:christi3k/furry-octo-nemesis.git) registered for path 'furry-octo-nemesis'
Submodule 'psychic-avenger' (git@github.com:christi3k/psychic-avenger.git) registered for path 'psychic-avenger'

git submodule init copies the submodule names, urls and other details from .gitmodules to .git/config, which is where git looks for config details it should apply to your working copy.

git submodule init does not update or otherwise alter information in .git/config. If you have changed .gitmodules for any submodule already initialized, you’ll need to deinit and init the submodule again for changes to be reflected in .git/config.

You can initialize specific submodules by specifying their name:

git submodule init psychich-avenger

At this point you could customized git submodule urls for use in your local checkout by editing them in .git/config before proceeding to git submodule update.

Now let’s actually checkout the submodules with submodule update:

skade ;) ~/Work/submodule-practice (master)] 
christie$ git submodule update --recursive
Cloning into 'furry-octo-nemesis'...
remote: Counting objects: 6, done.
remote: Total 6 (delta 0), reused 0 (delta 0), pack-reused 6
Receiving objects: 100% (6/6), done.
Checking connectivity... done.
Submodule path 'furry-octo-nemesis': checked out '1c4b231fa0bcfd5ce8b8a2773c6616689032d353'
Cloning into 'psychic-avenger'...
remote: Counting objects: 25, done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 25 (delta 1), reused 0 (delta 0), pack-reused 15
Receiving objects: 100% (25/25), done.
Resolving deltas: 100% (3/3), done.
Checking connectivity... done.
Submodule path 'psychic-avenger': checked out '169c5c56154f58fd745352c4f30aa0d4a1d7a88e'

Note: The --recursive flag tells git to recurse into submodule directories and run update on any submodules those submodules include. It’s not needed for this example, but I’ve included it here anyway since it’s common for projects to have nested submodules.

Now when we run ls on either directory, we see they now contain our submodule’s files:

[skade ;) ~/Work/submodule-practice (master)] 
christie$ ls furry-octo-nemesis/
▕ -rw-rw-r--▏42 sec │  52B│README.md

[skade ;) ~/Work/submodule-practice (master)] 
christie$ ls psychic-avenger/
▕ -rw-rw-r--▏46 sec │ 133B│README.md
▕ -rw-rw-r--▏46 sec │   0B│other.txt

Note: It’s possible to run init and update in one command with git submodule update --init --recursive

Adding a git submodule

We’ll start in the working directory of submodule-practice.

To add a submodule, use:

git submodule add <git-url>

Let’s try adding sample project scaling-octo-wallhack as a submodule.

[2495][skade ;) ~/Work/submodule-practice (master)] 
christie$ git submodule add git@github.com:christi3k/scaling-octo-wallhack.git
Cloning into 'scaling-octo-wallhack'...
remote: Counting objects: 19, done.
remote: Compressing objects: 100% (8/8), done.
remote: Total 19 (delta 1), reused 0 (delta 0), pack-reused 9
Receiving objects: 100% (19/19), done.
Resolving deltas: 100% (3/3), done.
Checking connectivity... done.

Note: If you want the submodule to be cloned into a directory other than ‘scaling-octo-wallhack’ then you need to specify a directory to clone into as you would when cloning any other project. For example, this command will clone psychic-avenger to the subdirectory submodules:

christie$ git submodule add git@github.com:christi3k/scaling-octo-wallhack.git submodules/scaling-octo-wallhack

Let’s see what git status tells us:

[skade ;) ~/Work/submodule-practice (master +)] 
christie$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

	modified:   .gitmodules
	new file:   scaling-octo-wallhack

And running ls we see that there are files in scaling-octo-wallhack directory:

[skade ;) ~/Work/submodule-practice (master +)] 
christie$ ll scaling-octo-wallhack/
▕ -rw-rw-r--▏christie:christie│<  min │ 180B│README.md
▕ -rw-rw-r--▏christie:christie│<  min │   0B│cutting-edge-changes.txt
▕ -rw-rw-r--▏christie:christie│<  min │   0B│file1.txt
▕ -rw-rw-r--▏christie:christie│<  min │   0B│file2.txt

Specifying a branch

When you add a git submodule, git makes some assumptions for you. It sets up a remote repository to the submodule called ‘origin’ and it checksout the ‘master’ branch for you. In many cases you may no want to use the master branch. Luckily, this is easy to change.

There are two methods to specific which branch of the submodule should be checked out by your project.

Method 1: Specify a branch in .gitmodules

Here’s what the modified section of .gitmodules looks like for scaling-octo-wallhack:

[submodule "scaling-octo-wallhack"]
  path = scaling-octo-wallhack
  url = git@github.com:christi3k/scaling-octo-wallhack.git
  branch  = REL_1

Be sure to save .gitmodules and then run git submodule update --remote:

[skade ;( ~/Work/submodule-practice (master *+)] 
christie$ git submodule update --remote
Submodule path 'psychic-avenger': checked out 'fba086dbb321109e5cd2d9d1bc3b59478dacf6ee'
Submodule path 'scaling-octo-wallhack': checked out '88d66d5ecc58d2ab82fec4fea06ffbfd2c55fd7d'

Method 2: Checkout specific branch in submodule directory

In the submodule directory, checkout the branch you want with git checkout origin/branch-name:

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack ((b49591a...))] 
christie$ git checkout origin/REL_1
Previous HEAD position was b49591a... Cutting-edge changes.
HEAD is now at 88d66d5... Prep Release 1.

Either method will result will yield the following from git status:

[skade ;) ~/Work/submodule-practice (master *+)] 
christie$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

	modified:   .gitmodules
	new file:   scaling-octo-wallhack

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   scaling-octo-wallhack (new commits)

Now let’s stage and commit the changes:

[skade ;) ~/Work/submodule-practice (master *+)] 
christie$ git add scaling-octo-wallhack

[skade ;) ~/Work/submodule-practice (master +)] 
christie$ git commit -m "Add scaling-octo-wallhack submodule, REL_1."
[master 4a97a6f] Add scaling-octo-wallhack submodule, REL_1.
 2 files changed, 4 insertions(+)
 create mode 160000 scaling-octo-wallhack

And don’t forget to push them to our remote repository so they are available for others:

[skade ;) ~/Work/submodule-practice (master)] 
christie$ git push -n origin master 
To git@github.com:christi3k/submodule-practice.git
   7e6d09e..4a97a6f  master -> master

(Note the -n flag means ‘dry run’, that is ‘do everything except actually send the updates.’ I recommend using this when available with commands that have potentially destructive results, including push and merge.)

Looks good, do it for real now:

[skade ;) ~/Work/submodule-practice (master)] 
christie$ git push origin master 
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 439 bytes | 0 bytes/s, done.
Total 3 (delta 2), reused 0 (delta 0)
To git@github.com:christi3k/submodule-practice.git
   7e6d09e..4a97a6f  master -> master

Removing a git submodule

Removing a submodule is a bit trickier than adding one.

Deinitialize

First, deinit the submodule with git submodule deinit :

[skade ;) ~/Work/submodule-practice (master)]
christie$ git submodule deinit psychic-avenger
Cleared directory 'psychic-avenger'
Submodule 'psychic-avenger' (git@github.com:christi3k/psychic-avenger.git) unregistered for path 'psychic-avenger'

This command removes the submodule’s confg entries in .git/config and .gitmodules and it removes files from the submodule’s working directory. This command will delete untracked files, even when they are listed in .gitignore.

Note: You can also use this command if you simply want to prevent having a local checkout of the submodule in your working tree, without actually removing the submodule from your main project.

Let’s check our work:

[skade ;) ~/Work/submodule-practice (master)]
christie$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

This shows no changes because git submodule deinit only makes changes to our local working copy.

Running ls we also see the directories are still present:

[skade ;) ~/Work/submodule-practice (master)]
christie$ ll
▕ drwxrwxr-x▏christie:christie│4 day │ 4K│furry-octo-nemesis
▕ drwxrwxr-x▏christie:christie│16 sec │ 4K│psychic-avenger
▕ -rw-rw-r--▏christie:christie│4 day │ 29B│README.md
▕ -rw-rw-r--▏christie:christie│4 day │ 110B│README.mediawiki

[skade ;) ~/Work/submodule-practice (master)]

Remove with git rm

To actually remove the submodule from your project’s repository, use git rm:

[skade ;) ~/Work/submodule-practice (master)]
christie$ git rm psychic-avenger
rm 'psychic-avenger'

Let’s check our work:

[skade ;) ~/Work/submodule-practice (master +)]
christie$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
(use "git reset HEAD ..." to unstage)

modified: .gitmodules
deleted: psychic-avenger

These changes have been staged by git automatically, so to see what has changed about .gitmodules, use --cached flag or its alias --staged:

[skade ;) ~/Work/submodule-practice (master +)]
christie$ git diff --cached
diff --git a/.gitmodules b/.gitmodules
index dec1204..e531507 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,6 +1,3 @@
[submodule "furry-octo-nemesis"]
path = furry-octo-nemesis
url = git@github.com:christi3k/furry-octo-nemesis.git
-[submodule "psychic-avenger"]
- path = psychic-avenger
- url = git@github.com:christi3k/psychic-avenger.git
diff --git a/psychic-avenger b/psychic-avenger
deleted file mode 160000
index fdd4b36..0000000
--- a/psychic-avenger
+++ /dev/null
@@ -1 +0,0 @@
-Subproject commit fdd4b366458757940d7692b61e22f4d1b21c825a

So we see that in .gitmodules, lines related to psychic-avenger have been removed and that the psychic-avenger directory and commit hash has also been removed.

And a directory listing shows the files are no longer in our working directory:

christie$ ll
▕ drwxrwxr-x▏christie:christie│4 day │ 4K│furry-octo-nemesis
▕ -rw-rw-r--▏christie:christie│4 day │ 29B│README.md
▕ -rw-rw-r--▏christie:christie│4 day │ 110B│README.mediawiki

Removing all reference to the submodule (optional)

For whatever reason, git does not remove all trace of the submodule even after these commands. To completely remove all reference, you need to also delete the .git/modules entry to really have it be gone:

[skade ;) ~/Work/submodule-practice (master)]
christie$ rm -rf .git/modules/psychic-avenger

Note: This probably optional for most use-cases. The only time you might run into trouble if you leave this reference is if you later add a submodule of the same name. In that case, git will complain and ask you to pick a different name or to simply checkout the submodule from the remote source it already knows about.

Also, be careful with rm -rf because it doesn’t prompt you for a confirmation and there’s no dry-run flag.

Commit changes

Now we commit our changes:

[skade ;) ~/Work/submodule-practice (master +)]
christie$ git commit -m "Remove psychic-avenger submodule."
[master 7833c1c] Remove psychic-avenger submodule.
2 files changed, 4 deletions(-)
delete mode 160000 psychic-avenger

Looks good, let’s push our changes:

[skade ;) ~/Work/submodule-practice (master)]
christie$ git push -n origin master
To git@github.com:christi3k/submodule-practice.git
d89b5cb..7833c1c master -&gt; master

Looks good, let’s do it for real:

[skade ;) ~/Work/submodule-practice (master)]
christie$ git push origin master
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 402 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To git@github.com:christi3k/submodule-practice.git
d89b5cb..7833c1c master -&gt; master

Updating submodules within your project

The simplest use case for updating submodules within your project is when you simply want to pull in the most recent version of that submodule or want to change to a different branch.

There are two methods for updating modules.

Method 1: Specify a branch in .gitmodules and use git submodule update --remote

Using this method, you first need to ensure that the branch you want to use is specified for each submodule in .gitmodules.

Let’s take a look at the .gitmodules file for our sample project:

[submodule "furry-octo-nemesis"]
  path = furry-octo-nemesis
  url = git@github.com:christi3k/furry-octo-nemesis.git
[submodule "psychic-avenger"]
  path = psychic-avenger
  url = git@github.com:christi3k/psychic-avenger.git
  branch = RELEASE_E
[submodule "scaling-octo-wallhack"]
  path = scaling-octo-wallhack
  url = git@github.com:christi3k/scaling-octo-wallhack.git

The submodule psychic-avenger is set to checkout branch RELEASE_E and both furry-octo-nemesis and scaling-octo-wallhack will checkout master because no branch is specified.

Edit .gitsubmodules

To change the branch that is checked out, update the value of branch:

[submodule "scaling-octo-wallhack"]
  path = scaling-octo-wallhack
  url = git@github.com:christi3k/scaling-octo-wallhack.git
  brach = REL_2

Now scaling-octo-wallhack is set to checkout the REL_2 branch.

Update with git submodule update –remote

[skade ;) ~/Work/submodule-practice (master *)] 
christie$ git submodule update --remote
Submodule path 'scaling-octo-wallhack': checked out 'e845f5431119b527b7cde1ad138a373c5b2d4ec1'

And if we cd into scaling-octo-wallhack and run branch -vva we confirm we’ve checked out the REL_2 branch:

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack ((e845f54...))] 
christie$ git branch -vva
* (detached from e845f54) e845f54 Release 2.
  master                  b49591a [origin/master] Cutting-edge changes.
  remotes/origin/HEAD     -> origin/master
  remotes/origin/REL_1    88d66d5 Prep Release 1.
  remotes/origin/REL_2    e845f54 Release 2.
  remotes/origin/master   b49591a Cutting-edge changes.

Method 2: git fetch and git checkout within submodule

First, change into the directory of the submodule you wish to update.

fetch from remote repository

Then run git fetch origin to grab any new commits:

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack ((b49591a...))] 
christie$ git fetch origin 
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 1), reused 3 (delta 1), pack-reused 0
Unpacking objects: 100% (3/3), done.
From github.com:christi3k/scaling-octo-wallhack
   e845f54..1cc1044  REL_2      -> origin/REL_2

Here was can see that the last commit for the REL_2 branch changed from e845f54 to 1cc1044.

Running branch -vva confirms this and that we haven’t changed which commit is checked out yet:

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack ((88d66d5...))] 
christie$ git branch -vva
* (detached from 88d66d5) 88d66d5 Prep Release 1.
  master                  b49591a [origin/master] Cutting-edge changes.
  remotes/origin/HEAD     -> origin/master
  remotes/origin/REL_1    88d66d5 Prep Release 1.
  remotes/origin/REL_2    1cc1044 Hotfix for Release 2 branch.
  remotes/origin/master   b49591a Cutting-edge changes.

Checkout branch

So now we can re-checkout the REL_2 remote branch:

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack ((88d66d5...))] 
christie$ git checkout origin/REL_2
Previous HEAD position was 88d66d5... Prep Release 1.
HEAD is now at 1cc1044... Hotfix for Release 2 branch.

Let’s check our work with branch -vva:

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack ((1cc1044...))] 
christie$ git branch -vva
* (detached from origin/REL_2) 1cc1044 Hotfix for Release 2 branch.
  master                       b49591a [origin/master] Cutting-edge changes.
  remotes/origin/HEAD          -> origin/master
  remotes/origin/REL_1         88d66d5 Prep Release 1.
  remotes/origin/REL_2         1cc1044 Hotfix for Release 2 branch.
  remotes/origin/master        b49591a Cutting-edge changes.

Commiting the changes

Moving back to our main project directory, let’s check our work with git status && git diff:

[skade ;) ~/Work/submodule-practice (master *)] 
christie$ git status && git diff
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   scaling-octo-wallhack (new commits)

no changes added to commit (use "git add" and/or "git commit -a")
diff --git a/scaling-octo-wallhack b/scaling-octo-wallhack
index 88d66d5..1cc1044 160000
--- a/scaling-octo-wallhack
+++ b/scaling-octo-wallhack
@@ -1 +1 @@
-Subproject commit 88d66d5ecc58d2ab82fec4fea06ffbfd2c55fd7d
+Subproject commit 1cc104418a6a24b9a3cc227df4ebaf707ea23b49

Notice that there are no changes to .gitmodules with this method. Instead, we’ve simply changed the commit hash that the super project is pointing to for this submodule.

Now let’s add, commit and push our changes:

[skade ;) ~/Work/submodule-practice (master *)] 
christie$ git add scaling-octo-wallhack

[skade ;) ~/Work/submodule-practice (master +)] 
christie$ git commit -m "Updating to current REL_2."
[master 5ddbe87] Updating to current REL_2.
 1 file changed, 1 insertion(+), 1 deletion(-)

[skade ;) ~/Work/submodule-practice (master)] 
christie$ git push -n origin master
To git@github.com:christi3k/submodule-practice.git
   4a97a6f..5ddbe87  master -> master

[skade ;) ~/Work/submodule-practice (master)] 
christie$ git push origin master
Counting objects: 2, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (2/2), 261 bytes | 0 bytes/s, done.
Total 2 (delta 1), reused 0 (delta 0)
To git@github.com:christi3k/submodule-practice.git
   4a97a6f..5ddbe87  master -> master

what’s the difference between git submodule update and git submodule update –remote?

Note: git submodule update –remote looks at the value you have in .gitmodules for branch. If there isn’t a value there, it assumes master. git submodule update looks at your repository has for the commit of the submodule project and checks that commit out. Both checkout to a detached state by default unless you specify –merge or –rebase.

These two commands have the ability to step on each other. If you have checked out a specific commit in the submodule directory, it’s possible for it to be different than the commit that would be checked out by git submdoule update –remote specificied in the branch value of .gitmodules.
Likewise, simply looking at the branch value in .gitmodules does not guarentee that’s the branch you have checked out for the submodule. When in doubt, cd to the submodule directory and run git branch -vva. git branch -vva is your friend!

When a subbmodule has been removed

When a submodule has been removed from a repository, what’s the best way to update your working directory to reflect this change?

The answer is that it depends on whether or not you have local, untracked files in the submodule directory that you want to keep.

Method 1: deinit and then fetch and merge

Use this method if you want to completely remove the submodule directory even if you have local, untracked files in it.

Note: In the following examples, we’re working in another checkout of our submodule-practice.

First, use git submodule deinit to deinitialize the submodule:

[skade ;) ~/Work/submodule-elsewhere (master *)] 
christie$ git submodule deinit psychic-avenger
error: the following file has local modifications:
    psychic-avenger
(use --cached to keep the file, or -f to force removal)
Submodule work tree 'psychic-avenger' contains local modifications; use '-f' to discard them

We have untracked changes, so we need to use -f to remove them:

[skade ;( ~/Work/submodule-elsewhere (master *)] 
christie$ git submodule deinit -f psychic-avenger
Cleared directory 'psychic-avenger'
Submodule 'psychic-avenger' (git@github.com:christi3k/psychic-avenger.git) unregistered for path 'psychic-avenger'

Now fetch changes from the remote repository and merge them:

[skade ;) ~/Work/submodule-elsewhere (master)] 
christie$ git fetch origin 
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (1/1), done.
remote: Total 3 (delta 2), reused 3 (delta 2), pack-reused 0
Unpacking objects: 100% (3/3), done.
From github.com:christi3k/submodule-practice
   666af5d..6038c72  master     -> origin/master

[skade ;) ~/Work/submodule-elsewhere (master)] 
christie$ git merge origin/master 
Updating 666af5d..6038c72
Fast-forward
 .gitmodules     | 3 ---
 psychic-avenger | 1 -
 2 files changed, 4 deletions(-)
 delete mode 160000 psychic-avenger

Running ls on our project directory shows that the all of psychic-avenger’s files have been removed:

[skade ;) ~/Work/submodule-elsewhere (master)] 
christie$ ll 
▕ drwxrwxr-x▏christie:christie│3  hour│   4K│furry-octo-nemesis
▕ drwxrwxr-x▏christie:christie│5  min │   4K│scaling-octo-wallhack
▕ -rw-rw-r--▏christie:christie│3  hour│  29B│README.md
▕ -rw-rw-r--▏christie:christie│3  hour│ 110B│README.mediawiki

Method 2: fetch and merge and clean up as needed

Use this method if you have local, untracked (and/or ignored) changes that you want to keep, or if you want to remove files manually.

First, fetch changes from the remote repository and merge them with your local branch:

[skade ;) ~/Work/submodule-elsewhere (master)]
christie$ git fetch origin
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 1), reused 3 (delta 1), pack-reused 0
Unpacking objects: 100% (3/3), done.
From github.com:christi3k/submodule-practice
d89b5cb..7833c1c master -> origin/master

[skade ;) ~/Work/submodule-elsewhere (master)]
christie$ git merge origin/master
Updating d89b5cb..7833c1c
warning: unable to rmdir psychic-avenger: Directory not empty
Fast-forward
.gitmodules | 3 ---
psychic-avenger | 1 -
2 files changed, 4 deletions(-)
delete mode 160000 psychic-avenger

Note the warning “unable to rm dir…” and let’s check our work:

[skade ;) ~/Work/submodule-elsewhere (master)]
christie$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Untracked files:
(use "git add ..." to include in what will be committed)

psychic-avenger/

nothing added to commit but untracked files present (use "git add" to track)

No uncommited or staged changes, but the directory that was our submodule psychic-avenger is now untracked. Running ls shows that there are still files in the directory, too:

[skade ;( ~/Work/submodule-elsewhere (master)]
christie$ ll psychic-avenger/
▕ -rw-rw-r--▏christie:christie│30 min │ 192B│README.md

Now you can clean up files as you like. In this example we’ll delete the entire psychic-avenger directory:

[skade ;) ~/Work/submodule-elsewhere (master)]
christie$ rm -rf psychic-avenger

Working on projects checked out as submodules

Working on projects checked out as submodules is rather straight-forward, particularly if you are comfortable with git branching and make liberal use of git branch -vva.

Let’s pretend that scaling-octo-wallhack is an extension that I’m developing for my project submodule-practice. I want to work on the project while it’s checked out as a submodule because doing so makes it easy to test the extension within my larger project.

Create a working branch

First switch the the branch that you want to use as the base for your work. I’m going to use local tracking branch master, which I’ll first ensure is up to date with the remote origin/master:

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack ((1cc1044...))] 
christie$ git branch -vva
* (detached from origin/REL_2) 1cc1044 Hotfix for Release 2 branch.
  master                       b49591a [origin/master] Cutting-edge changes.
  remotes/origin/HEAD          -> origin/master
  remotes/origin/REL_1         88d66d5 Prep Release 1.
  remotes/origin/REL_2         1cc1044 Hotfix for Release 2 branch.
  remotes/origin/master        b49591a Cutting-edge changes.

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack ((b49591a...))] 
christie$ git checkout master
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.

If master had not been up-to-date with orgin/master, I would have merged.

Next, let’s create a tracking branch for this awesome feature we’re going to work on:

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack (master)] 
christie$ git checkout -b awesome-feature
Switched to a new branch 'awesome-feature'

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack (awesome-feature)] 
christie$ git branch -vva
* awesome-feature       b49591a Cutting-edge changes.
  master                b49591a [origin/master] Cutting-edge changes.
  remotes/origin/HEAD   -> origin/master
  remotes/origin/REL_1  88d66d5 Prep Release 1.
  remotes/origin/REL_2  1cc1044 Hotfix for Release 2 branch.
  remotes/origin/master b49591a Cutting-edge changes.

Do some work, add and commit changes

No we’ll do some work on the feature, add and commit that work:

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack (awesome-feature)] 
christie$ touch awesome_feature.txt

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack (awesome-feature)] 
christie$ git add awesome_feature.txt 

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack (awesome-feature +)] 
christie$ git commit -m "first round of work on awesome feature"
[awesome-feature 005994b] first round of work on awesome feature
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 awesome_feature.txt

Push to remote repository

Now we’ll push that to our remost repository so others can contribute:

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack (awesome-feature)] 
christie$ git push -n origin awesome-feature 
To git@github.com:christi3k/scaling-octo-wallhack.git
 * [new branch]      awesome-feature -> awesome-feature

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack (awesome-feature)] 
christie$ git push origin awesome-feature 
Counting objects: 2, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (2/2), 265 bytes | 0 bytes/s, done.
Total 2 (delta 1), reused 0 (delta 0)
To git@github.com:christi3k/scaling-octo-wallhack.git
 * [new branch]      awesome-feature -> awesome-feature

Switch back to remote branch, headless checkout

If we’d like to switch back to a remote branch, we can:

[skade ;) ~/Work/submodule-practice/scaling-octo-wallhack (awesome-feature)] 
christie$ git checkout origin/REL_2
Note: checking out 'origin/REL_2'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:

  git checkout -b new_branch_name

HEAD is now at 1cc1044... Hotfix for Release 2 branch.

Using this new branch to collaborate

To try this awesome feature in another checkout, use git fetch:

[skade ;) ~/Work/submodule-elsewhere/scaling-octo-wallhack ((1cc1044...))] 
christie$ git fetch origin 
remote: Counting objects: 2, done.
remote: Compressing objects: 100% (1/1), done.
remote: Total 2 (delta 1), reused 2 (delta 1), pack-reused 0
Unpacking objects: 100% (2/2), done.
From github.com:christi3k/scaling-octo-wallhack
 * [new branch]      awesome-feature -> origin/awesome-feature

If you just want to try the feature, checkout orgin/branch:

[2724][skade ;) ~/Work/submodule-elsewhere/scaling-octo-wallhack ((1cc1044...))] 
christie$ git checkout origin/awesome-feature 
Previous HEAD position was 1cc1044... Hotfix for Release 2 branch.
HEAD is now at 005994b... first round of work on awesome feature

If you plan to work on the feature, create a tracking branch:

[2725][skade ;) ~/Work/submodule-elsewhere/scaling-octo-wallhack ((005994b...))] 
christie$ git checkout -b awesome-feature 
Switched to a new branch 'awesome-feature'

Acknowledgements

Thanks GPHemsley for helping me figure out git submodules within the context of our MozillaWiki work. I couldn’t have written this post without those conversations or the notes I took during them.

Additional Resources

Update 19 Feb: Fixed typos and added ‘Additional Resources’ section.