93 lines
2.5 KiB
Markdown
93 lines
2.5 KiB
Markdown
+++
|
|
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
|
|
``` |