If you cloned a Git repository on your Mac and its submodule folders are empty, open Terminal, move into the repository, and run git submodule update --init --recursive. This initializes the submodules recorded by the project, checks out the commits the parent repository specifies, and also handles nested submodules. You need Git installed and access to each submodule’s remote repository.

Run the initialization command in the cloned repository

Open Terminal and use cd to enter the directory created by git clone. If the directory name contains spaces, put it in quotes, for example:

cd "$HOME/Projects/My Project"
git submodule update --init --recursive

Replace the example path with the actual location of your clone. You can also type cd , drag the repository folder from Finder into the Terminal window to insert its path, and press Return. Apple documents Terminal as the macOS command-line interface and identifies zsh as its default shell; the commands above use ordinary shell syntax that works in zsh. Open or quit Terminal on Mac, Change the default shell in Terminal on Mac

Git’s official documentation explains that --init initializes submodules that have not been initialized, while --recursive also updates nested submodules. update fetches missing commits and checks out the revision expected by the parent repository. git-submodule documentation

Check whether submodules were initialized

To see what the parent repository records, run:

git submodule status --recursive

A submodule status line normally shows a commit ID and path. A leading minus sign means that submodule is not initialized; a plus sign means its checked-out commit differs from the commit recorded by the parent repository; and U indicates a conflict. The recursive status option also reports nested submodules. git-submodule documentation

If the output lists paths with minus signs, run the initialization command again from the repository’s top-level directory. If no submodules appear, check whether the current clone actually contains a .gitmodules file and whether you are in the intended repository. A repository may have no submodules, or the commit you cloned may not record any.

Understand which revision gets checked out

A submodule is its own Git repository, and the parent repository records a specific commit for it. The regular update behavior checks out that recorded commit, commonly leaving the submodule on a detached HEAD. That is expected when you are setting up the parent project: it reproduces the version the parent selected. Git - Submodules, git-submodule documentation

For that reason, don’t add --remote when your goal is simply to initialize the clone. That option uses a submodule’s remote-tracking branch instead of the commit recorded by the parent, which can produce a different version. If you intend to develop inside a submodule, first learn the project’s workflow; switching to a branch or making commits inside it is separate from initializing it.

If the command fails

Submodule updates need to contact the remotes listed in the project’s configuration, so a network failure or missing access can prevent a checkout. Private submodules may require you to authenticate with the hosting service or have permission to the repository. If Git reports that it cannot find a repository or resolve a host, confirm your network connection and access, then retry.

If a project recently changed a submodule URL, git submodule sync --recursive can synchronize the local URL configuration from .gitmodules; follow it with git submodule update --init --recursive. Git documents sync for updating URL configuration for submodules that are already initialized or freshly added. git-submodule documentation

If you already have local work inside a submodule, inspect it before forcing any update or switching revisions. The standard initialization command does not ask Git to force-check out over local changes; resolve or preserve that work deliberately rather than deleting the directory as a troubleshooting shortcut.

Once git submodule status --recursive shows the expected commit IDs without leading minus signs, the repository’s recorded submodule revisions have been checked out. Keep working from the parent repository unless the project’s instructions call for separate work inside a submodule.

Sources