# Git Submodules

## On this page

- [1. Why submodules?](#why)
- [2. Key concepts](#terms)
- [3. Cloning a repo with submodules](#clone)
- [4. Adding ERC-Protobufs as a submodule](#add)
- [5. Updating ERC-Protobufs (pinning a new commit)](#update)
- [6. Branches, detached HEAD, and what “pinned” means](#branches)
- [7. Common mistakes](#mistakes)
- [8. Command cheat sheet](#cheatsheet)

## 1) Why submodules?

<span style="white-space: pre-wrap;">A </span>[git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules)<span style="white-space: pre-wrap;"> lets one repository “mount” another repository at a specific commit. That sounds fancy, but it’s really just Git saying: “this folder is a separate repo, and we are pinning it to a specific SHA because reproducibility is not optional.”</span>

We use this for shared code/assets that:

- should be versioned and reviewed independently,
- <span style="white-space: pre-wrap;">must be </span>**pinned**<span style="white-space: pre-wrap;"> (reproducible builds, fewer “works on my machine” sightings),</span>
- is shared across multiple firmware/software repositories.

**RoboTeam example:**<span style="white-space: pre-wrap;"> </span>**ERC-Protobufs**<span style="white-space: pre-wrap;"> can be shared between embedded firmware, tooling, and PC-side code. Pinning ensures everyone generates/uses the same message definitions — which is what prevents “my robot speaks protobuf dialect #3” incidents.</span>

## 2) Key concepts

<table id="bkmrk-termwhat-it-meanswhy"><colgroup><col style="width: 192px;"></col><col></col><col></col></colgroup><tbody><tr><th>Term

</th><th>What it means

</th><th>Why care about it?

</th></tr><tr><td>`<span class="editor-theme-code">.gitmodules</span>`

</td><td>A file in the parent repo that stores submodule name/path/URL.

</td><td>This is what gets committed so everyone else can actually fetch the submodule without guessing.

</td></tr><tr><td>“Pinned commit”

</td><td>The parent repo records a specific commit SHA for the submodule.

</td><td>Builds are reproducible; updating is an explicit change (and therefore reviewable).

</td></tr><tr><td>Detached HEAD

</td><td>By default, a submodule checks out the exact pinned commit, not a branch.

</td><td>Normal. It looks scary the first time, but it just means “you’re on a commit, not a branch.”

</td></tr><tr><td>`<span class="editor-theme-code">git submodule update</span>`

</td><td>Checks out the submodule commit referenced by the parent repo.

</td><td>Use after switching branches or pulling changes, because submodules do not magically follow along.

</td></tr></tbody></table>

## 3) Cloning a repo with submodules

<span style="white-space: pre-wrap;">If a repository already uses </span>[ERC-Protobufs](https://github.com/RoboTeamTwente/ERC-Protobufs/tree/aa3ea9bfd9cbe811f719f328bf4927445820d1f1)<span style="white-space: pre-wrap;"> as a submodule, you must fetch it after cloning. Otherwise Git will politely give you an empty folder and let you discover the problem at build time.</span>

### Recommended (one command)

```
git clone --recurse-submodules <PARENT_REPO_URL>
```

### If you already cloned (two commands)

```
git submodule init
git submodule update
```

**Tip:**<span style="white-space: pre-wrap;"> Add </span>`<span class="editor-theme-code">--recursive</span>`<span style="white-space: pre-wrap;"> if the submodule itself contains submodules:</span>

```
git submodule update --init --recursive
```

**Symptom you forgot submodules:**<span style="white-space: pre-wrap;"> build errors like “file not found”, missing generated headers, missing </span>`<span class="editor-theme-code">.proto</span>`<span style="white-space: pre-wrap;"> files, or empty directories where ERC-Protobufs should be.</span>

## 4) Adding ERC-Protobufs as a submodule

<span style="white-space: pre-wrap;">Use this when a parent repository needs to include </span>[ERC-Protobufs](https://github.com/RoboTeamTwente/ERC-Protobufs/tree/aa3ea9bfd9cbe811f719f328bf4927445820d1f1)<span style="white-space: pre-wrap;"> for builds/code generation. This is a dependency decision, not a casual Friday activity.</span>

### Step-by-step

1. <span style="white-space: pre-wrap;">Choose where it should live in your repo, for example: </span>`<span class="editor-theme-code">third_party/ERC-Protobufs</span>`<span style="white-space: pre-wrap;"> (or </span>`<span class="editor-theme-code">libs/ERC-Protobufs</span>`).
2. Add the submodule:```
    git submodule add <ERC_PROTOBUFS_REPO_URL> third_party/ERC-Protobufs
    ```
3. Commit the changes:```
    git add .gitmodules third_party/ERC-Protobufs
    git commit -m "Add ERC-Protobufs as a submodule"
    ```

**What gets committed?**<span style="white-space: pre-wrap;"> (a.k.a. “what did I just do to the repo”) </span>

- `<span class="editor-theme-code">.gitmodules</span>`<span style="white-space: pre-wrap;"> file (submodule metadata)</span>
- <span style="white-space: pre-wrap;">a “gitlink” entry at </span>`<span class="editor-theme-code">third_party/ERC-Protobufs</span>`<span style="white-space: pre-wrap;"> that pins a specific commit SHA</span>

The submodule’s full contents are not copied into the parent repo history. You’re committing a pointer, not a copy.

**Protocol for RoboTeam:**<span style="white-space: pre-wrap;"> confirm with your lead whether the submodule path is standardized across repositories (helps tooling and scripts, and prevents everyone inventing </span>`<span class="editor-theme-code">thirdparty/</span>`<span style="white-space: pre-wrap;"> in six different spellings).</span>

## 5) Updating ERC-Protobufs (pinning a new commit)

Updating a submodule means: “the parent repo now points to a newer commit of ERC-Protobufs”. This should be done intentionally and reviewed because it can change message definitions and compatibility. Treat it like an API bump, not like updating a meme folder.

### Update flow (safe + explicit)

1. Enter the submodule directory:```
    cd third_party/ERC-Protobufs
    ```
2. Fetch latest commits:```
    git fetch --all --tags
    ```
3. Check out the desired commit (or a tag):```
    git checkout <commit-sha-or-tag>
    ```
4. Go back to the parent repo and commit the updated pin:```
    cd ../..
    git status
    git add third_party/ERC-Protobufs
    git commit -m "Bump ERC-Protobufs submodule to <sha-or-tag>"
    ```

**Optional (if you want the newest remote-tracking commit):**<span style="white-space: pre-wrap;"> inside the parent repo:</span>

```
git submodule update --remote --merge
```

This requires the submodule to have a branch configured; it is less explicit, so use with care (automation is great right up until it updates something you didn’t mean to update).

**Do not “fix” submodule issues by deleting the folder.**<span style="white-space: pre-wrap;"> That often creates messy diffs and makes Git sad. Use actual submodule commands instead.</span>

## 6) Branches, detached HEAD and what “pinned” means

<span style="white-space: pre-wrap;">When you run </span>`<span class="editor-theme-code">git submodule update</span>`<span style="white-space: pre-wrap;">, Git checks out the exact commit recorded by the parent repo. This usually results in a </span>**detached HEAD**<span style="white-space: pre-wrap;"> state inside the submodule.</span>

**This is normal.**<span style="white-space: pre-wrap;"> A consumer repo typically should not make local changes inside the submodule. If you need to change ERC-Protobufs itself, do that in the ERC-Protobufs repository and then bump the pin in the consumer repo. Submodules are for consuming, not freestyle surgery.</span>

### How to tell what commit you are pinned to

```
# From the parent repo root:
git submodule status
```

### How to see what changed after a submodule bump

```
# From the parent repo root:
git diff --submodule
```

## 7) Common mistakes

### “Directory is empty / looks uninitialized”

```
git submodule update --init --recursive
```

### “Submodule shows changes but I didn’t touch it”

Often caused by being on the wrong commit, or having local edits in the submodule. Either way, Git is not gaslighting you — something really is different.

```
cd third_party/ERC-Protobufs
git status
git reset --hard
git clean -fd
cd ../..
git submodule update --init --recursive
```

**Warning:**<span style="white-space: pre-wrap;"> </span>`<span class="editor-theme-code">git reset --hard</span>`<span style="white-space: pre-wrap;"> and </span>`<span class="editor-theme-code">git clean -fd</span>`<span style="white-space: pre-wrap;"> will delete local submodule changes. Only do this if you are sure you don’t need them (i.e., you didn’t secretly do work inside the submodule and forget).</span>

### “I switched branches and submodules are wrong”

```
git submodule update --init --recursive
```

### “I updated the submodule but forgot to commit in the parent repo”

After updating inside the submodule, you must commit the new pin from the parent repo. Otherwise you updated your local checkout and told nobody, which is the Git equivalent of whispering into the void.

```
git add third_party/ERC-Protobufs
git commit -m "Bump ERC-Protobufs submodule"
```

## 8) Command cheat sheet

### Clone with submodules

```
git clone --recurse-submodules <repo-url>
```

### Initialize/update after cloning

```
git submodule update --init --recursive
```

### Show pinned commits

```
git submodule status
```

### Add ERC-Protobufs

```
git submodule add <erc-protobufs-url> third_party/ERC-Protobufs
git commit -m "Add ERC-Protobufs submodule"
```

### Bump ERC-Protobufs to a specific commit/tag

```
cd third_party/ERC-Protobufs
git fetch --all --tags
git checkout <sha-or-tag>
cd ../..
git add third_party/ERC-Protobufs
git commit -m "Bump ERC-Protobufs submodule to <sha-or-tag>"
```