Mastering git, Part 9, git Submodule

Set up: This allows the repository to be local a file directory:

Create remote:

Creating repos1

Creating lib1

Adding lib1 as submodule to repos1

Cloning a Project with Submodules to repos2

Working on Submodule lib1 in repos2:

Pulling in Upstream Changes from the Submodule Remote in repos1:

Working on Submodule lib1 in repos1

Cloning repos3

Let’s break down these Git commands related to submodules and their effects:

  1. git submodule update:
    • Effect: This command is used to update the submodules to the commit specified in the superproject. When you have a project with submodules, these submodules are usually fixed to specific commits. Running git submodule update will ensure your submodules are set to those specific commits.
    • Example: Suppose your main project (superproject) has a submodule at commit abc123. If someone else updates the submodule and you pull the latest changes in the superproject, git submodule update will set the submodule to commit abc123.
    • Difference: Unlike git submodule update --remote, it does not update the submodule to the latest commit in its own branch; it updates to the commit specified in the superproject.
  2. git submodule sync:
    • Effect: This command is used to update the URL of the submodule. If the submodule’s repository URL changes in the superproject configuration, running git submodule sync will update your local submodule configuration to the new URL.
    • Example: If the URL of a submodule repository was changed in the .gitmodules file, git submodule sync will update your local configuration to match this new URL.
    • Difference: This command does not change any submodule content, unlike git submodule update, which updates the submodule to a specific commit.
  3. git submodule update --remote:
    • Effect: This updates the submodules to the latest commit available on their respective branches as specified in .gitmodules, rather than the commit specified in the superproject.
    • Example: If a submodule is set to track the master branch, git submodule update --remote will update the submodule to the latest commit on the master branch.
    • Difference: Unlike the basic git submodule update, this command does not adhere to the commit specified in the superproject but fetches the latest from the tracked branch.
  4. git pull --recurse-submodules:
    • Effect: This command updates both the superproject and the submodules. It fetches and merges changes from the remote for the superproject and the submodules.
    • Example: When you have changes in both your superproject and submodules in the remote repository, git pull --recurse-submodules will update all of them to their latest commits.
    • Difference: It not only updates the superproject (like a regular git pull) but also ensures that all submodules are updated.
  5. git push --recurse-submodules=check:
    • Effect: This command, when pushing, checks if any commits in submodules need to be pushed to their respective remotes. If there are such commits, the push is aborted.
    • Example: Before pushing changes in your superproject, this command ensures that all submodule changes are also pushed. If not, it prevents the push to the superproject.
    • Difference: It provides a safety check before pushing, unlike a regular git push, which does not consider submodule statuses.
  6. git push --recurse-submodules=on-demand:
    • Effect: Similar to the above, but instead of just checking, it attempts to push the changes of the submodules to their respective remotes automatically if needed.
    • Example: If submodule changes haven’t been pushed, using this command will push both the superproject and the necessary submodule changes.
    • Difference: It actively pushes submodule changes if needed, as opposed to git push --recurse-submodules=check, which only checks and aborts if needed.

To list all the submodules:

If you want more detailed information about each submodule

Removing a Submodule

  1. Delete the Submodule Reference:
    Remove the submodule entry from the index and delete the relevant section from .gitmodules and .git/config:

  1. Remove Submodule Files:
    Manually delete the submodule’s files from your working directory:

  1. Commit the Changes:
    Commit these changes to the repository:

Adding a Submodule

  1. Add the Submodule:
    To add a new submodule, you use the git submodule add command followed by the repository URL and the path where you want to place it in your project:

For example:

  1. Initialize and Fetch the Submodule Contents:
    If the submodule has nested submodules, initialize and update them:

0 0 votes
Article Rating
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Would love your thoughts, please comment.x