Thanks, this looks like a good explanation. Some more nits, but overall I feel like I understand this and have learned something from it. On Tue, Jun 20, 2017 at 3:56 PM, Stefan Beller <sbeller@xxxxxxxxxx> wrote: > +A submodule is another Git repository tracked inside a repository. > +The tracked repository has its own history, which does not > +interfere with the history of the current repository. > + > +It consists of a tracking subdirectory in the working directory, > +a 'gitlink' in the working tree and an entry in the `.gitmodules` Probably should be `gitlink` (the special quotes), and (optional) s/`gitlink`/`gitlink` object/ because it might not be apparent that gitlink is a type of object. > +file (see linkgit:gitmodules[5]) at the root of the source tree. After reading below, maybe we should mention the Git directory in $GIT_DIR/modules/<submodule name> as part of what a submodule consists of too. > +The tracking subdirectory appears in the main repositorys working s/repositorys/repository's/ (apostrophe is also missing in some other places below) > +tree at the point where the submodules gitlink is tracked in the > +tree. It is empty when the submodule is not populated, otherwise > +it contains the content of the submodule repository. > +The main repository is often referred to as superproject. > + > +The gitlink contains the object name of a particular commit > +of the submodule. > + > +The `.gitmodules` file establishes a relationship between the > +path, which is where the gitlink is in the tree, and the logical > +name, which is used for the location of the submodules git > +directory. The `.gitmodules` file has the same syntax as the > +$Git_DIR/config file and the mapping of path to name Capitalization of $GIT_DIR > +is done via setting `submodule.<name value>.path = <path value>`. (Optional) I would prefer <name> and <path> to be consistent with the following paragraph. > +The submodules git directory is found in in the main repositories > +'$GIT_DIR/modules/<name>' or inside the tracking subdirectory. > + > +Submodules can be used for at least two different use cases: > + > +1. Using another project while maintaining independent history. > + Submodules allow you to contain the working tree of another project > + within your own working tree while keeping the history of both > + projects separate. Also, since submodules are fixed to a an arbitrary > + version, the other project can be independently developed without > + affecting the superproject, allowing the superproject project to > + fix itself to new versions only whenever desired. > + > +2. Splitting a (logically single) project into multiple > + repositories and tying them back together. This can be used to > + overcome current limitations of Gits implementation to have > + finer grained access: > + > +* Size of the git repository > + In its current form Git scales up poorly for very large repositories that > + change a lot, as the history grows very large. > + However you can also use submodules to e.g. hold large binary assets > + and these repositories are then shallowly cloned such that you do not > + have a large history locally. > + > +* Transfer size > + In its current form Git requires the whole working tree present. It > + does not allow partial trees to be transferred in fetch or clone. > + > +* Access control > + By restricting user access to submodules, this can be used to implement > + read/write policies for different users. The bullet points should probably be indented more. [snip] > +Deleting a submodule > +-------------------- > + > +Deleting a submodule can happen on different levels: > + > +1) Removing it from the local working tree without tampering with > + the history of the superproject. > + > +You may no longer need the submodule, but still want to keep it recorded > +in the superproject history as others may have use for it. The command > +`git submodule deinit <submodule path>` will remove any configuration > +entries from the config file, such that the submodule becomes s=config=$GIT_DIR/config= (since there are multiple relevant config files) > +uninitialized. The tracking directory in the superprojects working > +tree that holds the submodules working directory is emptied. > +This step can be undone via `git submodule init`. > + > +2) Remove it from history: > +-- > + git rm <submodule path> > + git commit > +-- > +This removes the submodules gitlink from the superprojects tree, as well > +as removing the entries from the `.gitmodules` file, but keeps the > +local configuration for the submodule. This can be undone using `git revert`. > + > + > +3) Remove the submodules git directory: > + > +When you also want to free up the disk space that the submodules git > +directory uses, you have to delete it manually as this > +step cannot be undone using git tools. It is found in `$GIT_DIR/modules`.
