Git Submodule Management Commands Guide

Submodule Management

Submodules are a feature that allows you to include one Git repository inside another Git repository. This is useful for large projects or when using common code across multiple projects. This section explains the basic usage of submodules, with a particular focus on how to change branches.

git submodule add - Adding Submodules

Adds an existing repository as a submodule.

Option	Description
-b, --branch <branch-name>	Specify the branch to track
--name <name>	Specify the name of the submodule
-f, --force	Overwrite existing path

Examples:

git submodule add https://github.com/username/library.git lib - Add repository as a submodule in the lib directory
git submodule add -b develop https://github.com/username/library.git lib - Add a submodule that tracks the develop branch

git submodule init/update - Initializing and Updating Submodules

Initializes submodules and fetches data from the remote repository.

Command/Option	Description
git submodule init	Initialize submodules (copy information from .gitmodules to .git/config)
git submodule update	Update submodule content
--init	Initialize uninitialized submodules before updating
--recursive	Process nested submodules recursively
--remote	Update to the latest remote commit (by default, updates to the commit recorded in the superproject)

Examples:

git submodule init - Initialize all submodules
git submodule update - Update all submodules
git submodule update --init - Perform initialization and update in one step
git submodule update --init --recursive - Initialize and update including nested submodules
git clone --recurse-submodules https://github.com/username/project.git - Clone a repository and fetch its submodules at the same time

git submodule set-branch - Changing Submodule Branch

Changes the branch that a submodule tracks.

Option	Description
--branch <branch-name>	Specify the branch to track
--default	Revert to the default branch (usually main/master)

Examples:

git submodule set-branch --branch develop lib - Change the tracking branch of the lib submodule to develop
git submodule set-branch --default lib - Revert the tracking branch of the lib submodule to the default

Changing Branches Within a Submodule

Method for directly changing branches within a submodule directory.

Examples:

cd lib - Navigate to the submodule directory
git checkout develop - Checkout the develop branch
cd .. - Return to the parent directory
git add lib - Stage the submodule changes
git commit -m "Switch lib submodule to develop branch" - Commit the changes

Batch Updating and Managing Submodules

Commands for efficiently managing multiple submodules.

Command	Description
git submodule foreach <command>	Execute the specified command in each submodule
git submodule status	Display the status of all submodules
git submodule sync	Synchronize submodule remote URLs

Examples:

git submodule foreach git pull origin master - Update the master branch in all submodules
git submodule foreach git checkout develop - Checkout the develop branch in all submodules
git submodule foreach 'git checkout -b feature/new-feature || true' - Create a new branch in all submodules (ignore errors if it already exists)
git submodule status - Check the status of all submodules
git submodule sync - Update submodule remote URLs from the .gitmodules file

Note: After changing a submodule's branch, you need to commit that change in the parent repository. Otherwise, when other developers clone or update the project, the submodule will revert to its original branch.