Git Reference ยท Files and Formats
The .gitmodules file
Reference for the .gitmodules file: the path, url, branch, update, ignore, fetchRecurseSubmodules and shallow keys, how it relates to .git/config and gitlinks.
.gitmodules is a committed file at the top of a working tree that records each submodule's name, path and URL. It uses the same format as Git configuration files, so you read and write it with git config -f .gitmodules. It is the shared, versioned half of submodule setup: the commit a submodule is pinned to is stored separately in the parent's tree as a gitlink entry.
The file is only a recipe. Nothing is cloned until you run git submodule init and git submodule update (or git clone --recurse-submodules). At that point the URLs are copied into your local .git/config, where you can override them without changing the committed file.
[submodule "libs/greeter"]
path = libs/greeter
url = https://example.com/greeter.git
branch = main
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
[submodule "<name>"] path = <relative path> url = <repository URL or relative path> branch = <branch or .> update = checkout | rebase | merge | none ignore = all | dirty | untracked | none fetchRecurseSubmodules = true | false | on-demand shallow = true | false
| Key | Description |
|---|---|
path |
Where the submodule sits in the working tree. Required; relative to the file. |
url |
Where to clone from. A relative URL such as ../lib.git is resolved against the parent's remote URL. |
branch |
Branch tracked by git submodule update --remote. The value . means "the same branch name as the parent". Default is the remote's HEAD. |
update |
Default procedure for git submodule update: checkout (detached HEAD), rebase, merge or none. Commands starting with ! are not honored from this file for safety. |
ignore |
What git status and git diff ignore about the submodule: none, untracked, dirty or all. |
fetchRecurseSubmodules |
Whether git fetch and git pull descend into the submodule. |
shallow |
When true, clone the submodule with --depth=1. |
Edge cases: [submodule "<name>"] names are arbitrary but usually equal the path. Removing the entry without removing the gitlink and .git/modules/<name> leaves a half-removed submodule.
Usage notes
- Two places, two roles.
.gitmodulesis committed and shared;.git/configholds each clone's active URL. Edit the URL locally withgit config submodule.<name>.urland rungit submodule syncto pick up a changed.gitmodules. - The commit is not in the file. The exact revision lives in the parent's tree. Updating a submodule means committing the new gitlink in the parent.
- Use
git config -f .gitmodulesinstead of editing by hand; it keeps quoting right. - Prefer HTTPS or relative URLs for public projects. SSH URLs fail for people without keys.
- File protocol is restricted. Since Git 2.38.1, local
file:submodule clones need-c protocol.file.allow=always, as the examples show. - Private data. Never put credentials in
url; the file is committed. git rmremoves both the gitlink and the.gitmodulessection, but not.git/modules/<name>; delete that to fully clean up.submodule.recurse(a config setting) makes checkout, pull and other commands follow submodules; see submodule.recurse.