git submodules: exploring the add api



~1 min read


157 words

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

This would add an entry to .gitmodules:

[submodule "my-submodule"]
    path = my-submodule
    url =

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 a/path/to/submodule

The .gitmodules would now have a new entry:

[submodule "the-submodule"]
    path = a/path/to/submodule
    url =

Hi there and thanks for reading! My name's Stephen. I live in Chicago with my wife, Kate, and dog, Finn. Want more? See about and get in touch!