With the `git submodule` command, you can include one Git repository inside another as a subdirectory. This is most useful when you want to reuse shared code — such as a library or framework — across multiple projects without copying it.

## Adding a submodule

To add a submodule, run the following from the root of your repository:

```bash
$ git submodule add https://github.com/myotherproject/myotherrepository subfolder
Cloning into 'subfolder'...
remote: Counting objects: 11, done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 11 (delta 0), reused 11 (delta 0)
Unpacking objects: 100% (11/11), done.
Checking connectivity... done.
```

By default, Git creates a folder named after the remote repository. You can override this by specifying a different folder name after the URL, as shown above.

This will create (or update) a `.gitmodules` file that records the submodule's local path and remote URL. Once you've added the submodule, commit and push the change:

```bash
$ git commit -am "Added myotherrepository submodule"
[main 1234abc] Added myotherrepository submodule
 2 files changed, 4 insertions(+)
 create mode 100644 .gitmodules
 create mode 160000 subfolder
$ git push origin main
```

## Cloning a repository with submodules

When you [`clone`](/git/cloning-an-existing-repository) a repository that contains submodules, the submodule directories will be empty by default. To clone everything in one step, use the `--recurse-submodules` flag:

```bash
$ git clone --recurse-submodules https://github.com/myproject/myrepository
```

This clones the main repository and then automatically initialises and fetches all of its submodules.

## Initialising submodules after cloning

If you've already cloned a repository without `--recurse-submodules`, you can set up the submodules afterwards with two commands:

```bash
$ git submodule init
$ git submodule update
```

`git submodule init` registers the submodule paths from `.gitmodules` into your local Git config. `git submodule update` then fetches the correct commit for each submodule and checks it out.

## Updating a submodule

If the remote repository for a submodule has been updated and you want to pull the latest changes into your project:

```bash
$ git submodule update --remote --merge
```

This fetches the latest commit from each submodule's [`remote`](/git/commands/git-remote) and merges it. You'll then need to commit and push the change so other collaborators pick it up.

## Removing a submodule

Removing a submodule takes a few steps. First, unregister the submodule and remove its files:

```bash
$ git submodule deinit -f subfolder
$ git rm -f subfolder
```

Then clean up the leftover Git internal data:

```bash
$ rm -rf .git/modules/subfolder
```

Finally, commit the removal:

```bash
$ git commit -m "Removed subfolder submodule"
```

This fully removes the submodule entry from `.gitmodules`, your `.git/config`, and the working directory.

If you run into issues with submodule paths during deployment, see our FAQ on [adding files at a submodule path](/git/faqs/add-files-git-submodule-path).

---

[DeployHQ](https://www.deployhq.com) supports deploying repositories that use submodules — it can automatically fetch and deploy submodule contents alongside your main project.