On 02/08, Stefan Beller wrote: > +STATES > +------ > + > +When working with submodules, you can think of them as in a state machine. > +So each submodule can be in a different state, the following indicators are > used: > + > +* the existence of the setting of 'submodule.<name>.url' in the > + superprojects configuration > +* the existence of the submodules working tree within the > + working tree of the superproject > +* the existence of the submodules git directory within the superprojects > + git directory at $GIT_DIR/modules/<name> or within the submodules working > + tree > + > + State URL config working tree git dir > + ----------------------------------------------------- > + uninitialized no no no > + initialized yes no no > + populated yes yes yes > + depopulated yes no yes > + deinitialized no no yes > + uninteresting no yes yes > + > + invalid no yes no > + invalid yes yes no > + ----------------------------------------------------- > + > +The first six states can be reached by normal git usage, the latter two are > +only shown for completeness to show all possible eight states with 3 binary > +indicators. The states in detail: > + > +uninitialized:: > +The uninitialized state is the default state if no > +'--recurse-submodules' / '--recursive'. An empty directory will be put in > +the working tree as a place holder, such that you are reminded of the > +existence of the submodule. > +--- > +To transition into the initialized state > +you can use 'git submodule init', which copies the presets from the > +.gitmodules file into the config. > + > +initialized:: > +Users transitioned from the uninitialized state to this state via > +'git submodule init', which preset the URL configuration. As these URLs > +may not be desired in certain scenarios, this state allows to change the > +URLs. For example in a corporate environment you may want to run > + > + sed -i s/example.org/$internal-mirror/ .git/config > ++
Maybe we can try to brainstorm and come up with some clearer terminology while we are at it. I was trying to think about the "initialized" state and I may be the only one but it seems unclear what "initialized" means. I mean I already have all the information about a submodule in the .gitmodules file, isn't it already initialized then? Maybe this state would be better named "(in)active" as a module that is interesting to a user is "active"? -- Brandon Williams
