How to Perform Git Submodule Checkout

September 7, 2022

Introduction

Git submodules help maintain complex projects by allowing independent repositories to exist as subdirectories within a wider project repository. This Git feature allows each repository's version history to remain separate while making the code easily accessible inside the main project.

In this tutorial, you will learn how to obtain the contents of a submodule using the command line and how to automate the checkout process with GitHub actions.

How to perform Git submodule checkout.

Prerequisites

  • Git installed.
  • GitHub account for creating GitHub actions.

Note: For instructions on how to set up your Git environment, read the Install Git and Create a GitHub account section of our beginner's guide to Git.

Submodule Checkout Using Git CLI

The command-line procedure to obtain repositories containing submodules is the same as the general checkout procedure. However, initializing submodules on a local machine requires updating the content of submodule directories, as listed in step 3 below.

To check out submodules via CLI:

1. Use git clone to copy the repository content to the local machine:

git clone [repository-url]
Cloning a Git repository containing submodules.

The cloned copy contains all the files of the original repository, but the directories representing submodules remain empty until they are initialized.

2. Navigate to the main repository directory.

cd [directory]

3. Update the content of submodule directories with the git submodule update command. Execute the command from the main project directory.

git submodule update --init --recursive

The --init flag initializes the submodules before the update. The --recursive option searches for nested submodules and ensures they are updated too.

Updating submodules in a git repository.

The command output in the example above shows that Git successfully registered and checked out the two submodules located in the main repository.

Note: For a more comprehensive guide to obtaining Git submodules with CLI commands, read How to Pull the Latest Git Submodule.

Submodule Checkout Using GitHub Actions

Using the GitHub Actions CI/CD platform, you can automate submodule checkout by including it in your pipeline. The following sections present three methods to configure a submodule checkout job in your workflow.

The methods include:

  • Executing the CLI command in a run step.
  • Specifying the submodules input.
  • Using an extension available in the GitHub Marketplace.

Run Command Directly

Automate submodule checkout by integrating the git submodule update CLI command into your GitHub Actions workflow. The following example defines a job named submodule-checkout that features two steps.

  • The first step uses the checkout action to obtain the repository contents.
  • The second step runs the command that initiates and updates the submodules.
jobs: 
  submodule-checkout:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v2
    - name: Checkout submodules
      run: git submodule update --init --recursive

Use submodules Input

Another way to check out submodules in a repository is to include the submodules input in the step that calls the checkout action. The example job below checks out the repository and its submodules in a single step.

jobs: 
  submodule-checkout:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository and submodules
      uses: actions/checkout@v2
      with:
        submodules: recursive

Use git Actions Extension

The git Actions extension allows any Git command to be executed inside a workflow. Install the extension by adding the following section to your YML file:

- name: git Actions
  uses: srt32/[email protected]

When calling this action in your job configuration, pass the git submodule update command using the args keyword, as in the example below.

jobs: 
  submodule-checkout:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v2
    - name: Checkout submodules
      uses: srt32/[email protected]
      with:
        args: git submodule update --init --recursive

Conclusion

After reading this tutorial, you should know how to check out submodule content for your project. The article covered the command-line approach to checking out submodules and offered ways to include the procedure in your GitHub Actions workflow.

If you are new to Git, read our How to Use Git beginner's guide and get to know the platform. For a detailed introduction to Git submodules, read Git Submodule Guide.

Was this article helpful?
YesNo
Marko Aleksic
Marko Aleksić is a Technical Writer at phoenixNAP. His innate curiosity regarding all things IT, combined with over a decade long background in writing, teaching and working in IT-related fields, led him to technical writing, where he has an opportunity to employ his skills and make technology less daunting to everyone.
Next you should read
How Does Git Work?
September 16, 2021

Having a good understanding of Git is essential if you want to code and work on a collaborative software development project. Learn how Git works and how to...
Read more
Git Fetch: Definition & Examples
December 8, 2021

The git fetch command downloads objects to the local machine without overwriting existing local code in the current branch. The command pulls a record...
Read more
How to Restore a Git Repository
August 1, 2022

Accidentally deleted a critical Git repository when cleaning up? Forcefully pushed a new commit before fetching the latest version on a different machine? This article provides two possible methods...
Read more
Git Checkout Tag
December 2, 2021

Git tags help developers create source points during development. The primary purpose is to mark and reference release versions. Checkout works with any Git object, including tags. This tutorial will show you how to check out...
Read more