Comment vérifier l'état des sous-modules Git dans un dépôt

Introduction

Git submodules are a powerful feature that allow you to include external repositories within your own projects. This capability is particularly useful when your project depends on external libraries or components that are maintained separately. By using submodules, you can keep these dependencies up-to-date and well-managed.

In this tutorial, you will learn how to check the status of Git submodules in your repository, understand what changes have been made to them, and ensure they are properly synchronized with their source repositories.

Skills Graph

Creating a Repository with Submodules

Let's start by creating a sample repository with a submodule to have a practical environment for our learning.

Setting Up the Main Repository

First, we'll create a new main repository where we'll add our submodule. Open your terminal and run the following commands:

cd ~/project
mkdir main-repo
cd main-repo
git init

You should see output similar to:

Initialized empty Git repository in /home/labex/project/main-repo/.git/

Now, let's create a simple file in our main repository:

echo "## Main Repository" > README.md
git add README.md
git commit -m "Initial commit"

The output should indicate that you've created your first commit:

[master (root-commit) xxxxxxx] Initial commit
 1 file changed, 1 insertion(+)
 create mode 100644 README.md

Adding a Submodule

Now let's add a submodule to our main repository. For this tutorial, we'll use a small, public repository as our submodule:

git submodule add https://github.com/libgit2/libgit2-backends.git libs/libgit2-backends

This command will clone the repository and add it as a submodule in the libs/libgit2-backends directory. You should see output similar to:

Cloning into '/home/labex/project/main-repo/libs/libgit2-backends'...
remote: Enumerating objects: xxx, done.
remote: Counting objects: 100% (xxx/xxx), done.
remote: Compressing objects: 100% (xxx/xxx), done.
remote: Total xxx (delta xx), reused xxx (delta xx), pack-reused xxx
Receiving objects: 100% (xxx/xxx), xxx KiB | xxx KiB/s, done.
Resolving deltas: 100% (xxx/xxx), done.

Understanding the Changes

When you add a submodule, Git creates a .gitmodules file in your repository that tracks the URL and path of the submodule. Let's look at this file:

cat .gitmodules

You should see content similar to:

[submodule "libs/libgit2-backends"]
	path = libs/libgit2-backends
	url = https://github.com/libgit2/libgit2-backends.git

Let's also check the status of our repository:

git status

You should see output indicating that both the new .gitmodules file and the submodule directory have been added:

On branch master
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   .gitmodules
        new file:   libs/libgit2-backends

Let's commit these changes to complete our setup:

git commit -m "Add libgit2-backends submodule"

You should now have a repository with a submodule successfully set up.

Checking the Status of Submodules

Now that we have a repository with a submodule, let's learn how to check the status of the submodule and understand what the output means.

Basic Submodule Status Check

Git provides a specific command to check the status of submodules. Run the following command:

cd ~/project/main-repo
git submodule status

You should see output similar to:

+abcdef1234567890abcdef1234567890abcdef12 libs/libgit2-backends (v1.0.0-123-gabcdef12)

Let's understand what this output means:

1. The first character can be one of:

   • +: indicates the submodule commit checked out differs from what is registered in the main repository
   • (space): indicates the submodule is in sync with what is registered
   • -: indicates the submodule is not initialized
   • U: indicates merge conflicts in the submodule

2. The alphanumeric string is the commit hash of the current commit checked out in the submodule.

3. The path shows where the submodule is located in your repository.

4. The parenthesized text shows additional information about the checked-out commit, like tags or branch names.

Detailed Submodule Information

For more detailed information about your submodules, you can use the following command:

git submodule

This will show similar information to the status command, but in a different format.

Using Git Status to See Submodule Changes

You can also use the standard git status command to see changes in submodules:

git status

If there are no changes to the submodule, you'll see no mention of it in the output. However, if there are changes to the submodule's checked-out commit or files within the submodule, git status will show this information.

Examining Submodule Content

Let's examine the contents of our submodule:

ls -la libs/libgit2-backends/

You'll see the files from the libgit2-backends repository. Note that the submodule is essentially a complete Git repository within your main repository. You can verify this by checking for the presence of a .git directory:

ls -la libs/libgit2-backends/.git

You might not see a .git directory directly, but rather a file that points to the actual Git repository data stored in your main repository's .git/modules directory. This is how Git manages submodules.

Understanding the Submodule Reference

The main repository stores a reference to a specific commit in the submodule repository. This reference is what Git uses to know which version of the submodule should be checked out when cloning your repository or updating the submodule.

Let's see the commit that our main repository is referencing:

cd ~/project/main-repo
git ls-files --stage libs/libgit2-backends

The output will show a commit hash, which is the specific commit of the submodule that the main repository is tracking.

Updating Submodules

One common task when working with submodules is keeping them up-to-date with their remote repositories. Let's learn how to update our submodule.

Initializing and Updating Submodules

If you've just cloned a repository that contains submodules, you'll need to initialize and update them. For our existing repository, we can demonstrate this process with:

cd ~/project/main-repo
git submodule init
git submodule update

The init command initializes your submodules configuration, and the update command fetches the data and checks out the commit specified in your main repository.

You can also combine these commands:

git submodule update --init

Updating Submodules to Latest Remote Version

If you want to update a submodule to the latest commit in its remote repository, you can use:

cd ~/project/main-repo
git submodule update --remote libs/libgit2-backends

This command fetches the latest changes from the remote repository and updates the submodule. You should see output indicating that Git is fetching changes.

After running this command, let's check the status of the submodule:

git submodule status

You'll notice the output now shows a plus sign (+) at the beginning, indicating that the submodule's checked-out commit differs from what is recorded in the main repository:

+abcdef1234567890abcdef1234567890abcdef12 libs/libgit2-backends (origin/HEAD)

To confirm the changes to your main repository, run:

git status

You should see output indicating that the submodule has been modified:

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   libs/libgit2-backends (new commits)

Committing the Updated Submodule Reference

To record the updated submodule state in your main repository, you need to add and commit the changes:

git add libs/libgit2-backends
git commit -m "Update libgit2-backends submodule to latest version"

The output should indicate that you've successfully committed the new submodule reference.

Checking the Updated Status

After committing the updated submodule reference, let's check the status again:

git submodule status

The output should no longer have a plus sign at the beginning, indicating that the submodule is now in sync with what is recorded in the main repository:

 abcdef1234567890abcdef1234567890abcdef12 libs/libgit2-backends (origin/HEAD)

Understanding Submodule Update Options

The git submodule update command has several options that control how updates are performed:

• --remote: Update to the latest commit on the remote tracking branch
• --merge: Merge changes if the current branch is behind the remote
• --rebase: Rebase changes if the current branch is behind the remote
• --recursive: Update nested submodules too

For most basic use cases, git submodule update --remote is sufficient.

Working with Submodule Changes

Sometimes you need to work with changes inside a submodule. In this step, we'll learn how to make and manage changes within submodules.

Navigating into the Submodule

To work with a submodule, you need to navigate into its directory:

cd ~/project/main-repo/libs/libgit2-backends

From here, you can use standard Git commands to view information about the submodule repository:

git status
git log -3 --oneline

The git status command shows the current state of the submodule repository, and git log shows the recent commits.

Making Changes in a Submodule

Let's make a simple change to a file in the submodule. First, let's create a new file:

echo "## My notes on libgit2-backends" > NOTES.md

Now let's check the status of our change:

git status

You should see output indicating that you have an untracked file:

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        NOTES.md

Let's add and commit this change to the submodule:

git add NOTES.md
git commit -m "Add notes file"

You should see output confirming your commit within the submodule.

Checking the Status from the Main Repository

Now, let's go back to the main repository and check the status:

cd ~/project/main-repo
git status

You should see output indicating that the submodule has been modified:

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   libs/libgit2-backends (new commits)

Committing Submodule Changes in the Main Repository

To record the new state of the submodule in your main repository, you need to add and commit the changes:

git add libs/libgit2-backends
git commit -m "Update libgit2-backends with notes file"

The output should indicate that you've successfully committed the new submodule reference.

Viewing Detailed Submodule Changes

To see more detailed information about changes in submodules, you can use:

git diff --submodule

This command shows the range of commits that have been added or removed in each changed submodule.

Summary of Working with Submodule Changes

When working with changes in a submodule, remember this workflow:

1. Navigate into the submodule directory
2. Make and commit changes within the submodule
3. Return to the main repository
4. Add and commit the updated submodule reference

This two-step commit process (first in the submodule, then in the main repository) is essential for properly tracking changes to submodules.

Summary

In this tutorial, you have learned how to work with Git submodules, focusing on checking their status and making updates. Here's what you accomplished:

1. Created a main repository and added a submodule to it
2. Learned how to check the status of submodules using various Git commands
3. Updated a submodule to the latest version from its remote repository
4. Made changes within a submodule and properly tracked those changes in the main repository

Git submodules provide a powerful way to include external repositories within your projects, allowing you to manage dependencies efficiently. By understanding how to check their status and manage updates, you can ensure your project remains properly synchronized with its dependencies.

Key commands to remember:

• git submodule status - Check the current status of submodules
• git submodule update --remote - Update submodules to their latest versions
• git add <submodule-path> - Stage changes to a submodule's reference
• git diff --submodule - View detailed changes in submodules

With these skills, you can effectively manage Git repositories that incorporate external code through submodules.