[PATCH v2 0/2] Doc/submodules: a few updates
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.Change since v2:
I've squashed the fine grained patches into 2 patches that touch two distinct
documents. This v2 conatins a lot of changes suggested for v1 and few that I
caught by myself since v1.
This patch is based on 'master' just like v1.
Inter-word-diff v1..v2:
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 5c4d941cc..801d291ca 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -140,7 +140,7 @@ through the `submodule.<name>.update` configuration are:
checked out in the submodule on a detached HEAD.
+
If `--force` is specified, the submodule will be checked out (using
`git checkout [---force` if appropriate),-]{+--force`),+} even if the commit specified
in the index of the containing repository already matches the commit
checked out in the submodule.
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt
index 339fb73db..ce2369c2d 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.txt
@@ -36,7 +36,7 @@ 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-]{+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,21 +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-]{+Git's+} implementation to have
finer grained access:
* Size of the [-git-]{+Git+} repository:
In its current form Git scales up poorly for large repositories containing
content that is not compressed by delta computation between trees.
[-Therefore-]{+For example,+} you can use submodules to hold large binary assets
and these repositories [-are then-]{+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 [-you have your-]{+the+} project [-as-]{+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.
@@ -76,10 +76,10 @@ The configuration of submodules
Submodule operations can be configured using the following mechanisms
(from highest to lowest precedence):
* The command line [-arguments of-]{+for+} those commands that support taking [-submodule-]
[- specifications.-]{+submodules+}
{+ as part of their pathspecs.+} Most commands have a boolean flag
[-'--recurse-submodules'-]{+`--recurse-submodules`+} which specify whether [-they should-]{+to+} recurse into submodules.
Examples are [-`ls-files` or-]{+`grep` and+} `checkout`.
Some commands take enums, such as `fetch` and `push`, where you can
specify how submodules are affected.
@@ -101,17 +101,17 @@ 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-]{+Git only recurses+} into [-at all via the `active` flag for example.-]{+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
obtain the submodule from is configured here for example.
* The `.gitmodules` file inside the superproject. [-Additionally, if mapping-]
[- is required between a submodule's name and its path, a-]{+A+} project usually
uses this file to suggest defaults for the upstream collection
of [-repositories.-]{+repositories for the mapping that is required between a+}
{+ submodule's name and its path.+}
+
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
@@ -141,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-]{+Git+} directory
may be there as after deinitializing the [-git-]{+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`.
@@ -164,6 +164,53 @@ 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+}
{+ or+}
{+ (b) if the submodules path matches the pathspec in `submodule.active`+}
{+ or+}
{+ (c) if `submodule.<name>.url` is set.+}
{+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).+}
{+Note that '(c)' is a historical artefact and will be ignored if the+}
{+pathspec set in (b) excludes the submodule. For example:+}
{+ [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, no matter if+}
{+the .url field is present.+}
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 | 12 +++---
Documentation/gitsubmodules.txt | 93 +++++++++++++++++++++++++++++++----------
2 files changed, 78 insertions(+), 27 deletions(-)
--
2.16.0.rc0.223.g4a4ac8367
Kaartic Sivaraam <kaartic.sivaraam@gmail.com>