In software development, we rarely build projects entirely from scratch. We leverage open-source libraries and frameworks to accelerate development and avoid reinventing the wheel. But managing these dependencies can quickly become a tangled mess, especially as projects grow and dependencies multiply.

This blog post explores a simple yet powerful Git feature called git-submodule, which streamlines dependency management and keeps your codebase clean and organised.

The Downside of the Manual Approach

Many developers resort to simply manually cloning and directly pushing dependency code into their main project’s codebase. While this may seem convenient at first, it creates several challenges:

• Version Control Issues: Updating dependencies becomes a manual process, increasing the risk of compatibility issues and security vulnerabilities.
• Upstream Changes: New features or bug fixes in the original library require manual integration, which is time-consuming and error-prone.

Introducing Git Submodules

git submodules allow you to integrate external Git repositories (containing your dependencies) directly into your project. This creates a modular approach with several benefits:

• Independent Updates: You can update submodules individually without affecting your main project code.
• Version Tracking: Submodules track the specific commit hash of the dependency you’re using, ensuring consistency and reproducibility.
• Modular Codebase: Your project remains clean and organised, with dependencies clearly separated from your core code.

Putting Git Submodules into Action

Let’s walk through a practical example. Imagine a project named “submodule-demo” that relies on two libraries:

• FastLED: A library for controlling LEDs
• PubSubClient: A library for implementing an MQTT client

Here’s how to leverage git-submodules to manage these dependencies:

1. Project Structure: You can create a dedicated directory (e.g., lib) within your project to store dependencies.
2. Adding Submodules: Use the git submodule add command to specify the URL of the external repository and the desired submodule path:

cd your_project/lib
git submodule add https://github.com/iayanpahwa/FastLED.git
git submodule add https://github.com/iayanpahwa/pubsubclient.git

This fetches the code from the specified repositories and stores them within the lib directory.

3. Initialising and Updating: Anyone cloning your project can easily initialise and update the submodules using the following commands:

git clone <your_project_URL>
cd <your_project_URL>
git submodule init
git submodule update

Alternatively, you can use the --recursive flag during cloning to automate these steps:

git clone --recursive <your_project_URL>

4. Version Control: Git submodules record the specific commit hash used from each dependency. This ensures everyone working on the project uses the same library version, promoting consistency and preventing compatibility issues.

Beyond the Basics:

While submodules default to fetching the latest commit from the dependency’s main branch, you can specify a different branch or commit hash. Refer to the official Git documentation (https://git-scm.com/book/en/v2/Git-Tools-Submodules) for details on advanced usage.

Key Takeaways

By embracing git submodules, you can effectively manage dependencies, improve code organization, and streamline project collaboration. This approach promotes a more modular and maintainable codebase, saving you time and headaches in the long run.

Feel free to explore our other blog posts on Git internals for further insights!

Git Internals Part 1- List of basic Concepts That Power your .git Directory

Git Internals Part 2: How does Git store your data?

Git Internals Part 3: Understanding the staging area in Git

NEW Developer Nation survey is live! Participate, shape the trends in software development, and win big. Start here!