documenting my sufferings with git submodules

.gitconfig

@@ -11,3 +11,6 @@
 	alias = ! git config --get-regexp ^alias\\. | sed -e s/^alias\\.// -e s/\\ /\\ =\\ / | grep -v ^'alias ' | sort
 [commit]
 	gpgSign = true
+[submodule]
+        recurse = true
+

docs/libraries.md

@@ -77,6 +77,71 @@ repository results in non portable surprises and complexity.  Makes it hard
 for anyone else to build your project, because they will have to, by hand,
 tell your project where the libraries are on their system.
 
+When one is developing code, you normally have a git branch.  But
+the git commit of the master project in which the submodule is
+contained does not notice its subproject has changed, unless the
+subproject head has changed.  And the subject project head will not
+change if it points to a name, rather than to a particular commit. For
+ones changes to a submodule to be reflected in the master project in
+any consistent or predictable way, the submodule has to be in
+detached head mode, with the head pointing directly to a commit,
+rather than pointing to a branch that points to a commit.
+
+Git commands in master project do not look inside the subproject.
+They just look at the subproject's head.
+
+This means that signing off on changes to a submodule is
+irrelevant.  One signs off on the master project, which includes the
+hash of that submodule commit.
+
+When one is changing submodules for the use of a particular
+project, making related changes in the master project and
+submodules, one should not track the changes by creating and
+updating branch names in the submodule, but by creating and
+updating branch names in the containing module, so that the
+commits in the submodule have no name in the submodule, the
+submodule is always in detached head state, albeit the head may be
+tagged.  Names in submodules are primarily of value for
+amendments to the submodule as an independent module,
+intended to be used by multiple projects, and for this purpose, tags
+are better than branch names.  wxWidgets releases are identified by
+tag, not by branch, and the names of branches are only used to
+communicate a particular project on the submodule to other people
+working on that project as their master project.
+
+Branch names are not useful within a submodule, though
+submodule may well be, from the point of view of the primary
+developers, not a submodule but a module in its own right, used as
+a submodule in many different modules, so for them, branch names
+will be useful.  But when you are modifying the submodules in a
+project as a single project, making related changes in the module
+and submodule, the names belong in the primary project module,
+Within the submodule, commits are nameless with detached head,
+the name in primary module naming a group of related commits in
+several submodules, which commits do not usually receive
+independent names of their own, even though the commits have to
+be made within the submodule, not in the containing module which
+names the complete set of interrelated commits.
+
+In this case, working on submodules as part of a single larger project, you should set
+
+```bash
+git config --local submodule.recurse true
+```
+
+In the primary project, so that you conveniently push and pull a
+group of related changes as one thing, and the build for the whole
+project should treat the submodule libraries as having a
+dependency on module/.git/modules/submodule/HEAD, rather than
+checking every single file in the submodules every time to see
+if one has changed, for there could be an enormous number of
+them.  The primary build should invoke the submodule build, which
+*will* check each file in the submodule for changes, only when the
+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.
+
 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
 local great big pile of source code references many independent and
@@ -128,7 +193,6 @@ submodule and the next are such that one is only likely to make changes in
 one module at at time.
 
 # Passphrases
-
 All wallets now use random words - but you cannot carry an eighteen word random phrase though an airport in you head
 
 Should use [grammatically correct passphrases](https://github.com/lungj/passphrase_generator).