git-submodule - Linux


git-submodule tracks submodules in a Git repository, which are external repositories that are included as part of the main repository. It allows for the inclusion of third-party code or independent modules within a project.


git submodule <command> [options] [<args>]


  • init – Initializes a new submodule
  • add – Adds a submodule
  • update – Updates submodules
  • status – Shows the status of submodules
  • sync – Synchronizes submodules
  • clone – Clones submodules
  • addbranch – Adds a branch to a submodule
  • foreach – Executes a command in each submodule
  • summary – Summarizes the status of all submodules


  • -q, –quiet – Suppresses output
  • -v, –verbose – Enables verbose output
  • -f, –force – Overwrites existing submodules
  • -s, –squash – Squashes commits in submodule updates
  • -n, –no-fetch – Skips fetching submodules
  • -d, –delete – Deletes a submodule
  • -u, –update – Updates submodules after adding
  • -b, –branch – Specifies the branch to clone in –add


Initializing a Submodule

git submodule init
git submodule add

Updating Submodules

git submodule update
git submodule foreach git pull --rebase

Checking Submodule Status

git submodule status
git submodule foreach git status

Adding a Branch to a Submodule

git submodule add -b my-branch

Deleting a Submodule

git submodule deinit --force submodule-name
git rm -rf .git/modules/submodule-name

Common Issues

Submodules Not Found

  • Ensure that the submodules have been initialized and added.
  • Check the repository’s .gitmodules file for correct submodule paths.

Submodule Updates Not Working

  • Verify if the remote repository is available and accessible.
  • Try fetching the latest changes from the remote repository: git remote update.


Combining with Git

  • Use git config to set submodule update behavior.
  • Utilize git submodule status to track submodule changes and integration progress.

Scripting and Automation

  • Write scripts to automate submodule synchronization and updates.
  • Integrate git-submodule into CI/CD workflows.

Related Commands

  • git add – Adds files to the index
  • git clone – Clones a Git repository
  • git init – Initializes a Git repository
  • git status – Shows the status of the current working tree