git@vger.kernel.org mailing list mirror (one of many)
 help / Atom feed
From: Stefan Beller <sbeller@google.com>
To: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
Cc: Git mailing list <git@vger.kernel.org>,
	Eric Sunshine <sunshine@sunshineco.com>,
	Jon Forrest <nobozo@gmail.com>
Subject: Re: [PATCH v3 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax
Date: Tue, 16 Jan 2018 12:03:52 -0800
Message-ID: <CAGZ79kZYidKKCNF1=ZCZaOgpNZu-tuaD4_56V1DTd9++_8YN=Q@mail.gmail.com> (raw)
In-Reply-To: <20180114173737.13012-2-kaartic.sivaraam@gmail.com>

On Sun, Jan 14, 2018 at 9:37 AM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> * 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>
> ---

Thanks,
Stefan

>  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
>

  reply index

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     ` [PATCH v3 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax Kaartic Sivaraam
2018-01-16 20:03       ` Stefan Beller [this message]
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='CAGZ79kZYidKKCNF1=ZCZaOgpNZu-tuaD4_56V1DTd9++_8YN=Q@mail.gmail.com' \
    --to=sbeller@google.com \
    --cc=git@vger.kernel.org \
    --cc=kaartic.sivaraam@gmail.com \
    --cc=nobozo@gmail.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