git submodules: exploring the add api

Git Submodules can be really useful, but they’re not always straightforward to use. Today, I want to explore the git submodules add API a bit.

The full API for the add command is:

git submodule [--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--] <repository> [<path>]

If we start with basics, we might add the simplest version to our project:

git submodule git@github.com:stephencweiss/my-submodule.git

This would add an entry to .gitmodules:

[submodule "my-submodule"]
    path = my-submodule
    url = git@github.com:stephencweiss/my-submodule.git

But, what if we want the files of my-submodule to live somewhere else? We can use the path optional argument when we add the submodule.

For example, if added my-submodule, stored it in a/path/to/submodule and named it the-submodule, we could do that with:

git submodule add --name the-submodule git@github.com:stephencweiss/my-submodule.git a/path/to/submodule

The .gitmodules would now have a new entry:

[submodule "the-submodule"]
    path = a/path/to/submodule
    url = git@github.com:stephencweiss/my-submodule.git