Website/content/docs/infrastructure/forgejo/submodules.md

---
title: 'Submodules'
date: 2024-02-29T01:31:40+01:00
---

Git provides [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
to use another project in your repository[^1]. This is a handy way to separate
content and apply different access rights. For example, if you want to create a
hidden area for a [treasure](/music/inconvenient-ep/influenca/#treasure) hunt
like me. I use a private repo from within my main Website repo. If you view the
[sources of the Influenca page](https://dri.ven.uber.space/thisven/Website/src/branch/main/content/music/inconvenient-ep/influenca)
in this repo and want to access the folder `hidden @ <hash>`, you'll get a 404
page as this is a link to the private repo. Only authenticated users can access
it.

## Enabling auto-update

To automatically update submodules on `git clone` and `git pull` I enable [submodule.rescurse](https://git-scm.com/docs/git-config#Documentation/git-config.txt-submodulerecurse):

```bash
git config submodule.recurse true
```

## Adding into main

The command to add a submodule expects the destination of the other project and
a relative path inside the main repository. For example, to add the repo
`https://codeberg.org/thisven/private` as submodule into `content/blog/hidden`
the command would be:

```bash
git submodule add https://codeberg.org/thisven/private content/blog/hidden
```

Additionally, a `.gitmodules` file is created to maintain the submodule details:

```git {filename=".gitmodules"}
[submodule "content/blog/hidden"]
    path = content/blog/hidden
    url = https://codeberg.org/thisven/private
```

## Pulling from remote

If you have cloned a repo before [enabling auto-update](#enabling-auto-update),
you can manually pull from the submodule repo using this command:

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

If you are cloning an existing main repo that contains submodules, you can use
`git clone` with the `--recurse-submodules` option.

[^1]: [Software repository](https://en.wikipedia.org/wiki/Software_repository)
in the Wikipedia