> For the complete documentation index, see [llms.txt](https://b1f6c1c4.gitbook.io/learn-git-the-super-hard-way/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://b1f6c1c4.gitbook.io/learn-git-the-super-hard-way/chapter9.md). # 第9章：邪恶的submodule ## 基础知识在worktree内部创建新的repo/worktree是坏的，因为一个文件受两个repo管辖。一个workaround是将这个小的repo/worktree变成大repo的一个submodule。一个submodule的信息可以分为静态与动态两大部分，总共分散在5个位置： * `.gitmodules`文件中包含一部分静态信息： * submodule (name)：名字 * path：应该放在worktree的哪个路径里面 * url：在哪里能够找到包含该commit的repo * branch：没有什么卵用 * update：如何处理下级repo的更改 * index中包含另一部分静态信息： * commit：上级repo期待哪个commit * `.git/config`文件中包含一部分动态信息： * submodule (name) * active：启用/禁用 * url * update * `.git/modules//`是下级repo，包含一部分动态信息 * ``是下级repo的worktree，包含一部分动态信息 ```bash git config --global alias.lg "log --graph --pretty=tformat:'%h -%d <%an/%cn> %s' --abbrev-commit" ``` ## 添加/更新submodule的静态部分（`.gitmodules`/index）非常简单，直接修改`.gitmodules`和index： * Lv1 ```bash git init parent # Initialized empty Git repository in /root/parent/.git/ cd parent cat - >.gitmodules <` 若未指定那三个选项，其功能根据`git config submodule..update`而定，共有5种： * checkout（此为默认情况） * rebase * merge * none * !... 下面将分别介绍。 ### `git submodule update --checkout == git clone` * Lv2 ```bash cd parent (git submodule --quiet init -- whatever/path) git config --list | grep -F submodule.static/name # submodule.static/name.active=true # submodule.static/name.url=https://github.com/b1f6c1c4/git-get.git # submodule.static/name.update=none # 首先创建repo和worktree mkdir -p .git/modules/static/name git init --separate-git-dir .git/modules/static/name whatever/path # Initialized empty Git repository in /root/parent/.git/modules/static/name/ git -C whatever/path config core.worktree ../../../../whatever/path ls -A .git/modules/static/name whatever/path # .git/modules/static/name: # HEAD # branches # config # description # hooks # info # objects # refs # # whatever/path: # .git # 然后设置remote git -C whatever/path remote add origin \ "$(git config submodule.static/name.url)" # 然后fetch git -C whatever/path fetch origin # From https://github.com/b1f6c1c4/git-get # * [new branch] example-repo0 -> origin/example-repo0 # * [new branch] example-repo1 -> origin/example-repo1 # * [new branch] example-repo2 -> origin/example-repo2 # * [new branch] example/repo3 -> origin/example/repo3 # * [new branch] master -> origin/master # * [new tag] v0.0 -> v0.0 # 然后创建默认分支（根据远端的HEAD是谁而决定） # （其实这一步实际上并没有什么卵用） git -C whatever/path symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/master git -C whatever/path update-ref refs/heads/master refs/remotes/origin/master git -C whatever/path config branch.master.remote origin git -C whatever/path config branch.master.merge refs/heads/master # 然后switch到目标commit git -C whatever/path switch --detach \ "$(git ls-files -s -- whatever/path | awk "{ print $2; }")" # fatal: invalid reference: 160000 bff56f7a1c9585780950dce5c1964410e0aa2ecc 0 whatever/path git -C whatever/path branch -av # * master e822073 improve PKGBUILD quality # remotes/origin/HEAD -> origin/master # remotes/origin/example-repo0 bff56f7 basics # remotes/origin/example-repo1 e97348c dummy commit # remotes/origin/example-repo2 2dd50b6 use https # remotes/origin/example/repo3 2dd50b6 use https # remotes/origin/master e822073 improve PKGBUILD quality ls -A whatever/path # .git cat .git/modules/static/name/config # [core] # repositoryformatversion = 0 # filemode = true # bare = false # logallrefupdates = true # worktree = ../../../../whatever/path # [remote "origin"] # url = https://github.com/b1f6c1c4/git-get.git # fetch = +refs/heads/*:refs/remotes/origin/* # [branch "master"] # remote = origin # merge = refs/heads/master ``` 由于其中有`git fetch`，巨量无关数据一并被下载了下来。 * Lv3 ```bash cd parent (rm -rf .git/modules whatever/path) git submodule update --checkout -- whatever/path # Cloning into '/root/parent/whatever/path'... # Submodule path 'whatever/path': checked out 'bff56f7a1c9585780950dce5c1964410e0aa2ecc' git -C whatever/path branch -av # * (HEAD detached at bff56f7) bff56f7 basics # master e822073 improve PKGBUILD quality # remotes/origin/HEAD -> origin/master # remotes/origin/example-repo0 bff56f7 basics # remotes/origin/example-repo1 e97348c dummy commit # remotes/origin/example-repo2 2dd50b6 use https # remotes/origin/example/repo3 2dd50b6 use https # remotes/origin/master e822073 improve PKGBUILD quality ls -A whatever/path # .git # dir # file # link cat .git/modules/static/name/config # [core] # repositoryformatversion = 0 # filemode = true # bare = false # logallrefupdates = true # worktree = ../../../../whatever/path # [remote "origin"] # url = https://github.com/b1f6c1c4/git-get.git # fetch = +refs/heads/*:refs/remotes/origin/* # [branch "master"] # remote = origin # merge = refs/heads/master ``` 这里面依然有`git fetch`。为了解决这个问题，可以使用`git-get`： * Lv5: [git-get](https://github.com/b1f6c1c4/git-get) ### `git submodule update --checkout [-f] == git switch [-f] ` 假设index发生了变动： ```bash git -C parent update-index --cacheinfo 160000,e97348c1ba3072a1c108218f6ba88c3177a7456f,whatever/path ``` * Lv2 ```bash cd parent git -C whatever/path switch -f --detach \ "$(git ls-files -s -- whatever/path | awk "{ print $2; }")" # fatal: invalid reference: 160000 e97348c1ba3072a1c108218f6ba88c3177a7456f 0 whatever/path git -C whatever/path status # HEAD detached at bff56f7 # nothing to commit, working tree clean ``` * Lv3 ```bash cd parent git submodule update --checkout -f -- whatever/path # Submodule path 'whatever/path': checked out 'e97348c1ba3072a1c108218f6ba88c3177a7456f' git -C whatever/path status # HEAD detached at e97348c # nothing to commit, working tree clean ``` ### `git submodule update --rebase == git rebase ` （先回到原来的HEAD位置） ```bash (git -C parent update-index --cacheinfo 160000,bff56f7a1c9585780950dce5c1964410e0aa2ecc,whatever/path) (git -C parent submodule --quiet update --checkout -f -- whatever/path) ``` 假设repo中HEAD发生了变动： ```bash cd parent git -C whatever/path switch --detach 2dd5 # Previous HEAD position was bff56f7 basics # HEAD is now at 2dd50b6 use https ``` 然后index又发生了变动： ```bash git -C parent update-index --cacheinfo 160000,e97348c1ba3072a1c108218f6ba88c3177a7456f,whatever/path ``` 现在希望能够把下级repo中新的改动rebase到e973上： * Lv2 ```bash cd parent git -C whatever/path lg HEAD e973 # * e97348c - (origin/example-repo1) dummy commit # * ac33e9e - dummy commit # * 7fffa2c - dummy commit # * db89c7a - dummy commit # * 58e8a67 - dummy commit # * a37e16b - dummy commit # * 329a265 - dummy commit # * eec9c41 - dummy commit # * 3c19b79 - dummy commit # | * 2dd50b6 - (HEAD, origin/example/repo3, origin/example-repo2) use https # | * 1beea7d - add repo2 to xsub # |/ # * 2c0d59d - use https # * e7b2ae8 - add repo0 to sub # * bff56f7 - (origin/example-repo0) basics GIT_COMMITTER_NAME=committer \ GIT_COMMITTER_EMAIL=committer@gmail.com \ GIT_COMMITTER_DATE='1514736120 +0800' \ git -C whatever/path rebase --quiet e973 git -C whatever/path lg HEAD e973 # * d02f6d7 - (HEAD) use https # * c4a760b - add repo2 to xsub # * e97348c - (origin/example-repo1) dummy commit # * ac33e9e - dummy commit # * 7fffa2c - dummy commit # * db89c7a - dummy commit # * 58e8a67 - dummy commit # * a37e16b - dummy commit # * 329a265 - dummy commit # * eec9c41 - dummy commit # * 3c19b79 - dummy commit # * 2c0d59d - use https # * e7b2ae8 - add repo0 to sub # * bff56f7 - (origin/example-repo0) basics ``` * Lv3 ```bash cd parent (git -C whatever/path switch --detach 2dd5 2>/dev/null) git -C whatever/path lg HEAD e973 # * e97348c - (origin/example-repo1) dummy commit # * ac33e9e - dummy commit # * 7fffa2c - dummy commit # * db89c7a - dummy commit # * 58e8a67 - dummy commit # * a37e16b - dummy commit # * 329a265 - dummy commit # * eec9c41 - dummy commit # * 3c19b79 - dummy commit # | * 2dd50b6 - (HEAD, origin/example/repo3, origin/example-repo2) use https # | * 1beea7d - add repo2 to xsub # |/ # * 2c0d59d - use https # * e7b2ae8 - add repo0 to sub # * bff56f7 - (origin/example-repo0) basics GIT_COMMITTER_NAME=committer \ GIT_COMMITTER_EMAIL=committer@gmail.com \ GIT_COMMITTER_DATE='1514736120 +0800' \ git submodule update --rebase -- whatever/path 2>/dev/null # Submodule path 'whatever/path': rebased into 'e97348c1ba3072a1c108218f6ba88c3177a7456f' git -C whatever/path lg HEAD e973 # * d02f6d7 - (HEAD) use https # * c4a760b - add repo2 to xsub # * e97348c - (origin/example-repo1) dummy commit # * ac33e9e - dummy commit # * 7fffa2c - dummy commit # * db89c7a - dummy commit # * 58e8a67 - dummy commit # * a37e16b - dummy commit # * 329a265 - dummy commit # * eec9c41 - dummy commit # * 3c19b79 - dummy commit # * 2c0d59d - use https # * e7b2ae8 - add repo0 to sub # * bff56f7 - (origin/example-repo0) basics ``` ### `git submodule update --merge == git merge ` （先回到原来的HEAD位置） ```bash (git -C parent update-index --cacheinfo 160000,bff56f7a1c9585780950dce5c1964410e0aa2ecc,whatever/path) (git -C parent submodule update --checkout -f -- whatever/path 2>/dev/null) # Submodule path 'whatever/path': checked out 'bff56f7a1c9585780950dce5c1964410e0aa2ecc' ``` 假设repo中HEAD发生了变动： ```bash cd parent git -C whatever/path switch --detach 2dd5 # Previous HEAD position was bff56f7 basics # HEAD is now at 2dd50b6 use https ``` 然后index又发生了变动： ```bash git -C parent update-index --cacheinfo 160000,e97348c1ba3072a1c108218f6ba88c3177a7456f,whatever/path ``` 现在希望能够在下级repo中merge上级以为的新的改动： * Lv2 ```bash cd parent git -C whatever/path lg HEAD e973 # * e97348c - (origin/example-repo1) dummy commit # * ac33e9e - dummy commit # * 7fffa2c - dummy commit # * db89c7a - dummy commit # * 58e8a67 - dummy commit # * a37e16b - dummy commit # * 329a265 - dummy commit # * eec9c41 - dummy commit # * 3c19b79 - dummy commit # | * 2dd50b6 - (HEAD, origin/example/repo3, origin/example-repo2) use https # | * 1beea7d - add repo2 to xsub # |/ # * 2c0d59d - use https # * e7b2ae8 - add repo0 to sub # * bff56f7 - (origin/example-repo0) basics GIT_AUTHOR_NAME=author \ GIT_AUTHOR_EMAIL=author@gmail.com \ GIT_AUTHOR_DATE='1234567890 +0800' \ GIT_COMMITTER_NAME=committer \ GIT_COMMITTER_EMAIL=committer@gmail.com \ GIT_COMMITTER_DATE='1514736120 +0800' \ git -C whatever/path merge e973 # Already up to date! # Merge made by the 'recursive' strategy. git -C whatever/path lg HEAD e973 # * 46b15af - (HEAD) Merge commit 'e973' into HEAD # |\ # | * e97348c - (origin/example-repo1) dummy commit # | * ac33e9e - dummy commit # | * 7fffa2c - dummy commit # | * db89c7a - dummy commit # | * 58e8a67 - dummy commit # | * a37e16b - dummy commit # | * 329a265 - dummy commit # | * eec9c41 - dummy commit # | * 3c19b79 - dummy commit # * | 2dd50b6 - (origin/example/repo3, origin/example-repo2) use https # * | 1beea7d - add repo2 to xsub # |/ # * 2c0d59d - use https # * e7b2ae8 - add repo0 to sub # * bff56f7 - (origin/example-repo0) basics ``` * Lv3 ```bash cd parent (git -C whatever/path switch --quiet --detach 2dd5) git -C whatever/path lg HEAD e973 # * e97348c - (origin/example-repo1) dummy commit # * ac33e9e - dummy commit # * 7fffa2c - dummy commit # * db89c7a - dummy commit # * 58e8a67 - dummy commit # * a37e16b - dummy commit # * 329a265 - dummy commit # * eec9c41 - dummy commit # * 3c19b79 - dummy commit # | * 2dd50b6 - (HEAD, origin/example/repo3, origin/example-repo2) use https # | * 1beea7d - add repo2 to xsub # |/ # * 2c0d59d - use https # * e7b2ae8 - add repo0 to sub # * bff56f7 - (origin/example-repo0) basics GIT_AUTHOR_NAME=author \ GIT_AUTHOR_EMAIL=author@gmail.com \ GIT_AUTHOR_DATE='1234567890 +0800' \ GIT_COMMITTER_NAME=committer \ GIT_COMMITTER_EMAIL=committer@gmail.com \ GIT_COMMITTER_DATE='1514736120 +0800' \ git submodule update --merge -- whatever/path # Already up to date! # Merge made by the 'recursive' strategy. # Submodule path 'whatever/path': merged in 'e97348c1ba3072a1c108218f6ba88c3177a7456f' git -C whatever/path lg HEAD e973 # * 71e724c - (HEAD) Merge commit 'e97348c1ba3072a1c108218f6ba88c3177a7456f' into HEAD # |\ # | * e97348c - (origin/example-repo1) dummy commit # | * ac33e9e - dummy commit # | * 7fffa2c - dummy commit # | * db89c7a - dummy commit # | * 58e8a67 - dummy commit # | * a37e16b - dummy commit # | * 329a265 - dummy commit # | * eec9c41 - dummy commit # | * 3c19b79 - dummy commit # * | 2dd50b6 - (origin/example/repo3, origin/example-repo2) use https # * | 1beea7d - add repo2 to xsub # |/ # * 2c0d59d - use https # * e7b2ae8 - add repo0 to sub # * bff56f7 - (origin/example-repo0) basics ``` ### 其他两种`git config submodule..update` ```bash cd parent git config submodule.static/name.update none git submodule update -- whatever/path # Skipping submodule 'whatever/path' ``` ```bash cd parent git config submodule.static/name.update '!true' git submodule update -- whatever/path # Submodule path 'whatever/path': 'true e97348c1ba3072a1c108218f6ba88c3177a7456f' git config submodule.static/name.update '!false' git submodule update -- whatever/path # Execution of 'false e97348c1ba3072a1c108218f6ba88c3177a7456f' failed in submodule path 'whatever/path' git config submodule.static/name.update '!echo' git submodule update -- whatever/path # e97348c1ba3072a1c108218f6ba88c3177a7456f # Submodule path 'whatever/path': 'echo e97348c1ba3072a1c108218f6ba88c3177a7456f' ``` ## 用`.gitmodules`和index来创建repo和worktree 分两步：用`.gitmodules`来更新`.git/config`；再用`.git/config`和index来更新repo和worktree。 Lv2不再赘述。 * Lv3 ```bash cd parent (rm -rf .git/modules whatever/path) git submodule update --init --checkout -- whatever/path # Cloning into '/root/parent/whatever/path'... # Submodule path 'whatever/path': checked out 'e97348c1ba3072a1c108218f6ba88c3177a7456f' ``` ## 用repo来更新index （先回到原来的HEAD位置） ```bash (git -C parent update-index --cacheinfo 160000,bff56f7a1c9585780950dce5c1964410e0aa2ecc,whatever/path) (git -C parent submodule --quiet update --checkout -f -- whatever/path) ``` 假设repo中HEAD发生了变动： ```bash cd parent git -C whatever/path switch --detach 2dd5 # Previous HEAD position was bff56f7 basics # HEAD is now at 2dd50b6 use https ``` 现在希望index也跟着变动： * Lv1 ```bash cd parent git ls-files -s # 160000 bff56f7a1c9585780950dce5c1964410e0aa2ecc 0 whatever/path git update-index --cacheinfo "160000,$(git -C whatever/path rev-parse HEAD),whatever/path" git ls-files -s # 160000 2dd50b6425c7d79f4695aa69d05467e1a00fc20f 0 whatever/path ``` * Lv2 ```bash cd parent (git update-index --cacheinfo 160000,bff56f7a1c9585780950dce5c1964410e0aa2ecc,whatever/path) git ls-files -s # 160000 bff56f7a1c9585780950dce5c1964410e0aa2ecc 0 whatever/path git update-index -- whatever/path git ls-files -s # 160000 2dd50b6425c7d79f4695aa69d05467e1a00fc20f 0 whatever/path ``` * Lv3 ```bash cd parent (git update-index --cacheinfo 160000,bff56f7a1c9585780950dce5c1964410e0aa2ecc,whatever/path) git ls-files -s # 160000 bff56f7a1c9585780950dce5c1964410e0aa2ecc 0 whatever/path git add whatever/path git ls-files -s # 160000 2dd50b6425c7d79f4695aa69d05467e1a00fc20f 0 whatever/path ``` ## 用`.gitmodules`来更新`.git/config`和repo的URL ```bash cd parent git config --file=.gitmodules submodule.static/name.url https://localhost ``` * Lv2 ```bash cd parent git config submodule.static/name.url \ "$(git config --file=.gitmodules submodule.static/name.url)" git -C whatever/path remote set-url origin \ "$(git config --file=.gitmodules submodule.static/name.url)" ``` * Lv3 ```bash cd parent git submodule sync -- whatever/path # Synchronizing submodule url for 'whatever/path' git config --get submodule.static/name.url # https://localhost git -C whatever/path remote -v # origin https://localhost (fetch) # origin https://localhost (push) ``` ## 一次性添加`.gitmodules`、`.git/config`、index、repo、worktree * Lv2 先添加`.gitmodules`和index，然后用`.gitmodules`更新`.git/config`，然后用`.git/config`和index创建repo和worktree。 * Lv3 注意：只能指定一个branch，不能指定某个commit。包括`git fetch`，可能造成大量资源浪费。 ```bash (rm -rf parent && git init --quiet parent) cd parent git submodule add -b example-repo0 -f --name static/name -- https://github.com/b1f6c1c4/git-get.git whatever/path # Cloning into '/root/parent/whatever/path'... cat .gitmodules # [submodule "static/name"] # path = whatever/path # url = https://github.com/b1f6c1c4/git-get.git # branch = example-repo0 cat .git/config # [core] # repositoryformatversion = 0 # filemode = true # bare = false # logallrefupdates = true # [submodule "static/name"] # url = https://github.com/b1f6c1c4/git-get.git # active = true git ls-files -s # 100644 64817d5b42c4ac1087a41478d37dfe22df2bacad 0 .gitmodules # 160000 bff56f7a1c9585780950dce5c1964410e0aa2ecc 0 whatever/path ls -A .git/modules/static/name # HEAD # branches # config # description # hooks # index # info # logs # objects # packed-refs # refs ls -A whatever/path # .git # dir # file # link ``` ## 删除`.git/config`和worktree * Lv2 ```bash cd parent git config --remove-section submodule.static/name rm -rf whatever/path ``` * Lv3 ```bash cd parent (git submodule --quiet update --init -- whatever/path) git submodule deinit -f -- whatever/path # Cleared directory 'whatever/path' # Submodule 'static/name' (https://github.com/b1f6c1c4/git-get.git) unregistered for path 'whatever/path' cat .gitmodules # [submodule "static/name"] # path = whatever/path # url = https://github.com/b1f6c1c4/git-get.git # branch = example-repo0 cat .git/config # [core] # repositoryformatversion = 0 # filemode = true # bare = false # logallrefupdates = true git ls-files -s # 100644 64817d5b42c4ac1087a41478d37dfe22df2bacad 0 .gitmodules # 160000 bff56f7a1c9585780950dce5c1964410e0aa2ecc 0 whatever/path ls -A .git/modules/static/name # HEAD # branches # config # description # hooks # index # info # logs # objects # packed-refs # refs ls -A whatever/path ``` ## 删除`.gitmodules`和index * Lv2 ```bash cd parent git config --file=.gitmodules --remove-section submodule.static/name git update-index --force-remove whatever/path rm -rf whatever/path git update-index -fu -- whatever/path # error: unknown switch 'f' # usage: git update-index [] [--] [...] # # -q continue refresh even when index needs update # --ignore-submodules refresh: ignore submodules # --add do not ignore new files # --replace let files replace directories and vice-versa # --remove notice files missing from worktree # --unmerged refresh even if index contains unmerged entries # --refresh refresh stat information # --really-refresh like --refresh, but ignore assume-unchanged setting # --cacheinfo ,