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>
Cc: Eric Sunshine <sunshine@sunshineco.com>, Jon Forrest <nobozo@gmail.com>
Subject: [PATCH v3 0/2]  Doc/submodules: a few updates
Date: Sun, 14 Jan 2018 23:07:35 +0530
Message-ID: <20180114173737.13012-1-kaartic.sivaraam@gmail.com> (raw)
In-Reply-To: <20180110064959.5491-1-kaartic.sivaraam@gmail.com>

Quoting from v1,

    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.

Changes since v2:

   - Made some changes suggested by Stefan.
   - A few more that caught my eyes.

Inter diff between v2 and v3:

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 801d291ca..71c5618e8 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -70,8 +70,8 @@ status [--cached] [--recursive] [--] [<path>...]::
 	Show the status of the submodules. This will print the SHA-1 of the
 	currently checked out commit for each submodule, along with the
 	submodule path and the output of 'git describe' for the
-	SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not
-	initialized, `+` if the currently checked out submodule commit
+	SHA-1. Each SHA-1 will possibly be prefixed with `-` if the submodule is
+	not initialized, `+` if the currently checked out submodule commit
 	does not match the SHA-1 found in the index of the containing
 	repository and `U` if the submodule has merge conflicts.
 +
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt
index ce2369c2d..47bbc62e8 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.txt
@@ -101,7 +101,7 @@ remotes are configured in the submodule as usual in the `$GIT_DIR/config`
 file.
 
  * The configuration file `$GIT_DIR/config` in the superproject.
-   Git only recurses into active submodules (see 'ACTIVE SUBMODULES'
+   Git only recurses into active submodules (see "ACTIVE SUBMODULES"
    section below).
 +
 If the submodule is not yet initialized, then the configuration
@@ -164,52 +164,59 @@ from another repository.
 To completely remove a submodule, manually delete
 `$GIT_DIR/modules/<name>/`.
 
-Active submodules
+ACTIVE SUBMODULES
 -----------------
 
 A submodule is considered active,
 
-  (a) if `submodule.<name>.active` is set
+  (a) if `submodule.<name>.active` is set to `true`
      or
-  (b) if the submodules path matches the pathspec in `submodule.active`
+  (b) if the submodule's path matches the pathspec in `submodule.active`
      or
   (c) if `submodule.<name>.url` is set.
 
+and these are evaluated in this order.
+
 For example:
 
-    [submodule "foo"]
-        active = false
-        url = https://example.org/foo
-    [submodule "bar"]
-        active = true
-        url = https://example.org/bar
-    [submodule "baz"]
-        url = https://example.org/baz
+  [submodule "foo"]
+    active = false
+    url = https://example.org/foo
+  [submodule "bar"]
+    active = true
+    url = https://example.org/bar
+  [submodule "baz"]
+    url = https://example.org/baz
 
-In the above config only the submodule bar and baz are active,
-bar due to (a) and baz due to (c).
+In the above config only the submodule 'bar' and 'baz' are active,
+'bar' due to (a) and 'baz' due to (c). 'foo' is inactive because
+(a) takes precedence over (c).
 
-Note that '(c)' is a historical artefact and will be ignored if the
-pathspec set in (b) excludes the submodule. For example:
+Note that (c) is a historical artefact and will be ignored if the
+(a) and (b) specify that the submodule is not active. In other words,
+if we have an `submodule.<name>.active` set to `false` or if the
+submodule's path is excluded in the pathspec in `submodule.active`, the
+url doesn't matter whether it is present or not. This is illustrated in
+the example that follows.
 
-    [submodule "foo"]
-        active = true
-        url = https://example.org/foo
-    [submodule "bar"]
-        url = https://example.org/bar
-    [submodule "baz"]
-        url = https://example.org/baz
-    [submodule "bob"]
-        ignore = true
-    [submodule]
-        active = b*
-        active = (:exclude) baz
+  [submodule "foo"]
+    active = true
+    url = https://example.org/foo
+  [submodule "bar"]
+    url = https://example.org/bar
+  [submodule "baz"]
+    url = https://example.org/baz
+  [submodule "bob"]
+    ignore = true
+  [submodule]
+    active = b*
+    active = :(exclude) baz
 
-In here all submodules except baz (foo, bar, bob) are active.
+In here all submodules except 'baz' (foo, bar, bob) are active.
 'foo' due to its own active flag and all the others due to the
 submodule active pathspec, which specifies that any submodule
-starting with 'b' except 'baz' are also active, no matter if
-the .url field is present.
+starting with 'b' except 'baz' are also active, regardless of the
+presence of the .url field.
 
 Workflow for a third party library
 ----------------------------------



Kaartic Sivaraam (2):
  Doc/gitsubmodules: make some changes to improve readability and syntax
  Doc/git-submodule: improve readability and grammar of a sentence

 Documentation/git-submodule.txt |  16 +++----
 Documentation/gitsubmodules.txt | 100 +++++++++++++++++++++++++++++++---------
 2 files changed, 87 insertions(+), 29 deletions(-)

-- 
2.16.0.rc1.281.g969645f98


  parent reply index

Thread overview: 44+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-01-06 18:46 [PATCH 0/8] " Kaartic Sivaraam
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   ` Kaartic Sivaraam [this message]
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 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=20180114173737.13012-1-kaartic.sivaraam@gmail.com \
    --to=kaartic.sivaraam@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=nobozo@gmail.com \
    --cc=sbeller@google.com \
    --cc=sunshine@sunshineco.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