From: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
To: Git mailing list <git@vger.kernel.org>,
Stefan Beller <sbeller@google.com>
Subject: [PATCH 0/8] Doc/submodules: a few updates
Date: Sun, 7 Jan 2018 00:16:06 +0530 [thread overview]
Message-ID: <20180106184614.20115-1-kaartic.sivaraam@gmail.com> (raw)
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
next reply other threads:[~2018-01-06 18:46 UTC|newest]
Thread overview: 44+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-01-06 18:46 Kaartic Sivaraam [this message]
2018-01-06 18:46 ` [PATCH 1/8] Doc/gitsubmodules: split a sentence for better readability Kaartic Sivaraam
2018-01-07 0:29 ` Eric Sunshine
2018-01-08 18:33 ` Stefan Beller
2018-01-06 18:46 ` [PATCH 2/8] Doc/gitsubmodules: clearly specify advantage of submodule Kaartic Sivaraam
2018-01-08 18:36 ` Stefan Beller
2018-01-09 15:58 ` Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 3/8] Doc/gitsubmodules: specify how submodules help in reduced size Kaartic Sivaraam
2018-01-07 0:31 ` Eric Sunshine
2018-01-08 18:38 ` Stefan Beller
2018-01-09 16:01 ` Kaartic Sivaraam
2018-01-09 19:01 ` Stefan Beller
2018-01-09 19:30 ` Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 4/8] Doc/gitsubmodules: avoid abbreviations Kaartic Sivaraam
2018-01-07 0:36 ` Eric Sunshine
2018-01-08 18:45 ` Stefan Beller
2018-01-09 16:06 ` Kaartic Sivaraam
2018-01-09 19:26 ` Stefan Beller
2018-01-09 19:32 ` Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 5/8] Doc/gitsubmodules: use "Git directory" consistently Kaartic Sivaraam
2018-01-07 0:39 ` Eric Sunshine
2018-01-08 18:45 ` Stefan Beller
2018-01-06 18:46 ` [PATCH 6/8] Doc/gitsubmodules: improve readability of certain lines Kaartic Sivaraam
2018-01-07 0:44 ` Eric Sunshine
2018-01-08 18:49 ` Stefan Beller
2018-01-09 16:37 ` Kaartic Sivaraam
2018-01-09 19:31 ` Stefan Beller
2018-01-09 19:57 ` Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 7/8] Doc/git-submodule: improve readability and grammar of a sentence Kaartic Sivaraam
2018-01-08 18:57 ` Stefan Beller
2018-01-06 18:46 ` [PATCH 8/8] Doc/git-submodule: correctly quote important words Kaartic Sivaraam
2018-01-08 19:08 ` [PATCH 0/8] Doc/submodules: a few updates Stefan Beller
2018-01-09 17:06 ` Kaartic Sivaraam
2018-01-09 18:50 ` Stefan Beller
2018-01-10 6:49 ` [PATCH v2 0/2] " Kaartic Sivaraam
2018-01-10 6:49 ` [PATCH v2 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax Kaartic Sivaraam
2018-01-10 20:49 ` Stefan Beller
2018-01-10 6:49 ` [PATCH v2 2/2] Doc/git-submodule: improve readability and grammar of a sentence Kaartic Sivaraam
2018-01-14 17:37 ` [PATCH v3 0/2] Doc/submodules: a few updates Kaartic Sivaraam
2018-01-14 17:37 ` [PATCH v3 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax Kaartic Sivaraam
2018-01-16 20:03 ` Stefan Beller
2018-01-14 17:37 ` [PATCH v3 2/2] Doc/git-submodule: improve readability and grammar of a sentence Kaartic Sivaraam
2018-01-16 20:02 ` [PATCH v3 0/2] Doc/submodules: a few updates Junio C Hamano
2018-01-17 2:45 ` Kaartic Sivaraam
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20180106184614.20115-1-kaartic.sivaraam@gmail.com \
--to=kaartic.sivaraam@gmail.com \
--cc=git@vger.kernel.org \
--cc=sbeller@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).