Re: [PATCHv2] Documentation/git-submodule.txt: Add Description section
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:44:57
Petr Baudis [off-list ref] writes:
quoted hunk
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 76702a0..87c4ece 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt@@ -16,6 +16,28 @@ SYNOPSIS 'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...] +DESCRIPTION +----------- +Submodules are a special kind of tree entries which refer to a particular tree +in another repository (living at a given URL). ...
In the documentation, "tree" has a specific meaning. Perhaps "a particular tree state" is a better wording than another alternative "a particular commit", because you mention "the exact revision" in the following sentence. I'd suggest dropping " (living at a given URL)" from here, though.
... The tree entry describes +the existence of a submodule with the given name and the exact revision that +should be used, while the location of the repository is described in the +`/.gitmodules` file.
Strictly speaking, ".gitmodules" merely gives a hint to be used by "submodule init", the canonical location from which the repository is expected to be cloned. I do not think this overview needs to go into such a detail. The description of "init" subcommand might need clarification, though.
+When checked out, submodules will maintain their own independent repositories +within their directories; the only link between the submodule and the "parent +project" is the tree entry within the parent project mentioned above. + +This command will manage the tree entries and contents of the gitmodules file +for you, as well as inspecting the status of your submodules and updating them. +When adding a new submodule to the tree, the 'add' subcommand is to be used. +However, when pulling a tree containing submodules, these will not be checked +out by default; the 'init' and 'update' subcommands will maintain submodules +checked out and at appropriate revision in your working tree. You can inspect +the current status of your submodules using the 'submodule' subcommand and get +an overview of changes 'update' would perform using the 'summary' subcommand.
Otherwise this is a nice write-up. Will queue; further comments from other submodule users are appreciated if there are any. Thanks.