Updating and Synchronizing Submodules

When you work with Git submodules, the main project (superproject) usually points to a specific commit of the submodule, not necessarily its latest version.

This lesson teaches you how to update your submodules to newer versions and ensure their configurations are correct.

The most common command to update submodules is git submodule update. This command does two main things:

• It checks out the exact commit that the superproject expects for each submodule.
• It ensures the submodule's working directory matches this recorded commit.

It does not fetch new commits from the submodule's remote repository.

Imagine your main project's .gitmodules file specifies a submodule my-lib. When someone else updates my-lib in its own repository and then updates the superproject's pointer to my-lib, you'll need to update.

After pulling changes in the superproject, run this to get the submodule's files to match the new recorded commit:

What if you want your submodule to point to the absolute latest commit on its remote tracking branch, not just the one recorded by the superproject?

That's where the --remote option comes in handy. It fetches from the submodule's remote and updates its HEAD to the tip of its configured tracking branch (e.g., main or master).

Using --remote is powerful for quickly bringing submodules up-to-date with their own upstream changes. It's like doing a git pull inside each submodule.

Remember, after doing this, your superproject's submodule pointer will be 'out of sync'. You'll need to commit the submodule's new SHA-1 hash to the superproject.

Sometimes, the URL for a submodule's remote repository might change. When this happens, the URL stored in your local Git configuration (.git/config) for that submodule needs to be updated.

The git submodule sync command is designed to synchronize these URLs. It reads the URLs from the .gitmodules file and updates the local configuration for each submodule.

You'll typically use git submodule sync in these situations:

• After someone changes a submodule's URL in the .gitmodules file and you pull those changes.
• When you clone a repository with submodules for the first time, though git submodule update --init often handles this implicitly.
• If you manually changed a submodule's URL in .gitmodules and want your local config to reflect it.

Let's say the URL for your my-lib submodule changed from old-url.git to new-url.git in the .gitmodules file. After pulling that change into your superproject, your local configuration for my-lib is still pointing to the old URL.

Run this command to fix it:

For a robust workflow that covers most scenarios when updating submodules, consider combining commands:

• git pull origin main: Get latest superproject changes.
• git submodule sync: Update submodule URLs if they changed.
• git submodule update --init --recursive --remote: Initialize any new submodules, update all existing ones to their latest remote, and handle nested submodules.

This ensures you're fully up-to-date.

You've pulled a new version of your superproject. Your colleague informs you they've updated a submodule called shared-utils in its own repository, but they haven't yet committed the new submodule pointer to the superproject.

Which command should you use to get the shared-utils submodule to its latest state from its remote, without waiting for the superproject to record it?

You've learned how to manage submodule updates:

• git submodule update: Checks out the commit recorded by the superproject.
• git submodule update --remote: Fetches the latest changes from the submodule's remote and updates its working directory.
• git submodule sync: Synchronizes submodule URLs from .gitmodules to your local Git config.

These commands are essential for maintaining a healthy and up-to-date project with submodules!