git@vger.kernel.org mailing list mirror (one of many)
 help / Atom feed
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
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


             reply index

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-01-06 18:46 Kaartic Sivaraam [this message]
2018-01-08 19:08 ` Stefan Beller
2018-01-09 17:06   ` Kaartic Sivaraam
2018-01-09 18:50     ` Stefan Beller

Reply instructions:

You may reply publically 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

git@vger.kernel.org mailing list mirror (one of many)

Archives are clonable:
	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.org/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/
       or Tor2web: https://www.tor2web.org/

AGPL code for this site: git clone https://public-inbox.org/ public-inbox