Add, Update, and Remove Git Submodule

Introduction

Git is a popular version control system used for managing source code. One of powerful features of Git is its ability to incorporate external repositories as submodules within a project. This allows you to reuse code from other repositories within your own project, and keep track of changes to both parent project and submodules independently.

In this article, we will explore how to add, update, and remove Git submodules. We will cover basic commands and options required for each operation, along with examples to help you better understand process.

Adding a Git Submodule

Adding a Git submodule is a simple process. To add a new submodule to your project, you can use git submodule add command. This command takes two arguments: URL of submodule repository, and path where submodule should be added within your project.

For example, let's say we want to add "jquery" repository as a submodule in our project. We would use following command −

git submodule add https://github.com/jquery/jquery.git path/to/submodule

This command will clone "jquery" repository into "path/to/submodule" directory within our project, and add it as a submodule.

Updating a Git Submodule

After you have added a submodule to your project, you may want to update it to get latest changes. To update a submodule, you can use git submodule update command.

There are several options you can use with this command to control how update is performed. default behavior is to update submodule to commit specified in parent project's .gitmodules file. However, you can also update submodule to latest commit, or to a specific branch or commit hash.

For example, let's say we want to update "jquery" submodule to latest commit. We would use following command −

git submodule update --remote path/to/submodule

This command will fetch latest changes from "jquery" repository, and update submodule in our project to latest commit.

Removing a Git Submodule

If you no longer need a submodule in your project, you can remove it using git submodule deinit and git rm commands.

The git submodule deinit command removes submodule from your project's .git/config file. This tells Git to stop tracking changes to submodule. However, submodule's files are still present in your project's directory.

To remove submodule's files, you can use git rm command. This command removes submodule's files from your project's directory, as well as from Git's index.

For example, let's say we want to remove "jquery" submodule from our project. We would use following commands −

git submodule deinit path/to/submodule
git rm path/to/submodule

These commands will remove "jquery" submodule from our project's .git/config file, and delete its files from our project's directory.

Advanced Submodule Management

In addition to basic operations of adding, updating, and removing Git submodules, there are several advanced techniques you can use to manage submodules more effectively.

Recursive Submodule Initialization and Update

If your project contains multiple submodules, initializing and updating them individually can become cumbersome. Fortunately, Git provides a recursive option that allows you to initialize and update all submodules at once.

To recursively initialize all submodules in your project, you can use git submodule update --init command. This command will initialize all submodules that have not been initialized yet.

To recursively update all submodules in your project, you can use git submodule update --recursive command. This command will update all submodules to commit specified in parent project's .gitmodules file.

Custom Submodule Branches

By default, submodules are updated to commit specified in parent project's .gitmodules file. However, you can also specify a custom branch or commit hash for each submodule.

To specify a custom branch for a submodule, you can use --branch option with git submodule add command. For example −

git submodule add --branch my-branch https://github.com/my-repo/my-submodule.git path/to/submodule

This command will add "my-submodule" repository as a submodule, and checkout "my-branch" branch.

To update a submodule to a custom branch or commit hash, you can use git submodule update --remote --merge command with --remote and --merge options. For example −

git submodule update --remote --merge path/to/submodule

This command will fetch latest changes from "my-submodule" repository, and merge them into current branch.

Submodule Stashing

When you update a submodule, any local changes you have made within submodule will be lost. To avoid losing these changes, you can use Git's stash feature to save your changes before updating submodule.

To stash changes within a submodule, you can use git submodule foreach command with git stash command. For example −

git submodule foreach 'git stash'

This command will stash changes within all submodules in your project.

To apply stashed changes after updating a submodule, you can use git submodule foreach command with git stash apply command. For example −

git submodule foreach 'git stash apply'

This command will apply stashed changes within all submodules in your project.

Troubleshooting Git Submodule Issues

While Git submodules are a powerful tool for managing code dependencies, they can also be a source of frustration when things go wrong. Here are some common issues and their solutions −

Issue: Submodule Not Initialized

When you clone a Git repository that contains submodules, submodules are not initialized by default. You will need to run git submodule update command to initialize them.

Solution − Run git submodule update --init

Issue: Submodule Files Missing

Sometimes, after initializing a submodule, submodule's files may be missing. This can happen if submodule's files were not properly included in initial clone.

Solution − Run git submodule update --init --recursive

This command will update all submodules, including those that were not initialized properly during initial clone.

Issue: Submodule Branches Out of Sync

If branch of a submodule becomes out of sync with parent repository, you may encounter conflicts when updating submodule.

Solution − Update submodule branch

To update submodule branch, you can use git submodule update --remote command with --rebase option. This command will fetch latest changes from submodule repository and rebase changes onto current branch.

Issue: Submodule Not Updating

Sometimes, updating a submodule with git submodule update command may not result in expected changes.

Solution − Check submodule branch and commit

Make sure submodule is on correct branch and commit. You can check submodule's branch and commit with git submodule status command. If submodule is not on expected branch or commit, you can use git submodule update --remote command with --merge option to update submodule to latest commit.

Conclusion

In this article, we have explored how to add, update, and remove Git submodules. Submodules are a powerful feature of Git that allows you to reuse code from other repositories within your own project. By understanding how to work with submodules, you can improve the organization and maintainability of your code.

Remember to use git submodule add, git submodule update, git submodule deinit, and git rm commands to manage submodules effectively. Keep in mind that submodules can be complex, so it's important to take time to understand how they work and how to use them properly.