git submodule 2022-07-14

A git submodule is a record within a host git repository that points to a specific commit in another external repository.

Submodules are very static and only track specific commits.
Submodules do not track git refs or branches and are not automatically updated when the host repository is updated.

When adding a submodule to a repository a new .gitmodules file will be created. The .gitmodules file contains meta data about the mapping between the submodule project's URL and local directory. If the host repository has multiple submodules, the .gitmodules file will have an entry for each submodule.

• Create a submodule in a git repo
  git submodule add repoURL [localName]

git submodule add https://github.com/panjf2000/ants.git myants

this command will immediately clone the submodule panjf2000/ants into local project and rename it as myants. And this command will create a file .gitmodules as well, which shows the submodules mapping

• Cloning git submodules
  when we want to clone a repo with submodules, git clone is not enough, because clone only work for the host repo but not submodules. so there are more things to go - init the submodules and update them

git clone /url/to/repo/with/submodules
git submodule init # 初始化本地配置文件
git submodule update # 从submodule指向的repo中抓取所有数据并检出当前父项目中列出的指定commit

or, in another simple way, use
git clone --recurse-submodules /url/to/repo/with/submodules

• How to update submodules
  Once submodules are properly initialized and updated within a parent repository they can be utilized exactly like stand-alone repositories. This means that submodules have their own branches and history.

  • When making changes to a submodule in a parent project it is important to publish submodule changes and then update the parent repositories reference to the submodule.

  • If you want to update the submodules by get the updates from submodules' remote repo, use
    git submodule update --remote

get more:
https://git-scm.com/book/zh/v2/Git-%E5%B7%A5%E5%85%B7-%E5%AD%90%E6%A8%A1%E5%9D%97
https://www.atlassian.com/git/tutorials/git-submodule