How do I "git clone" a repo, including its submodules?

With version 2.13 of Git and later, --recurse-submodules can be used instead of --recursive:

git clone --recurse-submodules -j8 git://github.com/foo/bar.git
cd bar

^{Editor’s note: -j8 is an optional performance optimization that became available in version 2.8, and fetches up to 8 submodules at a time in parallel — see man git-clone.}

With version 1.9 of Git up until version 2.12 (-j flag only available in version 2.8+):

git clone --recursive -j8 git://github.com/foo/bar.git
cd bar

With version 1.6.5 of Git and later, you can use:

git clone --recursive git://github.com/foo/bar.git
cd bar

For already cloned repos, or older Git versions, use:

git clone git://github.com/foo/bar.git
cd bar
git submodule update --init --recursive

You have to do two things before a submodule will be filled:

git submodule init 
git submodule update

Git 2.23 (Q3 2019): if you want to clone and update the submodules to their latest revision:

git clone --recurse-submodules --remote-submodules <repo-URL>

If you just want to clone them at their recorded SHA1:

git clone --recurse-submodules <repo-URL>

See below.

Note that Git 2.29 (Q4 2020) brings a significant optimization around submodule handling.

See commit a462bee (06 Sep 2020) by Orgad Shaneh (orgads).
^{(Merged by Junio C Hamano -- gitster -- in commit 2ce9d4e, 18 Sep 2020)}

submodule: suppress checking for file name and ref ambiguity for object ids

^{Signed-off-by: Orgad Shaneh}

The argv argument of collect_changed_submodules() contains only object ids (the objects references of all the refs).

Notify setup_revisions() that the input is not filenames by passing assume_dashdash, so it can avoid redundant stat for each ref.

Also suppress refname_ambiguity flag to avoid filesystem lookups for each object. Similar logic can be found in cat-file, pack-objects and more.

This change reduces the time for git fetch^(man) in my repo from 25s to 6s.

Original answer 2010

As joschi mentions in the comments, git submodule now supports the --recursive option (Git1.6.5 and more).

If --recursive is specified, this command will recurse into the registered submodules, and update any nested submodules within.

See Working with git submodules recursively for the init part.
See git submodule explained for more.

With version 1.6.5 of git and later, you can do this automatically by cloning the super-project with the –-recursive option:

git clone --recursive git://github.com/mysociety/whatdotheyknow.git

Update 2016, with git 2.8: see "How to speed up / parallelize downloads of git submodules using git clone --recursive?"

You can initiate fetching the submodule using multiple threads, in parallel.
For instances:

git fetch --recurse-submodules -j2

Even better, with Git 2.23 (Q3 2019), you can clone and checkout the submodule to their tracking branch in one command!

See commit 4c69101 (19 May 2019) by Ben Avison (bavison).
^{(Merged by Junio C Hamano -- gitster -- in commit 9476094, 17 Jun 2019)}

clone: add --remote-submodules flag

When using git clone --recurse-submodules there was previously no way to pass a --remote switch to the implicit git submodule update command for any use case where you want the submodules to be checked out on their remote-tracking branch rather than with the SHA-1 recorded in the superproject.

This patch rectifies this situation.
It actually passes --no-fetch to git submodule update as well on the grounds the submodule has only just been cloned, so fetching from the remote again only serves to slow things down.

That means:

--[no-]remote-submodules:

All submodules which are cloned will use the status of the submodule’s remote-tracking branch to update the submodule, rather than the superproject’s recorded SHA-1. Equivalent to passing --remote to git submodule update.

jhu notes in the comments:

If you want to use git clone --recurse-submodules --remote-submodules <repo-URL> to clone and update to the latest version, your submodules must either:

1. have a branch master, assumed by git when running the above, or
2. record a valid branch name in the .gitmodules of the cloned repo. > Otherwise you will get an error about a missing head, and cloning will fail.
   So if you have a submodule without branch master, say submodule sub with branch main, run in the root dir of the cloned repo git config -f .gitmodules submodule.sub.branch main and push your changes to the remote.

You can use this command to clone your repo with all the submodules:

git clone --recursive YOUR-GIT-REPO-URL

Or if you have already cloned the project, you can use:

git submodule init
git submodule update

[Quick Answer]

After cloning the parent repo (including some submodule repos), do the following:

git submodule update --init --recursive

Use this command to clone repo with all submodules

git clone --recurse-submodules git@gitlab.staging-host.com:yourproject

To update code for all submodules

git submodule update --recursive --remote

If your submodule was added in a branch be sure to include it in your clone command...

git clone -b <branch_name> --recursive <remote> <directory>

Try this:

git clone --recurse-submodules

It automatically pulls in the submodule data assuming you have already added the submodules to the parent project.

I think you can go with 3 steps:

git clone
git submodule init
git submodule update

You can use the --recursive flag when cloning a repository. This parameter forces git to clone all defined submodules in the repository.

git clone --recursive git@repo.org:your_repo.git

After cloning, sometimes submodules branches may be changed, so run this command after it:

git submodule foreach "git checkout master"

late answer

// git CLONE INCLUDE-SUBMODULES ADDRESS DESTINATION-DIRECTORY
git clone --recursive https://USERNAME@bitbucket.org/USERNAME/REPO.git DESTINATION_DIR

As I just spent a whole hour fiddling around with a friend: Even if you have Admin rights on BitBucket, always clone the ORIGINAL repository and use the password of the one who owns the repo. Annoying to find out that you ran into this minetrap :P

Try this for including submodules in git repository.

git clone -b <branch_name> --recursive <remote> <directory>

or

git clone --recurse-submodules

Just do these in your project directory.

$ git submodule init
$ git submodule update

Submodules parallel fetch aims at reducing the time required to fetch a repositories and all of its related submodules by enabling the fetching of multiple repositories at once. This can be accomplished by using the new --jobs option, e.g.:

git fetch --recurse-submodules --jobs=4

According to Git team, this can substantially speed up updating repositories that contain many submodules. When using --recurse-submodules without the new --jobs option, Git will fetch submodules one by one.

Source: http://www.infoq.com/news/2016/03/git28-released

If it is a new project simply you can do like this :

$ git clone --recurse-submodules https://github.com/chaconinc/YourProjectName 

If it is already installed than :

$ cd YourProjectName (for the cases you are not at right directory) 
$ git submodule init
$ git submodule update

I had the same problem for a GitHub repository. My account was missing SSH Key. The process is

1. Generate SSH Key
2. Adding a new SSH key to your GitHub account

Then, you can clone the repository with submodules (git clone --recursive YOUR-GIT-REPO-URL)

or

Run git submodule init and git submodule update to fetch submodules in already cloned repository.

Try this.

git clone -b <branch_name> --recursive <remote> <directory>

If you have added the submodule in a branch make sure that you add it to the clone command.

I recommend:

# - git submodule init initializes your local configuration file to track the submodules your repository uses, it just sets up the configuration so that you can use the git submodule update command to clone and update the submodules.
git submodule init
# - git submodule update --init initializes your local configuration file and clones the submodules for you, using the commit specified in the main repository.
#   note, command bellow will not pull the right branch -- even if it's in your .gitmodules file, for that you need remote. Likely because it looks at the origin (pointer to remote) in github for the available branches.
#   note, bellow pulls the submodules if you didn't specify them when cloning parent project, ref: https://youtu.be/wTGIDDg0tK8?t=119
git submodule update --init

if you have a specific branch for your submodules then change it to:

# - git submodule init initializes your local configuration file to track the submodules your repository uses, it just sets up the configuration so that you can use the git submodule update command to clone and update the submodules.
git submodule init

# - The --remote option tells Git to update the submodule to the commit specified in the upstream repository, rather than the commit specified in the main repository.
#git submodule update --init --remote
git submodule update --init --recursive --remote meta-dataset

For a full example that was testing:

# decided against this because it seems complicated

# - note to clone uutils with its submodule do (cmd not tested):
cd $HOME
git clone --recurse-submodules git@github.com:brando90/ultimate-utils.git

# - git submodules
cd $HOME/diversity-for-predictive-success-of-meta-learning

# - in case it's needed if the submodules bellow have branches your local project doesn't know about from the submodules upstream
git fetch

# -- first repo
# - adds the repo to the .gitmodule & clones the repo
git submodule add -f -b hdb --name meta-dataset git@github.com:brando90/meta-dataset.git meta-dataset/

# - ref for init then update: https://stackoverflow.com/questions/3796927/how-do-i-git-clone-a-repo-including-its-submodules/3796947#3796947
#git submodule init
#git submodule update

# - git submodule init initializes your local configuration file to track the submodules your repository uses, it just sets up the configuration so that you can use the git submodule update command to clone and update the submodules.
git submodule init
# - git submodule update --init initializes your local configuration file and clones the submodules for you, using the commit specified in the main repository.
#   note, command bellow will not pull the right branch -- even if it's in your .gitmodules file, for that you need remote. Likely because it looks at the origin (pointer to remote) in github for the available branches.
#   note, bellow pulls the submodules if you didn't specify them when cloning parent project, ref: https://youtu.be/wTGIDDg0tK8?t=119
git submodule update --init
# - The --remote option tells Git to update the submodule to the commit specified in the upstream repository, rather than the commit specified in the main repository.
#git submodule update --init --remote
git submodule update --init --recursive --remote meta-dataset

# - check we are using the right branch https://stackoverflow.com/questions/74998463/why-does-git-submodule-status-not-match-the-output-of-git-branch-of-my-submodule
git submodule status
cd meta-dataset
git branch  # should show hdb
cd ..

# pip install -r $HOME/meta-dataset/requirements.txt

# -- 2nd repo, simplified commands from above
git submodule add -f -b hdb --name pytorch-meta-dataset git@github.com:brando90/pytorch-meta-dataset.git pytorch-meta-dataset/

git submodule init
git submodule update --init --recursive --remote meta-dataset

# - check it's in specified branch
git submodule status
cd pytorch-meta-dataset
git branch  # should show hdb
cd ..

# pip install -r $HOME/pytorch-meta-dataset/requirements.txt

If you want to tell your git client to do all actions with --recurse-submodules then you can set this to your git config:

git config submodule.recurse true

See: https://www.git-scm.com/docs/git-config#Documentation/git-config.txt-submodulerecurse

If the submodules are private submodules you can use credential store so that it also clones its private submodules recursively.

USER=${GITHUB_ACTOR}
TOKEN=${{ secrets.JEKYLL_GITHUB_TOKEN }}

git config --global credential.helper store
echo "https://${USER}:${TOKEN}@github.com" > ~/.git-credentials

git clone --recurse-submodules -j8 git://github.com/foo/bar.git
cd bar

I use it to clone my submodules where the private one is in 5th level deep. Please allow me to show you how it goes in action:

You can copy clone url from github.

Then use:

git clone --recursive <url of clone copied above>

git submodule init
git submodule update

or maybe:

git stash -u
git pull origin master
git stash p

When you clone a repository with submodules, you need to initialize and update the submodules separately. Here's how you can pull a repository with submodules and update them:

1. Open a terminal on your Ubuntu system.

2. Change to the directory where your repository is located:

   cd /path/to/repository
   

3. Use the following command to clone the repository and its submodules:

   git clone --recurse-submodules <repository_url>
   

   Replace <repository_url> with the actual URL of your repository.

   The --recurse-submodules flag ensures that the submodules are also cloned along with the main repository.

4. If you have already cloned the repository without initializing and updating the submodules, navigate to the repository directory and initialize the submodules:

   cd /path/to/repository
   git submodule init
   

5. Update the submodules to retrieve the latest changes from their respective repositories:

   git submodule update
   

   If you want to update the submodules recursively (i.e., update submodules within submodules), you can add the --recursive flag:

   git submodule update --recursive
   

   This command will fetch the latest commits for each submodule.

After completing these steps, your repository and its submodules should be up to date. You can now use the files from the submodules as expected.

How do I "git clone" a repo, including its submodules?

Is there any way to specify this behavior as default in your git repository, so that less-informed cloners will automatically get an initialized submodule?

(I made it as a standalone answer because I think this IS important in the git)

Sadly, but there is plenty cases where that less-informed cloners will ANYWAY miss the externals:

• vcstool (https://github.com/dirk-thomas/vcstool)
• git-subrepo (https://github.com/ingydotnet/git-subrepo)
• git links (https://github.com/chronoxor/gil)
• .gitsvnextmodules (handled by smartgit).
• git-externals (https://github.com/develer-staff/git-externals)
• git x-modules (https://gitmodules.com/)
• ... and so on ...

Note:
Such projects as vcstool, git-subrepo and gil are using their own way to store external dependencies list and supersedes the clone operation, so the end repository by default won't has the .submodules file at all.
Here is some clarification of raised problem in the git internals:
nested submodules detection w/o .gitmodules file :
https://lore.kernel.org/git/1716310675.20230122233403@inbox.ru

As a backup, inability to make a bare clone (--bare) + full recursive (--recursive) to mirror (--mirror) all references (not just all externals):
Clone git repository with --recursive and --bare

So with the git there is no a builtin way to take the external dependencies absolutely completely. Which means in turn there is no a single way to backup any random git repository absolutely completely.