Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
[submodule "libs/greeter"]
    path = libs/greeter
    url = https://example.com/greeter.git
    branch = main

Try it

Bash What git submodule add writes

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.

Bash Edit keys with git config -f

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

Terminal
[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. .gitmodules is committed and shared; .git/config holds each clone's active URL. Edit the URL locally with git config submodule.<name>.url and run git submodule sync to 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 .gitmodules instead 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 rm removes both the gitlink and the .gitmodules section, 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.