+++
date = "2020-03-09"
title = "The git submodule cheat sheet"
tags = ["git"]
description = "git submodules are very handy, but how do you get rid of one?"
+++

A git submodule, in its essence, is a reference to another git repository. It's a great
way to include vendor code (like plugins or themes) into your own code base. This post
contains some examples on how to use git submodules effectively. 

## Add a submodule

You need to know the remote git repository url and where you want to place that it in your repository. 

```bash
git submodule add https://example.com/submodule-repo.git path/to/submodule
git add . 
git commit -m "adds submodule path/to/submodule"
```

## Cloning a project with submodules

When you clone a repository that contains submodules there are a few extra steps to be taken.

```bash
git clone http://example.com/repo.git repo
cd repo
git submodule init
git submodule update
```

If you're sure you want to fetch all submodules (and their submodules), you can also use this
fancy one-liner:

```bash
git clone --recurse-submodules http://example.com/repo.git
```

## Update your submodule

If you're simply tracking the `master` branch for the submodule, you can suffice with
a simple `fetch` and `merge`.

```bash
cd path/to/submodule
git fetch
git merge origin/master
```

If you're in a hurry, you can streamline this for all submodules in your repo with: 

```bash
git submodule update --remote --recursive
```

Don't forget to commit this change to your own repo, so others are locked to this new version of the
submodule as well.

## Track a specific branch of version

The repo for your submodule may have a specific branch (e.g. `stable`) or tag you want to track, instead
of `master`.

```bash
git config -f .gitmodules submodule.path/to/submodule.branch stable
git submodule update --remote
```

Again, don't forget to commit your changes to `.gitmodules` to send this change to other contributors
to you repository.

## Remove a submodule

Removing a git submodule consists of two steps: removing the reference and removing the locally cached 
version.

```bash
git submodule deinit path/to/submodule
git rm path/to/submodule
git commit -m "removes submodule path/to/submodule"

rm -rf .git/modules/path/to/submodule
```

## Bonus: see submodule status in `git status`

You can configure git to show a submodule summary when you do a `git status`. There is a small
performance trade-off here, but it might be useful to you.

```bash
git config status.submodulesummary 1
```