Commit 60736db1 authored by Junio C Hamano's avatar Junio C Hamano

Merge branch 'ks/submodule-doc-updates' into maint

Doc updates.

* ks/submodule-doc-updates:
  Doc/git-submodule: improve readability and grammar of a sentence
  Doc/gitsubmodules: make some changes to improve readability and syntax
parents b1bdf46b e1b3f3dd
......@@ -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.
+
......@@ -132,15 +132,15 @@ expects by cloning missing submodules and updating the working tree of
the submodules. The "updating" can be done in several ways depending
on command line options and the value of `submodule.<name>.update`
configuration variable. The command line option takes precedence over
the configuration variable. if neither is given, a checkout is performed.
update procedures supported both from the command line as well as setting
`submodule.<name>.update`:
the configuration variable. If neither is given, a 'checkout' is performed.
The 'update' procedures supported both from the command line as well as
through the `submodule.<name>.update` configuration are:
checkout;; the commit recorded in the superproject will be
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), even if the commit specified
`git checkout --force`), even if the commit specified
in the index of the containing repository already matches the commit
checked out in the submodule.
......@@ -150,8 +150,8 @@ checked out in the submodule.
merge;; the commit recorded in the superproject will be merged
into the current branch in the submodule.
The following procedures are only available via the `submodule.<name>.update`
configuration variable:
The following 'update' procedures are only available via the
`submodule.<name>.update` configuration variable:
custom command;; arbitrary shell command that takes a single
argument (the sha1 of the commit recorded in the
......
......@@ -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
----------------------------------
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment