How to Perform Git Submodule Checkout

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.

Prerequisites

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

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]

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.

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

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/git-actions@v0.0.3

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/git-actions@v0.0.3
      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.