Re: [PATCH] Documentation/git-submodule.txt: Further clarify the description
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:44:57
Possibly related (same subject, not in this thread)
- 2016-06-15 · [PATCH] Documentation/git-submodule.txt: Further clarify the description · Petr Baudis <hidden>
- 2016-06-15 · Re: [PATCH] Documentation/git-submodule.txt: Further clarify the description · Heikki Orsila <hidden>
Petr Baudis [off-list ref] writes:
quoted hunk
This patch rewrites the general description yet again, first clarifying the high-level concept, mentioning the difference to remotes and using the subtree merge strategy, then getting to the details about tree entries and .gitmodules file. The patch also makes few smallar grammar fixups of the rest of the description and clarifies how does 'init' relate to 'update --init'. Cc: Heikki Orsila <redacted> Signed-off-by: Petr Baudis <redacted> --- Documentation/git-submodule.txt | 39 +++++++++++++++++++++++++++------------ 1 files changed, 27 insertions(+), 12 deletions(-)diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index bb4e6fb..01d0d91 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt@@ -18,24 +18,35 @@ SYNOPSIS DESCRIPTION ----------- +Submodules allow foreign repositories to be embedded within a dedicated +subdirectory of the source tree, always pointed at a particular commit. +They are not to be confused with remotes, which are meant mainly for branches +of the same project; submodules are meant for different projects you would like
Your lines are getting overlong to be easily quoted and commented...
+.... In case you want to merge the project +histories, possibly make local modifications within the tree, but also do not +mind that your repository will bulk up with all the contents of the other +project, consider adding a remote for the other project and using the 'subtree' +merge strategy instead of setting up a submodule.
I'd suggest rephrasing "do not mind" to something a lot less nagative. The user decides to merge because both histories *are* relevant and at that point there is no _minding_ anymore. If you want to have them, you not only "do not mind to have" them but you positively "want" them. On the other hand, a situation where you would want to use submodules is when not necessarily all users of the superproject would want to have all submodules cloned nor checked out. This needs to be stressed with equal weight as the above sentence in this "contrasting merged histories and submodules" paragraph. With that explained clearly upfront, it would become easier for the readers to understand why you can choose not to even update nor fetch submodules you are not interested in.
+Submodules are composed from a special kind of tree entry (so-called `gitlink`) +in the main repository that refers to a particular commit object within
Do we have to say "special"? Is a gitlink any more special than blob and tree entries are? It tends to be rarer, it came later, but I do not think there is anything special from the end user's point of view.
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 the changes 'update' would perform using the 'summary' +subcommand.
Sorry, cannot parse the last three lines...