How to Add and Update Git Submodules

Git submodules are a great way to manage dependencies inside your Git project. They allow you to include other Git repositories within your main repository. This keeps your projects organized and makes it easier to manage external code.

This guide will show you how to add and update Git submodules in your repository. 

With so much to explore, let’s dive right in!

How to Add a Git Submodule

Follow the below steps to add Git submodules:

1. Preparing Your Repository

Before adding a submodule, ensure your main repository is set up. If you don’t have one yet, you can create it with the following command:

 # git init my-main-repo && cd my-main-repo

This command creates a new Git repository called my-main-repo and navigates into it.

2. Adding the Submodule

To add a submodule, use the git submodule add command. Here’s the syntax:

 # git submodule add repository-url path-to-submodule

• repository-url: This is the repository URL you want to add as a submodule.
• path-to-submodule: This is where the submodule will be placed within your project.

For instance, if you want to add a submodule from https://github.com/example/example-repo.git to a folder called libs/example-repo, you would run:

 # git submodule add https://github.com/example/example-repo.git libs/example-repo

After running this command, you’ll see output like this:

Cloning into 'libs/example-repo'...
remote: Counting objects: 42, done.
remote: Compressing objects: 100% (21/21), done.
remote: Total 42 (delta 0), reused 42 (delta 0), pack-reused 0
Unpacking objects: 100% (42/42), done.

This shows that the submodule was successfully added and cloned into your project.

How to Update a Git Submodule

Over time, the submodule’s repository might get updated. You’ll need to bring those updates into your main project. Here’s how you can do it.

1. Updating to the Latest Commit

To update a submodule to the latest commit, use the following command:

 # git submodule update --remote

This tells Git to fetch the newest changes from the submodule’s repository. You should see output like this:

Submodule path 'libs/example-repo': checked out 'abcd1234'

The above output shows that the submodule has been updated to a newer commit.

2. Committing Submodule Changes

Once the submodule is updated, you’ll need to commit these changes in your main repository. Here’s how:

 # git add libs/example-repo
 # git commit -m "Updated submodule to latest version"
 # git push

The git add command stages the submodule update, while git commit records the change. Finally, git push sends the changes to the remote repository.

Here’s an example of what the output might look like:

[main 1234567] Updated submodule to latest version
 1 file changed, 1 insertion(+), 1 deletion(-)

Conclusion

In conclusion, Git submodules are a powerful way to handle external dependencies. By following this guide, you should now be able to add and update submodules easily. Make sure to commit and push your changes regularly, and don’t forget to keep your submodules updated.

FAQs

1. How do I update all Git submodules in a project?

To update all submodules in a project at once, run git submodule update --remote --merge command.

2. What happens if I don’t update my Git submodule?

If you don’t update your Git submodule, you will not have the latest changes from the submodule’s repository. This might cause issues if the submodule code is essential for your project.

3. How do I remove a Git submodule?

To remove a submodule, delete its entry in .gitmodules, remove the submodule directory, and clear the cache with git rm and rm -rf .git/modules/path/to/submodule.

4. How do I update all Git submodules in a project?

You can update all submodules at once using git submodule update --remote --merge.

5. What’s the difference between a submodule and a subtree?

Submodules keep repositories separate, while subtrees merge an external repository into the main repository, allowing more seamless integration.