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>,
	Eric Sunshine <sunshine@sunshineco.com>
Cc: Jon Forrest <nobozo@gmail.com>
Subject: [PATCH v2 0/2] Doc/submodules: a few updates
Date: Wed, 10 Jan 2018 12:19:57 +0530
Message-ID: <20180110064959.5491-1-kaartic.sivaraam@gmail.com> (raw)
In-Reply-To: <20180106184614.20115-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.

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


  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 ` Kaartic Sivaraam [this message]
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
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=20180110064959.5491-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