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.
- 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:
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.
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
--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.
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
- Specifying the
- 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
checkoutaction 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: email@example.com
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: firstname.lastname@example.org with: args: git submodule update --init --recursive
Note: Learn how to add, update or remove Git submodules.
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.