1. Use premise

This is often the case: when you work on a Git project, you need to use another Git project in it. Maybe it's a Git library developed by a third party, or you developed it independently and used it in multiple parent projects. In this case, a common problem arises: you want to deal with two projects separately, but you need to use the other one in one.

In Git, you can use submodule to manage these projects. Submodule allows you to treat one Git warehouse as a subdirectory of another Git warehouse. This allows you to clone another repository into your project and keep your submission relatively independent.

2. Add sub module

In this paper, the remote project will be unified https://github.com/maonx/vimwiki-assets.git Clone to the local assets folder.

$ git submodule add https://github.com/maonx/vimwiki-assets.git assets

After adding sub modules, run git status, and you can see that one file is added to the directory gitmodules, this file is used to save the information of sub modules.

$ git status
On branch master

Initial commit

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

    new file:   .gitmodules
    new file:   assets

3. View sub module

$ git submodule
 e33f854d3f51f5ebd771a68da05ad0371a3c0570 assets (heads/master)

4. Update sub module

• Update the child module in the project to the expected version of the parent module

  $ git submodule update
  

• Update the sub module to the latest version of the remote project

  $ git submodule update --remote
  

5. Clone a project that contains submodules

There are two methods to clone a project containing sub modules: one is to clone the parent project first, and then update the sub module; The other is direct recursive cloning of the entire project.

6. Clone the parent project and update the child module

1. Clone parent project

$ git clone https://github.com/maonx/vimwiki-assets.git assets

1. View sub module

$ git submodule
 -e33f854d3f51f5ebd771a68da05ad0371a3c0570 assets

There is a - in front of the sub module, indicating that the sub module file has not been checked in (empty folder).

1. Initialization sub module

$ git submodule init
Submodule 'assets' (https://github.com/maonx/vimwiki-assets.git) registered for path 'assets'

The initialization module only needs to run once after cloning the parent project.

The initialization action is actually from Read submodule information from gitsubmodule file and write it to file git/config:

  6 [remote "origin"]
  7         url = https://github.com/grpc/grpc.git
  8         fetch = +refs/heads/*:refs/remotes/origin/*
  9 [branch "master"]
 10         remote = origin
 11         merge = refs/heads/master
 12 [submodule "third_party/abseil-cpp"]
 13         url = https://github.com/abseil/abseil-cpp.git
 14 [submodule "third_party/benchmark"]
 15         url = https://github.com/google/benchmark
 16 [submodule "third_party/bloaty"]

1. Update sub module

$ git submodule update
Cloning into 'assets'...
remote: Counting objects: 151, done.
remote: Compressing objects: 100% (80/80), done.
remote: Total 151 (delta 18), reused 0 (delta 0), pack-reused 70
Receiving objects: 100% (151/151), 1.34 MiB | 569.00 KiB/s, done.
Resolving deltas: 100% (36/36), done.
Checking connectivity... done.
Submodule path 'assets': checked out 'e33f854d3f51f5ebd771a68da05ad0371a3c0570'

7. Recursively clone the entire project

git clone https://github.com/maonx/vimwiki-assets.git assets --recursive 

Recursively clone the whole project, and the sub modules have been updated at the same time.

8. Modify sub module

After modifying the file in the sub module, submit it directly to the remote project branch.

$ git add .
$ git ci -m "commit"
$ git push origin HEAD:master

9. Delete sub module

Deleting sub modules is troublesome. You need to delete relevant files manually, otherwise errors may occur when adding sub modules
Similarly, take deleting the assets folder as an example

1. Delete sub module folder

$ git rm --cached assets
$ rm -rf assets

1. Delete Relevant sub module information in gitmodules file

[submodule "assets"]
  path = assets
  url = https://github.com/maonx/vimwiki-assets.git

1. Delete Relevant sub module information in git/config

[submodule "assets"]
  url = https://github.com/maonx/vimwiki-assets.git

1. Delete Relevant sub module files in git folder

$ rm -rf .git/modules/assets