These are just a few improvements that I thought would make the documentation
related to submodules a little better in various way such as readability,
consistency etc., These were things I noticed while reading thise documents.
Sorry, for the highly granular patches. I did the commits as and when I was
reading them and tried to keep them focused to one particular change by rebasing
them as needed. In case they need some change, let me know.
I based these patches on top of 'master'.
Apart from the changes, I saw a few things that needed improvement/clarification
but wasn't able to do that myself due to my limited knowledge of submodules. They
are listed below. I'll add in patches for them if they are correctly clarified.
1.
man gitsubmodules
· The configuration file $GIT_DIR/config in the superproject. Typical configuration at this place is controlling if a submodule is
recursed into at all via the active flag for example.
If the submodule is not yet initialized, then the configuration inside the submodule does not exist yet, so configuration where to
obtain the submodule from is configured here for example.
What's the "active flag" mentioned above? Also I find the phrase "is recursed into at all"
to be a little slippery. How could it be improved?
2.
man git submodule
update
...
checkout
....
If --force is specified, the submodule will be checked out (using git checkout --force if appropriate), even if the commit
specified in the index of the containing repository already matches the commit checked out in the submodule.
I'm not sure this is conveying all the information it should be conveying.
It seems to making the user wonder, "How at all does 'git submodule update --force'
differs from 'git submodule update'?" also "using git checkout --force if appropriate"
seems to be invoking all sorts confusion as "appropriate" is superfluous.
How could these confusions be clarified?
---
Kaartic
Kaartic Sivaraam (8):
Doc/gitsubmodules: split a sentence for better readability
Doc/gitsubmodules: clearly specify advantage of submodule
Doc/gitsubmodules: specify how submodules help in reduced size
Doc/gitsubmodules: avoid abbreviations
Doc/gitsubmodules: use "Git directory" consistently
Doc/gitsubmodules: improve readability of certain lines
Doc/git-submodule: improve readability and grammar of a sentence
Doc/git-submodule: correctly quote important words
Documentation/git-submodule.txt | 10 +++++-----
Documentation/gitsubmodules.txt | 28 ++++++++++++++++------------
2 files changed, 21 insertions(+), 17 deletions(-)
--
2.16.0.rc0.223.g4a4ac8367
