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 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax
Date: Sun, 14 Jan 2018 23:07:36 +0530 [thread overview]
Message-ID: <20180114173737.13012-2-kaartic.sivaraam@gmail.com> (raw)
In-Reply-To: <20180114173737.13012-1-kaartic.sivaraam@gmail.com>
* Only mention porcelain commands in examples
* Split a sentence for better readability
* Add missing apostrophes
* Clearly specify the advantages of using submodules
* Avoid abbreviations
* Use "Git" consistently
* Improve readability of certain lines
* Clarify when a submodule is considered active
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Helped-by: Stefan Beller <sbeller@google.com>
Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
---
Documentation/gitsubmodules.txt | 100 +++++++++++++++++++++++++++++++---------
1 file changed, 79 insertions(+), 21 deletions(-)
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt
index 46cf120f6..4d6c17782 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.txt
@@ -36,8 +36,8 @@ The `gitlink` entry contains the object name of the commit that the
superproject expects the submodule’s working directory to be at.
The section `submodule.foo.*` in the `.gitmodules` file gives additional
-hints to Gits porcelain layer such as where to obtain the submodule via
-the `submodule.foo.url` setting.
+hints to Git's porcelain layer. For example, the `submodule.foo.url`
+setting specifies where to obtain the submodule.
Submodules can be used for at least two different use cases:
@@ -51,18 +51,21 @@ Submodules can be used for at least two different use cases:
2. Splitting a (logically single) project into multiple
repositories and tying them back together. This can be used to
- overcome current limitations of Gits implementation to have
+ overcome current limitations of Git's implementation to have
finer grained access:
- * Size of the git repository:
+ * Size of the Git repository:
In its current form Git scales up poorly for large repositories containing
content that is not compressed by delta computation between trees.
- However you can also use submodules to e.g. hold large binary assets
- and these repositories are then shallowly cloned such that you do not
+ For example, you can use submodules to hold large binary assets
+ and these repositories can be shallowly cloned such that you do not
have a large history locally.
* Transfer size:
In its current form Git requires the whole working tree present. It
does not allow partial trees to be transferred in fetch or clone.
+ If the project you work on consists of multiple repositories tied
+ together as submodules in a superproject, you can avoid fetching the
+ working trees of the repositories you are not interested in.
* Access control:
By restricting user access to submodules, this can be used to implement
read/write policies for different users.
@@ -73,9 +76,10 @@ The configuration of submodules
Submodule operations can be configured using the following mechanisms
(from highest to lowest precedence):
- * The command line for those commands that support taking submodule specs.
- Most commands have a boolean flag '--recurse-submodules' whether to
- recurse into submodules. Examples are `ls-files` or `checkout`.
+ * The command line for those commands that support taking submodules
+ as part of their pathspecs. Most commands have a boolean flag
+ `--recurse-submodules` which specify whether to recurse into submodules.
+ Examples are `grep` and `checkout`.
Some commands take enums, such as `fetch` and `push`, where you can
specify how submodules are affected.
@@ -87,8 +91,8 @@ Submodule operations can be configured using the following mechanisms
For example an effect from the submodule's `.gitignore` file
would be observed when you run `git status --ignore-submodules=none` in
the superproject. This collects information from the submodule's working
-directory by running `status` in the submodule, which does pay attention
-to its `.gitignore` file.
+directory by running `status` in the submodule while paying attention
+to the `.gitignore` file of the submodule.
+
The submodule's `$GIT_DIR/config` file would come into play when running
`git push --recurse-submodules=check` in the superproject, as this would
@@ -97,20 +101,20 @@ remotes are configured in the submodule as usual in the `$GIT_DIR/config`
file.
* 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.
+ Git only recurses into active submodules (see "ACTIVE SUBMODULES"
+ section below).
+
If the submodule is not yet initialized, then the configuration
-inside the submodule does not exist yet, so configuration where to
+inside the submodule does not exist yet, so where to
obtain the submodule from is configured here for example.
- * the `.gitmodules` file inside the superproject. Additionally to the
- required mapping between submodule's name and path, a project usually
+ * The `.gitmodules` file inside the superproject. A project usually
uses this file to suggest defaults for the upstream collection
- of repositories.
+ of repositories for the mapping that is required between a
+ submodule's name and its path.
+
-This file mainly serves as the mapping between name and path in
-the superproject, such that the submodule's git directory can be
+This file mainly serves as the mapping between the name and path of submodules
+in the superproject, such that the submodule's Git directory can be
located.
+
If the submodule has never been initialized, this is the only place
@@ -137,8 +141,8 @@ directory is automatically moved to `$GIT_DIR/modules/<name>/`
of the superproject.
* Deinitialized submodule: A `gitlink`, and a `.gitmodules` entry,
-but no submodule working directory. The submodule’s git directory
-may be there as after deinitializing the git directory is kept around.
+but no submodule working directory. The submodule’s Git directory
+may be there as after deinitializing the Git directory is kept around.
The directory which is supposed to be the working directory is empty instead.
+
A submodule can be deinitialized by running `git submodule deinit`.
@@ -160,6 +164,60 @@ from another repository.
To completely remove a submodule, manually delete
`$GIT_DIR/modules/<name>/`.
+ACTIVE SUBMODULES
+-----------------
+
+A submodule is considered active,
+
+ (a) if `submodule.<name>.active` is set to `true`
+ or
+ (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
+
+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
+(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
+
+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, regardless of the
+presence of the .url field.
+
Workflow for a third party library
----------------------------------
--
2.16.0.rc1.281.g969645f98
next prev parent reply other threads:[~2018-01-14 17:38 UTC|newest]
Thread overview: 44+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-01-06 18:46 [PATCH 0/8] Doc/submodules: a few updates 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 ` [PATCH v3 0/2] Doc/submodules: a few updates Kaartic Sivaraam
2018-01-14 17:37 ` Kaartic Sivaraam [this message]
2018-01-16 20:03 ` [PATCH v3 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax 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=20180114173737.13012-2-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
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).