fozu
on
Apr 10, 20222022-04-10T00:00:00+08:00
Updated
Apr 10, 20232023-04-10T14:35:37+08:00
3 min read
Official Tutorial
Usage
Add Submodule
git help submodule
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
| git submodule [--quiet] add [<options>] [--] <repository> [<path>]
add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository>
[<path>]
git submodule [--quiet] set-branch [<options>] [--] <path>
# Sets the default remote tracking branch for the submodule. The --branch option allows the remote branch to
# be specified. The --default option removes the submodule.<name>.branch configuration key, which causes the
# tracking branch to default to the remote HEAD.
set-branch (-b|--branch) <branch> [--] <path>, set-branch (-d|--default) [--] <path>
git submodule [--quiet] set-url [--] <path> <newurl>
# Sets the URL of the specified submodule to <newurl>. Then, it will automatically synchronize the
# submodule’s new remote URL configuration.
set-url [--] <path> <newurl>
git submodule [--quiet] sync [--recursive] [--] [<path>...]
# Synchronizes submodules' remote URL configuration setting to the value specified in .gitmodules. It will
# only affect those submodules which already have a URL entry in .git/config (that is the case when they are
# initialized or freshly added). This is useful when submodule URLs change upstream and you need to update
# your local repositories accordingly.
# git submodule sync synchronizes all submodules while git submodule sync -- A synchronizes submodule "A"
# only.
sync [--recursive] [--] [<path>...]
git submodule [--quiet] update [<options>] [--] [<path>...]
|
1
| git submodule add url [local path]
|
e.g.
1
| git submodule add ../c-tutorial.git
|
cat .gitmodules
1
2
3
| [submodule "c-tutorial"]
path = c-tutorial
url = ../c-tutorial.git
|
Clone
1
| git clone --recurse-submodules url
|
or
1
2
| git submodule init
git submodule update
|
or
1
| git submodule update --init --recursive
|
1
| git config -f .gitmodules submodule.DbConnector.branch stable
|
Diff
1
| git config --global diff.submodule log
|
Pull from submodule remote
1
| git submodule update --remote
|
Status with short summary
1
| git config status.submodulesummary 1
|
log
Pull
1
| git config --global submodule.recurse true
|
Detached HEAD
This means that there is no local working branch (like master, for example) tracking changes. With no working branch tracking changes, that means even if you commit changes to the submodule, those changes will quite possibly be lost the next time you run git submodule update.
In order to set up your submodule to be easier to go in and hack on, you need to do two things. You need to go into each submodule and check out a branch to work on. Then you need to tell Git what to do if you have made changes and then git submodule update --remote pulls in new work from upstream. The options are that you can merge them into your local work, or you can try to rebase your local work on top of the new changes.
1
2
3
| $ cd DbConnector/
$ git checkout stable
Switched to branch 'stable'
|
1
2
3
| $ cd ..
# updating our submodule with the “merge” option.
$ git submodule update --remote --merge
|
1
2
3
4
| # make out own changes in submodule and commit
$ cd DbConnector/
$ vim src/db.c
$ git commit -am 'Unicode support'
|
1
2
3
4
5
6
7
| # assuming someone else pushes another changeupstream at the same time
$ cd ..
# update with rebase option
$ git submodule update --remote --rebase
First, rewinding head to replay your work on top of it...
Applying: Unicode support
Submodule path 'DbConnector': rebased into '5d60ef9bbebf5a0c1c1050f242ceeb54ad58da94'
|
If you forget the --rebase or --merge, Git will just update the submodule to whatever is on the server and reset your project to a detached HEAD state.
f this happens, don’t worry, you can simply go back into the directory and check out your branch again (which will still contain your work) and merge or rebase origin/stable (or whatever remote branch you want) manually.
Push
1
2
3
| git push --recurse-submodules=check
git push --recurse-submodules=on-demand
git config push.recurseSubmodules on-demand.
|
