git-submodule

Manage embedded external repositories within a project

TLDR

Add submodule

$ git submodule add [url] [path]

Initialize submodules

$ git submodule init

Update submodules

$ git submodule update

Clone with submodules

$ git submodule update --init --recursive

Show submodule status

$ git submodule status

Pull submodule changes

$ git submodule update --remote

Remove submodule

$ git submodule deinit [path] && git rm [path]

Run a command in each submodule

$ git submodule foreach '[command]'

Sync submodule URLs from .gitmodules to local config

$ git submodule sync --recursive

SYNOPSIS

git submodule command [options]

git submodule manages submodules, which are external Git repositories embedded within a parent repository at specific paths. Each submodule tracks a particular commit of the external repository.Submodules allow projects to include and track dependencies or shared components while keeping their histories separate. Use `update --init --recursive` after cloning to populate all submodule contents.

PARAMETERS

--init

Initialize uninitialized submodules before updating.

--recursive

Recurse into nested submodules.

--remote

Use the submodule's remote tracking branch instead of the superproject's recorded SHA-1.

-f, --force

Force checkout even if the submodule already matches.

-b branch, --branch branch

Branch of repository to track (add, set-branch).

-j n, --jobs n

Clone new submodules in parallel with n jobs.

-q, --quiet

Only print error messages.

--depth depth

Create a shallow clone with truncated history.

-N, --no-fetch

Do not fetch new objects from the remote (update).

CONFIGURATION

.gitmodules

Configuration file mapping submodule names to their repository URLs and local paths.

SUBCOMMANDS

add URL [path]

Add a repository as a submodule at a given path.

init [path...]

Initialize submodules recorded in the index.

update [path...]

Update registered submodules to match the superproject.

status [path...]

Show status of submodules.

deinit [path...]

Unregister submodules and remove their work trees.

sync [path...]

Sync submodule remote URLs from .gitmodules to local config.

foreach command

Run a shell command in each checked-out submodule.

summary [commit] [path...]

Show commit summary between commit and working tree/index.

set-branch path

Set the default remote tracking branch for a submodule.

set-url path newurl

Set the URL of a submodule.

absorbgitdirs

Move submodule .git directories into the superproject's .git/modules/.