adds the git submodule cheat sheet
This commit is contained in:
parent
3737397c7e
commit
427d8affb9
93
content/posts/2020-03-09-the-git-submodule-cheat-sheet.md
Normal file
93
content/posts/2020-03-09-the-git-submodule-cheat-sheet.md
Normal file
|
@ -0,0 +1,93 @@
|
|||
+++
|
||||
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
|
||||
```
|
Loading…
Reference in New Issue
Block a user