diff --git a/docs/libraries.md b/docs/libraries.md index 65b4956..7fde6b1 100644 --- a/docs/libraries.md +++ b/docs/libraries.md @@ -140,7 +140,37 @@ them. The primary build should invoke the submodule build, which submodule detached head has changed. And therefore, you want it to change, you want the submodule head to be nameless and detached, whenever you modify a submodule as part of a larger -project where you test your changes by rebuilding the whole project to make sure all your related changes fit together. +project where you test your changes by rebuilding the whole +project to make sure all your related changes fit together. + +When tracking an upstream submodule that has submodules of its +own, which have their own upstreams + +Update your version with + +```bash +git pull upstream --recurse-submodules=on-demand their-latest release. +``` + +Make sure things still work. Get everything working. (You do have unit test, right?) + +then: + +```bash +git submodule foreach --recursive 'git push origin HEAD:your-tracking-branch' +git submodule foreach --recursive 'git switch --detach' +``` + +All of which, of course, presupposes you have already set unit tests, +upstream, origin, and your tracking branch appropriately. + +Even though your local modifications are nameless in your local +repository, on your remote they need to have a name to be pushed +to, hence you need to have a tracking branch in each of your +remote images of each of your submodules, and that tracking +branch will point to the root of a tree of all the nameless commits +that the names and commits in your superproject that contains all +these submodules point to. You need an enormous pile of source code, the work of many people over a very long time, and GitSubmodules allows this to scale, because the