Sling Academy
Home/DevOps/Working with Git submodules: A practical guide (with examples)

Working with Git submodules: A practical guide (with examples)

Last updated: January 27, 2024

Understanding Git Submodules

Git submodules allow you to keep a Git repository as a subdirectory of another Git repository. This is ideal for projects that depend on certain versions of external repositories. By using submodules, you can track the external repositories in a given commit.

Managing project dependencies can be a complex task, especially when your projects depend on external code repositories. One of the common solutions to this challenge in Git-centric workflows is using Git submodules. In this guide, we’ll explore the ins and outs of working with Git submodules and demonstrate practical usage with examples.

Adding a Submodule

To add a new submodule to your project, use the following command:

git submodule add  

This creates a new directory at the specified path containing the content of the added submodule. Furthermore, Git will add a `.gitmodules` file to your repository, which stores the mapping between the project’s URL and the local subdirectory you’ve pulled it into.

Initializing Submodules

After cloning a repository with submodules, you need to initialize them:

git submodule init

This initializes your local configuration file, and Git is now aware that there are submodules that need to be checked out.

Updating Submodules

To update your submodules, use:

git submodule update

This will fetch and update the files in the submodules to match the version described in the main repository.

Advanced Submodule Management

Managing submodules involves a variety of tasks, such as updating to the latest commit in submodule’s master branch:

cd  git checkout master git pull

You should then commit this change in the main repository to track the latest commit of the submodule.

Working with Branches in Submodules

Submodules can be checked out at any branch or tag. To work on a specific branch:

cd  git checkout 

Then commit and push your changes as you would with any normal Git repository.

Removing a Submodule

To remove a submodule you no longer need, perform the following steps:

git submodule deinit  git rm  rm -rf .git/modules/

After these commands, you can commit the changes to remove the submodule reference entirely from your project.

Best Practices

When working with submodules:

  • Always push your submodule changes before pushing the changes to the main project.
  • Avoid adding submodules inside of submodules.
  • Keep your submodules at specific tags or commits for stability.

Common Issues and Solutions

Dealing with submodules can sometimes lead to confusion or additional overhead:

  • If a submodule is not initiating correctly, ensure the `.gitmodules` file is set up correctly and that you run `git submodule update –init –recursive`.
  • To track submodule changes in a branch, remember to add and commit the changes to the submodule before commiting the changes in the main repository.

Conclusion

Incorporating Git submodules into your development workflow can greatly improve the management of external code dependencies. By following the steps lined out in this guide and considering best practices, you can efficiently work with submodules and ensure a more integrated and trackable codebase. Even though they introduce complexity, submodules provide a powerful way to incorporate and version external code within your projects.

Next Article: Git Pull Error: ‘unable to update local ref’ (4 solutions)

Previous Article: Git .gitignore: Excluding a folder but including a subfolder

Series: Git & GitHub Tutorials

DevOps

You May Also Like

  • How to reset Ubuntu to factory settings (4 approaches)
  • Making GET requests with cURL: A practical guide (with examples)
  • Git: What is .DS_Store and should you ignore it?
  • NGINX underscores_in_headers: Explained with examples
  • How to use Jenkins CI with private GitHub repositories
  • Terraform: Understanding State and State Files (with Examples)
  • SHA1, SHA256, and SHA512 in Terraform: A Practical Guide
  • CSRF Protection in Jenkins: An In-depth Guide (with examples)
  • Terraform: How to Merge 2 Maps
  • Terraform: How to extract filename/extension from a path
  • JSON encoding/decoding in Terraform: Explained with examples
  • Sorting Lists in Terraform: A Practical Guide
  • Terraform: How to trigger a Lambda function on resource creation
  • How to use Terraform templates
  • Understanding terraform_remote_state data source: Explained with examples
  • Jenkins Authorization: A Practical Guide (with examples)
  • Solving Jenkins Pipeline NotSerializableException: groovy.json.internal.LazyMap
  • Understanding Artifacts in Jenkins: A Practical Guide (with examples)
  • Using Jenkins with AWS EC2 and S3: A Practical Guide