{"thread":{"id":"47553","subject":"[PATCH 0/8] Doc/submodules: a few updates","startedAt":"2018-01-06T18:46:41Z","lastAt":"2018-01-17T02:45:50Z","messageCount":44,"participants":["Kaartic Sivaraam","Eric Sunshine","Stefan Beller","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":8},"messages":[{"id":"336059","messageId":"20180106184614.20115-1-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":null,"subject":"[PATCH 0/8] Doc/submodules: a few updates","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-06T18:46:06Z","receivedAt":"2018-01-06T18:46:41Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"These are just a few improvements that I thought would make the documentation\nrelated to submodules a little better in various way such as readability,\nconsistency etc., These were things I noticed while reading thise documents.\n\nSorry, for the highly granular patches. I did the commits as and when I was\nreading them and tried to keep them focused to one particular change by rebasing\nthem as needed. In case they need some change, let me know. \n\nI based these patches on top of 'master'.\n\nApart from the changes, I saw a few things that needed improvement/clarification\nbut wasn't able to do that myself due to my limited knowledge of submodules. They\nare listed below. I'll add in patches for them if they are correctly clarified.\n\n\n1.\n\n man gitsubmodules\n\n · The configuration file $GIT_DIR/config in the superproject. Typical configuration at this place is controlling if a submodule is\n recursed into at all via the active flag for example.\n\n If the submodule is not yet initialized, then the configuration inside the submodule does not exist yet, so configuration where to\n obtain the submodule from is configured here for example.\n\nWhat's the \"active flag\" mentioned above? Also I find the phrase \"is recursed into at all\"\nto be a little slippery. How could it be improved?\n\n\n2.\n\n man git submodule\n\n update\n ...\n\n checkout\n ....\n\n If --force is specified, the submodule will be checked out (using git checkout --force if appropriate), even if the commit\n specified in the index of the containing repository already matches the commit checked out in the submodule.\n\nI'm not sure this is conveying all the information it should be conveying.\nIt seems to making the user wonder, \"How at all does 'git submodule update --force'\ndiffers from 'git submodule update'?\" also \"using git checkout --force if appropriate\"\nseems to be invoking all sorts confusion as \"appropriate\" is superfluous.\n\nHow could these confusions be clarified?\n\n\n---\nKaartic\n\n\nKaartic Sivaraam (8):\n Doc/gitsubmodules: split a sentence for better readability\n Doc/gitsubmodules: clearly specify advantage of submodule\n Doc/gitsubmodules: specify how submodules help in reduced size\n Doc/gitsubmodules: avoid abbreviations\n Doc/gitsubmodules: use \"Git directory\" consistently\n Doc/gitsubmodules: improve readability of certain lines\n Doc/git-submodule: improve readability and grammar of a sentence\n Doc/git-submodule: correctly quote important words\n\n Documentation/git-submodule.txt | 10 +++++-----\n Documentation/gitsubmodules.txt | 28 ++++++++++++++++------------\n 2 files changed, 21 insertions(+), 17 deletions(-)\n\n-- \n2.16.0.rc0.223.g4a4ac8367\n\n"},{"id":"336060","messageId":"20180106184614.20115-2-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-1-kaartic.sivaraam@gmail.com","subject":"[PATCH 1/8] Doc/gitsubmodules: split a sentence for better readability","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-06T18:46:07Z","receivedAt":"2018-01-06T18:46:44Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Signed-off-by: Kaartic Sivaraam \n---\n Documentation/gitsubmodules.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex 46cf120f6..bf46b0fb5 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -36,8 +36,8 @@ The `gitlink` entry contains the object name of the commit that the\n superproject expects the submodule’s working directory to be at.\n \n The section `submodule.foo.*` in the `.gitmodules` file gives additional\n-hints to Gits porcelain layer such as where to obtain the submodule via\n-the `submodule.foo.url` setting.\n+hints to Gits porcelain layer. For example, the `submodule.foo.url`\n+setting specifies where to obtain the submodule.\n \n Submodules can be used for at least two different use cases:\n \n-- \n2.16.0.rc0.223.g4a4ac8367\n\n"},{"id":"336061","messageId":"20180106184614.20115-3-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-1-kaartic.sivaraam@gmail.com","subject":"[PATCH 2/8] Doc/gitsubmodules: clearly specify advantage of submodule","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-06T18:46:08Z","receivedAt":"2018-01-06T18:46:45Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Signed-off-by: Kaartic Sivaraam \n---\n Documentation/gitsubmodules.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex bf46b0fb5..cb795c6b6 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -57,7 +57,7 @@ Submodules can be used for at least two different use cases:\n * Size of the git repository:\n In its current form Git scales up poorly for large repositories containing\n content that is not compressed by delta computation between trees.\n- However you can also use submodules to e.g. hold large binary assets\n+ Therefore you can use submodules to hold large binary assets\n and these repositories are then shallowly cloned such that you do not\n have a large history locally.\n * Transfer size:\n-- \n2.16.0.rc0.223.g4a4ac8367\n\n"},{"id":"336062","messageId":"20180106184614.20115-4-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-1-kaartic.sivaraam@gmail.com","subject":"[PATCH 3/8] Doc/gitsubmodules: specify how submodules help in reduced size","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-06T18:46:09Z","receivedAt":"2018-01-06T18:46:49Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Signed-off-by: Kaartic Sivaraam \n---\n Documentation/gitsubmodules.txt | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex cb795c6b6..3f73983d5 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -63,6 +63,9 @@ Submodules can be used for at least two different use cases:\n * Transfer size:\n In its current form Git requires the whole working tree present. It\n does not allow partial trees to be transferred in fetch or clone.\n+ If you have your project as multiple repositories tied together as\n+ submodules in a superproject, you can avoid fetching the working\n+ trees of the repositories you are not interested in.\n * Access control:\n By restricting user access to submodules, this can be used to implement\n read/write policies for different users.\n-- \n2.16.0.rc0.223.g4a4ac8367\n\n"},{"id":"336063","messageId":"20180106184614.20115-5-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-1-kaartic.sivaraam@gmail.com","subject":"[PATCH 4/8] Doc/gitsubmodules: avoid abbreviations","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-06T18:46:10Z","receivedAt":"2018-01-06T18:46:51Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Signed-off-by: Kaartic Sivaraam \n---\n Documentation/gitsubmodules.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex 3f73983d5..e3c798d2a 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -76,9 +76,9 @@ The configuration of submodules\n Submodule operations can be configured using the following mechanisms\n (from highest to lowest precedence):\n \n- * The command line for those commands that support taking submodule specs.\n- Most commands have a boolean flag '--recurse-submodules' whether to\n- recurse into submodules. Examples are `ls-files` or `checkout`.\n+ * The command line for those commands that support taking submodule\n+ specifications. Most commands have a boolean flag '--recurse-submodules\n+ whether to recurse into submodules. Examples are `ls-files` or `checkout`.\n Some commands take enums, such as `fetch` and `push`, where you can\n specify how submodules are affected.\n \n-- \n2.16.0.rc0.223.g4a4ac8367\n\n"},{"id":"336064","messageId":"20180106184614.20115-6-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-1-kaartic.sivaraam@gmail.com","subject":"[PATCH 5/8] Doc/gitsubmodules: use \"Git directory\" consistently","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-06T18:46:11Z","receivedAt":"2018-01-06T18:46:54Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Signed-off-by: Kaartic Sivaraam \n---\n Documentation/gitsubmodules.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex e3c798d2a..745a3838e 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -113,7 +113,7 @@ obtain the submodule from is configured here for example.\n of repositories.\n +\n This file mainly serves as the mapping between name and path in\n-the superproject, such that the submodule's git directory can be\n+the superproject, such that the submodule's Git directory can be\n located.\n +\n If the submodule has never been initialized, this is the only place\n-- \n2.16.0.rc0.223.g4a4ac8367\n\n"},{"id":"336065","messageId":"20180106184614.20115-7-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-1-kaartic.sivaraam@gmail.com","subject":"[PATCH 6/8] Doc/gitsubmodules: improve readability of certain lines","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-06T18:46:12Z","receivedAt":"2018-01-06T18:46:56Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Signed-off-by: Kaartic Sivaraam \n---\n Documentation/gitsubmodules.txt | 19 ++++++++++---------\n 1 file changed, 10 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex 745a3838e..339fb73db 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -76,9 +76,10 @@ The configuration of submodules\n Submodule operations can be configured using the following mechanisms\n (from highest to lowest precedence):\n \n- * The command line for those commands that support taking submodule\n- specifications. Most commands have a boolean flag '--recurse-submodules\n- whether to recurse into submodules. Examples are `ls-files` or `checkout`.\n+ * The command line arguments of those commands that support taking submodule\n+ specifications. Most commands have a boolean flag '--recurse-submodules'\n+ which specify whether they should recurse into submodules. Examples are\n+ `ls-files` or `checkout`.\n Some commands take enums, such as `fetch` and `push`, where you can\n specify how submodules are affected.\n \n@@ -90,8 +91,8 @@ Submodule operations can be configured using the following mechanisms\n For example an effect from the submodule's `.gitignore` file\n would be observed when you run `git status --ignore-submodules=none` in\n the superproject. This collects information from the submodule's working\n-directory by running `status` in the submodule, which does pay attention\n-to its `.gitignore` file.\n+directory by running `status` in the submodule while paying attention\n+to the `.gitignore` file of the submodule.\n +\n The submodule's `$GIT_DIR/config` file would come into play when running\n `git push --recurse-submodules=check` in the superproject, as this would\n@@ -107,13 +108,13 @@ If the submodule is not yet initialized, then the configuration\n inside the submodule does not exist yet, so configuration where to\n obtain the submodule from is configured here for example.\n \n- * the `.gitmodules` file inside the superproject. Additionally to the\n- required mapping between submodule's name and path, a project usually\n+ * The `.gitmodules` file inside the superproject. Additionally, if mapping\n+ is required between a submodule's name and its path, a project usually\n uses this file to suggest defaults for the upstream collection\n of repositories.\n +\n-This file mainly serves as the mapping between name and path in\n-the superproject, such that the submodule's Git directory can be\n+This file mainly serves as the mapping between the name and path of submodules\n+in the superproject, such that the submodule's Git directory can be\n located.\n +\n If the submodule has never been initialized, this is the only place\n-- \n2.16.0.rc0.223.g4a4ac8367\n\n"},{"id":"336066","messageId":"20180106184614.20115-8-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-1-kaartic.sivaraam@gmail.com","subject":"[PATCH 7/8] Doc/git-submodule: improve readability and grammar of a sentence","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-06T18:46:13Z","receivedAt":"2018-01-06T18:47:00Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Signed-off-by: Kaartic Sivaraam \n---\n Documentation/git-submodule.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex ff612001d..befbccde6 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -132,9 +132,9 @@ expects by cloning missing submodules and updating the working tree of\n the submodules. The \"updating\" can be done in several ways depending\n on command line options and the value of `submodule..update`\n configuration variable. The command line option takes precedence over\n-the configuration variable. if neither is given, a checkout is performed.\n-update procedures supported both from the command line as well as setting\n-`submodule..update`:\n+the configuration variable. If neither is given, a checkout is performed.\n+The update procedures supported both from the command line as well as\n+through the `submodule..update` configuration are:\n \n \tcheckout;; the commit recorded in the superproject will be\n \t checked out in the submodule on a detached HEAD.\n-- \n2.16.0.rc0.223.g4a4ac8367\n\n"},{"id":"336067","messageId":"20180106184614.20115-9-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-1-kaartic.sivaraam@gmail.com","subject":"[PATCH 8/8] Doc/git-submodule: correctly quote important words","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-06T18:46:14Z","receivedAt":"2018-01-06T18:47:02Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Signed-off-by: Kaartic Sivaraam \n---\n Documentation/git-submodule.txt | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex befbccde6..5c4d941cc 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -132,8 +132,8 @@ expects by cloning missing submodules and updating the working tree of\n the submodules. The \"updating\" can be done in several ways depending\n on command line options and the value of `submodule..update`\n configuration variable. The command line option takes precedence over\n-the configuration variable. If neither is given, a checkout is performed.\n-The update procedures supported both from the command line as well as\n+the configuration variable. If neither is given, a 'checkout' is performed.\n+The 'update' procedures supported both from the command line as well as\n through the `submodule..update` configuration are:\n \n \tcheckout;; the commit recorded in the superproject will be\n@@ -150,8 +150,8 @@ checked out in the submodule.\n \tmerge;; the commit recorded in the superproject will be merged\n \t into the current branch in the submodule.\n \n-The following procedures are only available via the `submodule..update`\n-configuration variable:\n+The following 'update' procedures are only available via the\n+`submodule..update` configuration variable:\n \n \tcustom command;; arbitrary shell command that takes a single\n \t argument (the sha1 of the commit recorded in the\n-- \n2.16.0.rc0.223.g4a4ac8367\n\n"},{"id":"336075","messageId":"CAPig+cQb1G0H5FS9bMmrqv=T45XoRwp2-2vUAEDayd0hV8PwYA@mail.gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-2-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH 1/8] Doc/gitsubmodules: split a sentence for better readability","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2018-01-07T00:29:26Z","receivedAt":"2018-01-07T00:29:34Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, Jan 6, 2018 at 1:46 PM, Kaartic Sivaraam\n wrote:\n> Signed-off-by: Kaartic Sivaraam \n> ---\n> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n> @@ -36,8 +36,8 @@ The `gitlink` entry contains the object name of the commit that the\n> The section `submodule.foo.*` in the `.gitmodules` file gives additional\n> -hints to Gits porcelain layer such as where to obtain the submodule via\n> -the `submodule.foo.url` setting.\n> +hints to Gits porcelain layer. For example, the `submodule.foo.url`\n> +setting specifies where to obtain the submodule.\n\nI don't find the original difficult to read (aside, perhaps, from the\nmissing comma before \"such as\"), so I don't feel strongly about this\nchange.\n\nHowever, since you're touching this, you could apply the s/Gits/Git's/ fix.\n"},{"id":"336076","messageId":"CAPig+cSh=Hv7x1J8nydSrbgbaLR+JLhXMqpR42a0+m=OgL59JQ@mail.gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-4-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH 3/8] Doc/gitsubmodules: specify how submodules help in reduced size","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2018-01-07T00:31:23Z","receivedAt":"2018-01-07T00:31:29Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, Jan 6, 2018 at 1:46 PM, Kaartic Sivaraam\n wrote:\n> Signed-off-by: Kaartic Sivaraam \n> ---\n> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n> @@ -63,6 +63,9 @@ Submodules can be used for at least two different use cases:\n> * Transfer size:\n> In its current form Git requires the whole working tree present. It\n> does not allow partial trees to be transferred in fetch or clone.\n> + If you have your project as multiple repositories tied together as\n> + submodules in a superproject, you can avoid fetching the working\n> + trees of the repositories you are not interested in.\n\n\"If your project consists of multiple repositories tied together...\"\n"},{"id":"336077","messageId":"CAPig+cS2PAGm1OfQLOv+MOOvbUnFOUtfzXLOFfVNAD_VOhfntQ@mail.gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-5-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH 4/8] Doc/gitsubmodules: avoid abbreviations","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2018-01-07T00:36:27Z","receivedAt":"2018-01-07T00:36:33Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, Jan 6, 2018 at 1:46 PM, Kaartic Sivaraam\n wrote:\n> Signed-off-by: Kaartic Sivaraam \n> ---\n> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n> @@ -76,9 +76,9 @@ The configuration of submodules\n> - * The command line for those commands that support taking submodule specs.\n> - Most commands have a boolean flag '--recurse-submodules' whether to\n> - recurse into submodules. Examples are `ls-files` or `checkout`.\n> + * The command line for those commands that support taking submodule\n> + specifications. Most commands have a boolean flag '--recurse-submodules\n> + whether to recurse into submodules. Examples are `ls-files` or `checkout`.\n\nYour change loses the closing quote on --recurse-submodules.\n\nAlso, since you're touching this, it wouldn't hurt to address the\ngrammatical shortcoming(s), as well. To wit: Something is missing\nbetween \"--recurse-submodules\" and \"whether\".\n"},{"id":"336078","messageId":"CAPig+cRX6uJWzPNMaMoWdjcDGQqjMUz8Z5b3Gnhg3OOgHBBWOg@mail.gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-6-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH 5/8] Doc/gitsubmodules: use \"Git directory\" consistently","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2018-01-07T00:39:09Z","receivedAt":"2018-01-07T00:39:14Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, Jan 6, 2018 at 1:46 PM, Kaartic Sivaraam\n wrote:\n> Signed-off-by: Kaartic Sivaraam \n> ---\n> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n> @@ -113,7 +113,7 @@ obtain the submodule from is configured here for example.\n> This file mainly serves as the mapping between name and path in\n> -the superproject, such that the submodule's git directory can be\n> +the superproject, such that the submodule's Git directory can be\n> located.\n\nThere are two more instances of this capitalization inconsistency\nlater in the file. This patch probably ought to address all of them.\n"},{"id":"336079","messageId":"CAPig+cSqq508-mTCpMW62DvE90a_vK7cOQ5xJD9Krj1BL3=d3Q@mail.gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-7-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH 6/8] Doc/gitsubmodules: improve readability of certain lines","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2018-01-07T00:44:35Z","receivedAt":"2018-01-07T00:44:41Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sat, Jan 6, 2018 at 1:46 PM, Kaartic Sivaraam\n wrote:\n> Signed-off-by: Kaartic Sivaraam \n> ---\n> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n> @@ -76,9 +76,10 @@ The configuration of submodules\n> - * The command line for those commands that support taking submodule\n> - specifications. Most commands have a boolean flag '--recurse-submodules\n> - whether to recurse into submodules. Examples are `ls-files` or `checkout`.\n> + * The command line arguments of those commands that support taking submodule\n> + specifications. Most commands have a boolean flag '--recurse-submodules'\n> + which specify whether they should recurse into submodules. Examples are\n> + `ls-files` or `checkout`.\n\nSo, this is addressing issues pointed out in my review of 4/8. It's\nactually fixing a problem -- missing closing quote -- introduced by\n4/8. Therefore, it probably would make sense either to move this hunk\ninto 4/8 or drop 4/8 altogether.\n"},{"id":"336161","messageId":"CAGZ79kaNujhXPPSHQZuvEAz_NLDT0Opna+W4b84-vnan-1UsOA@mail.gmail.com","threadId":"47553","inReplyTo":"CAPig+cQb1G0H5FS9bMmrqv=T45XoRwp2-2vUAEDayd0hV8PwYA@mail.gmail.com","subject":"Re: [PATCH 1/8] Doc/gitsubmodules: split a sentence for better readability","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-08T18:33:43Z","receivedAt":"2018-01-08T18:33:54Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Sat, Jan 6, 2018 at 4:29 PM, Eric Sunshine wrote:\n> On Sat, Jan 6, 2018 at 1:46 PM, Kaartic Sivaraam\n> wrote:\n>> Signed-off-by: Kaartic Sivaraam \n>> ---\n>> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n>> @@ -36,8 +36,8 @@ The `gitlink` entry contains the object name of the commit that the\n>> The section `submodule.foo.*` in the `.gitmodules` file gives additional\n>> -hints to Gits porcelain layer such as where to obtain the submodule via\n>> -the `submodule.foo.url` setting.\n>> +hints to Gits porcelain layer. For example, the `submodule.foo.url`\n>> +setting specifies where to obtain the submodule.\n>\n> I don't find the original difficult to read (aside, perhaps, from the\n> missing comma before \"such as\"), so I don't feel strongly about this\n> change.\n\nSeconded. I am neutral to this change, but as you were keen enough to\ncome up with the patch, I see no reason to reject it.\nAnyway, let's read on!\n\nThanks,\nStefan\n\n>\n> However, since you're touching this, you could apply the s/Gits/Git's/ fix.\n"},{"id":"336162","messageId":"CAGZ79kYyUcun4spUKVsOb+SucCe6=1cizrfH7hrFoyKteWZ_9w@mail.gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-3-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH 2/8] Doc/gitsubmodules: clearly specify advantage of submodule","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-08T18:36:32Z","receivedAt":"2018-01-08T18:36:40Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam\n wrote:\n> Signed-off-by: Kaartic Sivaraam \n> ---\n> Documentation/gitsubmodules.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n> index bf46b0fb5..cb795c6b6 100644\n> --- a/Documentation/gitsubmodules.txt\n> +++ b/Documentation/gitsubmodules.txt\n> @@ -57,7 +57,7 @@ Submodules can be used for at least two different use cases:\n> * Size of the git repository:\n> In its current form Git scales up poorly for large repositories containing\n> content that is not compressed by delta computation between trees.\n> - However you can also use submodules to e.g. hold large binary assets\n> + Therefore you can use submodules to hold large binary assets\n\nIf this improves readability by a lot, I'd be all for it. But this use\ncase is just\nexemplary. There are also cases of submodules that do not contain big files,\nbut e.g. have a lengthy history with lots of small files.\nSo I don't know, as I would want to keep emphasized that this is just\nan example.\n\n\n> and these repositories are then shallowly cloned such that you do not\n> have a large history locally.\n> * Transfer size:\n> --\n> 2.16.0.rc0.223.g4a4ac8367\n>\n"},{"id":"336163","messageId":"CAGZ79kYrp_DAaiDzpiWbTSvsfud=JHSO+NX3UaC4osAE3dYmmQ@mail.gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-4-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH 3/8] Doc/gitsubmodules: specify how submodules help in reduced size","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-08T18:38:35Z","receivedAt":"2018-01-08T18:38:41Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam\n wrote:\n> Signed-off-by: Kaartic Sivaraam \n> ---\n> Documentation/gitsubmodules.txt | 3 +++\n> 1 file changed, 3 insertions(+)\n>\n> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n> index cb795c6b6..3f73983d5 100644\n> --- a/Documentation/gitsubmodules.txt\n> +++ b/Documentation/gitsubmodules.txt\n> @@ -63,6 +63,9 @@ Submodules can be used for at least two different use cases:\n> * Transfer size:\n> In its current form Git requires the whole working tree present. It\n> does not allow partial trees to be transferred in fetch or clone.\n> + If you have your project as multiple repositories tied together as\n> + submodules in a superproject, you can avoid fetching the working\n> + trees of the repositories you are not interested in.\n\nYou do not fetch a working tree, but a whole repository?\n\n> * Access control:\n> By restricting user access to submodules, this can be used to implement\n> read/write policies for different users.\n> --\n> 2.16.0.rc0.223.g4a4ac8367\n>\n"},{"id":"336164","messageId":"CAGZ79kZZf=zSfqFr9EV_Q408mG4cHTEQSOAMC7n_35oKgHJp2A@mail.gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-5-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH 4/8] Doc/gitsubmodules: avoid abbreviations","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-08T18:45:01Z","receivedAt":"2018-01-08T18:45:08Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam\n wrote:\n> Signed-off-by: Kaartic Sivaraam \n> ---\n> Documentation/gitsubmodules.txt | 6 +++---\n> 1 file changed, 3 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n> index 3f73983d5..e3c798d2a 100644\n> --- a/Documentation/gitsubmodules.txt\n> +++ b/Documentation/gitsubmodules.txt\n> @@ -76,9 +76,9 @@ The configuration of submodules\n> Submodule operations can be configured using the following mechanisms\n> (from highest to lowest precedence):\n>\n> - * The command line for those commands that support taking submodule specs.\n\n++ The command line for those commands that support taking submodules\nas part of their pathspecs[1].\n++\n++[1] pathspec is an official term according to `man gitglossary`.\n\nMaybe?\n\n> - Most commands have a boolean flag '--recurse-submodules' whether to\n> - recurse into submodules. Examples are `ls-files` or `checkout`.\n> + * The command line for those commands that support taking submodule\n> + specifications. Most commands have a boolean flag '--recurse-submodules\n> + whether to recurse into submodules. Examples are `ls-files` or `checkout`.\n> Some commands take enums, such as `fetch` and `push`, where you can\n> specify how submodules are affected.\n>\n> --\n> 2.16.0.rc0.223.g4a4ac8367\n>\n"},{"id":"336166","messageId":"CAGZ79kaLLk-Fy+doj_SA4fQAVAvR3LmKgix1292S4Hs41VwxJA@mail.gmail.com","threadId":"47553","inReplyTo":"CAPig+cRX6uJWzPNMaMoWdjcDGQqjMUz8Z5b3Gnhg3OOgHBBWOg@mail.gmail.com","subject":"Re: [PATCH 5/8] Doc/gitsubmodules: use \"Git directory\" consistently","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-08T18:45:42Z","receivedAt":"2018-01-08T18:45:50Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Sat, Jan 6, 2018 at 4:39 PM, Eric Sunshine wrote:\n> On Sat, Jan 6, 2018 at 1:46 PM, Kaartic Sivaraam\n> wrote:\n>> Signed-off-by: Kaartic Sivaraam \n>> ---\n>> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n>> @@ -113,7 +113,7 @@ obtain the submodule from is configured here for example.\n>> This file mainly serves as the mapping between name and path in\n>> -the superproject, such that the submodule's git directory can be\n>> +the superproject, such that the submodule's Git directory can be\n>> located.\n>\n> There are two more instances of this capitalization inconsistency\n> later in the file. This patch probably ought to address all of them.\n\nThanks for fixing the capitalization!\n"},{"id":"336167","messageId":"CAGZ79kYPcx39VqWLAxRCQgO16=Yegq6XeCVUmX7shYomF6sz=g@mail.gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-7-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH 6/8] Doc/gitsubmodules: improve readability of certain lines","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-08T18:49:43Z","receivedAt":"2018-01-08T18:49:50Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam\n wrote:\n> Signed-off-by: Kaartic Sivaraam \n> ---\n> Documentation/gitsubmodules.txt | 19 ++++++++++---------\n> 1 file changed, 10 insertions(+), 9 deletions(-)\n>\n> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n> index 745a3838e..339fb73db 100644\n> --- a/Documentation/gitsubmodules.txt\n> +++ b/Documentation/gitsubmodules.txt\n> @@ -76,9 +76,10 @@ The configuration of submodules\n> Submodule operations can be configured using the following mechanisms\n> (from highest to lowest precedence):\n>\n> - * The command line for those commands that support taking submodule\n> - specifications. Most commands have a boolean flag '--recurse-submodules\n> - whether to recurse into submodules. Examples are `ls-files` or `checkout`.\n> + * The command line arguments of those commands that support taking submodule\n> + specifications. Most commands have a boolean flag '--recurse-submodules'\n> + which specify whether they should recurse into submodules. Examples are\n> + `ls-files` or `checkout`.\n> Some commands take enums, such as `fetch` and `push`, where you can\n> specify how submodules are affected.\n>\n> @@ -90,8 +91,8 @@ Submodule operations can be configured using the following mechanisms\n> For example an effect from the submodule's `.gitignore` file\n> would be observed when you run `git status --ignore-submodules=none` in\n> the superproject. This collects information from the submodule's working\n> -directory by running `status` in the submodule, which does pay attention\n> -to its `.gitignore` file.\n> +directory by running `status` in the submodule while paying attention\n> +to the `.gitignore` file of the submodule.\n\nBoth are grammatically correct and expressive, thanks!\n\n> +\n\nExtra spurious line?\n\n> The submodule's `$GIT_DIR/config` file would come into play when running\n> `git push --recurse-submodules=check` in the superproject, as this would\n> @@ -107,13 +108,13 @@ If the submodule is not yet initialized, then the configuration\n> inside the submodule does not exist yet, so configuration where to\n> obtain the submodule from is configured here for example.\n>\n> - * the `.gitmodules` file inside the superproject. Additionally to the\n> - required mapping between submodule's name and path, a project usually\n> + * The `.gitmodules` file inside the superproject. Additionally, if mapping\n> + is required between a submodule's name and its path, a project usually\n\nThis changes meaning, originally it tries to say:\n\n* it requires mapping path <-> names.\n* but there can be more.\n\nwhereas the new lines are:\n\n* mapping is optional\n* there can be more.\n\n> uses this file to suggest defaults for the upstream collection\n> of repositories.\n> +\n> -This file mainly serves as the mapping between name and path in\n> -the superproject, such that the submodule's Git directory can be\n> +This file mainly serves as the mapping between the name and path of submodules\n> +in the superproject, such that the submodule's Git directory can be\n> located.\n\nmakes sense!\n\nThanks,\nStefan\n\n> +\n> If the submodule has never been initialized, this is the only place\n> --\n> 2.16.0.rc0.223.g4a4ac8367\n>\n"},{"id":"336170","messageId":"CAGZ79kbiyA7g3dqxydBgN_q=NkudbgATUru+01Pi6ujSk9dVHA@mail.gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-8-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH 7/8] Doc/git-submodule: improve readability and grammar of a sentence","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-08T18:57:07Z","receivedAt":"2018-01-08T18:57:13Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam\n wrote:\n> Signed-off-by: Kaartic Sivaraam \n> ---\n> Documentation/git-submodule.txt | 6 +++---\n> 1 file changed, 3 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index ff612001d..befbccde6 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -132,9 +132,9 @@ expects by cloning missing submodules and updating the working tree of\n> the submodules. The \"updating\" can be done in several ways depending\n> on command line options and the value of `submodule..update`\n> configuration variable. The command line option takes precedence over\n> -the configuration variable. if neither is given, a checkout is performed.\n> -update procedures supported both from the command line as well as setting\n> -`submodule..update`:\n> +the configuration variable. If neither is given, a checkout is performed.\n> +The update procedures supported both from the command line as well as\n> +through the `submodule..update` configuration are:\n\nMakes sense!\nThanks,\nStefan\n\n>\n> checkout;; the commit recorded in the superproject will be\n> checked out in the submodule on a detached HEAD.\n> --\n> 2.16.0.rc0.223.g4a4ac8367\n>\n"},{"id":"336171","messageId":"CAGZ79kZ-UNCyCzmg=5PQ_p5xbmCp7HUc0=TXNBxwTjZDCnJtBg@mail.gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-1-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH 0/8] Doc/submodules: a few updates","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-08T19:08:42Z","receivedAt":"2018-01-08T19:08:49Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam\n wrote:\n> These are just a few improvements that I thought would make the documentation\n> related to submodules a little better in various way such as readability,\n> consistency etc., These were things I noticed while reading thise documents.\n>\n> Sorry, for the highly granular patches. I did the commits as and when I was\n> reading them and tried to keep them focused to one particular change by rebasing\n> them as needed. In case they need some change, let me know.\n\nWhile small patches are really appreciated for code (bisect, automated\ntesting, and\nthe general difficulty to reason about code, as a very small change\nmay affect the whole\ncode base), I am not sure if they benefit in documentation.\nDocumentation is a rather\nlocal human readable thing, so by changing one sentence we don't\naffect the understanding\nof documentation at a completely unrelated place.\n\nAlso it helps to read more than just sentence fragments, i.e. I tried\nlooking at the\nwhole paragraph for review. May I suggest to squash them all and\nresend as one patch?\n\n\n>\n> I based these patches on top of 'master'.\n\nI am not aware of other submodule patches affecting documentation in master..pu,\nso this should be easy to merge.\n\n>\n> Apart from the changes, I saw a few things that needed improvement/clarification\n> but wasn't able to do that myself due to my limited knowledge of submodules. They\n> are listed below. I'll add in patches for them if they are correctly clarified.\n>\n>\n> 1.\n>\n> man gitsubmodules\n>\n> · The configuration file $GIT_DIR/config in the superproject. Typical configuration at this place is controlling if a submodule is\n> recursed into at all via the active flag for example.\n>\n> If the submodule is not yet initialized, then the configuration inside the submodule does not exist yet, so configuration where to\n> obtain the submodule from is configured here for example.\n>\n> What's the \"active flag\" mentioned above? Also I find the phrase \"is recursed into at all\"\n> to be a little slippery. How could it be improved?\n\nThere are multiple ways to indicate if a submodule is \"active\", i.e. if Git is\nsupposed to pay attention. Historically we had to set the\nsubmodule..url flag in the config, but last year Brandon added\nsubmodule.active as well as submodule..active which supersede\nthe .url flag.\n\n(See is_submodule_active() in submodule.c to see the definitive answer to\n\"should Git pay attention?\")\nhttps://github.com/git/git/blob/master/submodule.c#L224\n\nI wonder if this indicates a lack of documentation when the active\nflags were introduced.\nThey are found in 'man git config', but maybe we need to spell them\nout explicitly\nin the submodule related docs.\n\n> 2.\n>\n> man git submodule\n>\n> update\n> ...\n>\n> checkout\n> ....\n>\n> If --force is specified, the submodule will be checked out (using git checkout --force if appropriate), even if the commit\n> specified in the index of the containing repository already matches the commit checked out in the submodule.\n>\n> I'm not sure this is conveying all the information it should be conveying.\n> It seems to making the user wonder, \"How at all does 'git submodule update --force'\n> differs from 'git submodule update'?\" also \"using git checkout --force if appropriate\"\n> seems to be invoking all sorts confusion as \"appropriate\" is superfluous.\n\nWhen \"submodule update\" is invoked with the `--force` flag, that flag is passed\non to the 'checkout' operation. If you do not give the --force, then\nthe checkout\nwill also be done without --force.\n\n>\n> How could these confusions be clarified?\n\nI tried giving an alternative snippet above, not sure how else to tell.\n"},{"id":"336262","messageId":"19bb76a0-3360-65f8-4933-404addbdc767@gmail.com","threadId":"47553","inReplyTo":"CAGZ79kYyUcun4spUKVsOb+SucCe6=1cizrfH7hrFoyKteWZ_9w@mail.gmail.com","subject":"Re: [PATCH 2/8] Doc/gitsubmodules: clearly specify advantage of submodule","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-09T15:58:02Z","receivedAt":"2018-01-09T15:58:21Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":">> content that is not compressed by delta computation between trees.\n>> - However you can also use submodules to e.g. hold large binary assets\n>> + Therefore you can use submodules to hold large binary assets\n> \n> If this improves readability by a lot, I'd be all for it. But this use\n> case is just\n> exemplary. There are also cases of submodules that do not contain big files,\n> but e.g. have a lengthy history with lots of small files.\n> So I don't know, as I would want to keep emphasized that this is just\n> an example.\n> \n\nYou're right I actually screwed up by emphasizing that was the only use\ncase it was envisioned for. Fixed it by replacing \"Therefore\" with \" For\nexample, ...\"\n\nThanks,\nKaartic\n\n"},{"id":"336263","messageId":"3d85256e-4f19-b9d6-323a-d683dbfd8cf7@gmail.com","threadId":"47553","inReplyTo":"CAGZ79kYrp_DAaiDzpiWbTSvsfud=JHSO+NX3UaC4osAE3dYmmQ@mail.gmail.com","subject":"Re: [PATCH 3/8] Doc/gitsubmodules: specify how submodules help in reduced size","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-09T16:01:26Z","receivedAt":"2018-01-09T16:01:46Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"On Tuesday 09 January 2018 12:08 AM, Stefan Beller wrote:\n>> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n>> index cb795c6b6..3f73983d5 100644\n>> --- a/Documentation/gitsubmodules.txt\n>> +++ b/Documentation/gitsubmodules.txt\n>> @@ -63,6 +63,9 @@ Submodules can be used for at least two different use cases:\n>> * Transfer size:\n>> In its current form Git requires the whole working tree present. It\n>> does not allow partial trees to be transferred in fetch or clone.\n>> + If you have your project as multiple repositories tied together as\n>> + submodules in a superproject, you can avoid fetching the working\n>> + trees of the repositories you are not interested in.\n> \n> You do not fetch a working tree, but a whole repository?\n> \n\nMaybe I misunderstood submodules when I wrote that example. Could you\nhelp out with a better and precise replacement?\n\nJust putting in some context as to why I did this change, I thought this\nwas the only thing that lacked an example and wanted to make it consistent.\n\n\n-- \nKaartic\n\n"},{"id":"336264","messageId":"b59bd56a-f88b-a65a-263f-2b6d2f57dd99@gmail.com","threadId":"47553","inReplyTo":"CAGZ79kZZf=zSfqFr9EV_Q408mG4cHTEQSOAMC7n_35oKgHJp2A@mail.gmail.com","subject":"Re: [PATCH 4/8] Doc/gitsubmodules: avoid abbreviations","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-09T16:06:38Z","receivedAt":"2018-01-09T16:07:02Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"On Tuesday 09 January 2018 12:15 AM, Stefan Beller wrote:\n>>\n>> - * The command line for those commands that support taking submodule specs.\n> \n> ++ The command line for those commands that support taking submodules\n> as part of their pathspecs[1].\n> ++\n> ++[1] pathspec is an official term according to `man gitglossary`.\n> \n> Maybe?\n> \n\nYeah, I actually did think 'specification' wasn't a the best fit for\nthis (should have mentioned that somewhere) Now, the real term came out :)\n\nJust to be sure, that \"[1] pathspec ...\" part goes to the end of the\ndocument doesn't it?\n\n\n>> - Most commands have a boolean flag '--recurse-submodules' whether to\n>> - recurse into submodules. Examples are `ls-files` or `checkout`.\n>> + * The command line for those commands that support taking submodule\n>> + specifications. Most commands have a boolean flag '--recurse-submodules\n>> + whether to recurse into submodules. Examples are `ls-files` or `checkout`.\n>> Some commands take enums, such as `fetch` and `push`, where you can\n>> specify how submodules are affected.\n>>\n>> --\n>> 2.16.0.rc0.223.g4a4ac8367\n>>\n\n\n"},{"id":"336266","messageId":"f82949ed-5dbd-eab4-d917-8fe675b1c517@gmail.com","threadId":"47553","inReplyTo":"CAGZ79kYPcx39VqWLAxRCQgO16=Yegq6XeCVUmX7shYomF6sz=g@mail.gmail.com","subject":"Re: [PATCH 6/8] Doc/gitsubmodules: improve readability of certain lines","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-09T16:37:21Z","receivedAt":"2018-01-09T16:37:51Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"On Tuesday 09 January 2018 12:19 AM, Stefan Beller wrote:\n> On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam\n> wrote:\n>>\n>> - * The command line for those commands that support taking submodule\n>> - specifications. Most commands have a boolean flag '--recurse-submodules\n>> - whether to recurse into submodules. Examples are `ls-files` or `checkout`.\n>> + * The command line arguments of those commands that support taking submodule\n>> + specifications. Most commands have a boolean flag '--recurse-submodules'\n>> + which specify whether they should recurse into submodules. Examples are\n>> + `ls-files` or `checkout`.\n>> Some commands take enums, such as `fetch` and `push`, where you can\n>> specify how submodules are affected.\n>>\n>> @@ -90,8 +91,8 @@ Submodule operations can be configured using the following mechanisms\n>> For example an effect from the submodule's `.gitignore` file\n>> would be observed when you run `git status --ignore-submodules=none` in\n>> the superproject. This collects information from the submodule's working\n>> -directory by running `status` in the submodule, which does pay attention\n>> -to its `.gitignore` file.\n>> +directory by running `status` in the submodule while paying attention\n>> +to the `.gitignore` file of the submodule.\n> \n> Both are grammatically correct and expressive, thanks!\n>\n\nYou're welcome!\n\n\n>> +\n> \n> Extra spurious line?\n>\n\nNo. That's a \"real\" plus in the document that's usually present between\nparagraphs :) I think I now get why Junio suggests people to review\npatches in context (possibly, by applying them) ;)\n\n\n>> The submodule's `$GIT_DIR/config` file would come into play when running\n>> `git push --recurse-submodules=check` in the superproject, as this would\n>> @@ -107,13 +108,13 @@ If the submodule is not yet initialized, then the configuration\n>> inside the submodule does not exist yet, so configuration where to\n>> obtain the submodule from is configured here for example.\n>>\n\nI caught this in the context while replying. \"so configuration where to\nobtain the submodule from is configured here for example.\" doesn't seem\nto read well. Maybe removing configuration from the sentence will make\nit sound better?\n\n\n>> - * the `.gitmodules` file inside the superproject. Additionally to the\n>> - required mapping between submodule's name and path, a project usually\n>> + * The `.gitmodules` file inside the superproject. Additionally, if mapping\n>> + is required between a submodule's name and its path, a project usually\n> \n> This changes meaning, originally it tries to say:\n> \n> * it requires mapping path <-> names.\n\nI get this ...\n\n> * but there can be more.\n> \n\n... but not this. Did the previous version really try to say this?\nAnyways how does this sound?\n\n * The `.gitmodules` file inside the superproject. A project usually\n uses this file to suggest defaults for the upstream collection\n of repositories for the mapping that is required between a\n submodule's name and its path.\n\nI think it conveys the \"it requires mapping path <-> names.\" correctly\nbut doesn't convey the \"but there can be more.\" part. I'm not sure how\nto get that into the sentence, correctly.\n\n"},{"id":"336268","messageId":"64503247-66ad-03cf-26ba-3383337971b5@gmail.com","threadId":"47553","inReplyTo":"CAGZ79kZ-UNCyCzmg=5PQ_p5xbmCp7HUc0=TXNBxwTjZDCnJtBg@mail.gmail.com","subject":"Re: [PATCH 0/8] Doc/submodules: a few updates","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-09T17:06:16Z","receivedAt":"2018-01-09T17:06:36Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"On Tuesday 09 January 2018 12:38 AM, Stefan Beller wrote:\n> On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam\n> wrote:\n> \n> While small patches are really appreciated for code (bisect, automated\n> testing, and\n> the general difficulty to reason about code, as a very small change\n> may affect the whole\n> code base), I am not sure if they benefit in documentation.\n> Documentation is a rather\n> local human readable thing, so by changing one sentence we don't\n> affect the understanding\n> of documentation at a completely unrelated place.\n> \n> Also it helps to read more than just sentence fragments, i.e. I tried\n> looking at the\n> whole paragraph for review. May I suggest to squash them all and\n> resend as one patch?\n> \n\nI wouldn't mind that. I thought it might be easy to find to find the\nparts I changed when the patches are small. So, I sent them without\nsquashing them together. In case you feel it's not worth, let me know so\nI'll squash them in.\n\nBTW, in case I did squash them in, would it be nice to keep the commit\nsubjects of the current patch series as bullet points in the unified\ncommit message?\n\n\n> \n>>\n>> I based these patches on top of 'master'.\n> \n> I am not aware of other submodule patches affecting documentation in master..pu,\n> so this should be easy to merge.\n> \n>>\n>> Apart from the changes, I saw a few things that needed improvement/clarification\n>> but wasn't able to do that myself due to my limited knowledge of submodules. They\n>> are listed below. I'll add in patches for them if they are correctly clarified.\n>>\n>>\n>> 1.\n>>\n>> man gitsubmodules\n>>\n>> · The configuration file $GIT_DIR/config in the superproject. Typical configuration at this place is controlling if a submodule is\n>> recursed into at all via the active flag for example.\n>>\n>> If the submodule is not yet initialized, then the configuration inside the submodule does not exist yet, so configuration where to\n>> obtain the submodule from is configured here for example.\n>>\n>> What's the \"active flag\" mentioned above? Also I find the phrase \"is recursed into at all\"\n>> to be a little slippery. How could it be improved?\n> \n> There are multiple ways to indicate if a submodule is \"active\", i.e. if Git is\n> supposed to pay attentio. Historically we had to set the\n> submodule..url flag in the config, but last year Brandon added\n> submodule.active as well as submodule..active which supersede\n> the .url flag.\n> \n> (See is_submodule_active() in submodule.c to see the definitive answer to\n> \"should Git pay attention?\")\n> https://github.com/git/git/blob/master/submodule.c#L224\n> \n\nThanks for the info!\n\n\n> I wonder if this indicates a lack of documentation when the active\n> flags were introduced.\n> They are found in 'man git config', but maybe we need to spell them\n> out explicitly\n> in the submodule related docs.\n> \n\nPossibly. So, why not in Documentation/gitsubmodules! Here's a replaced\nversion of that paragraph,\n\n * The configuration file `$GIT_DIR/config` in the superproject.\n Typically this file is used to specify whether the submodule\n is recursed into at all via the `active` flag for example. A\n submodule is considered active if `submodule..url` is set\n or if the submodules path is present in `submodule.active` or\n if `submodule..url` is set.\n\n\n>> 2.\n>>\n>> man git submodule\n>>\n>> update\n>> ...\n>>\n>> checkout\n>> ....\n>>\n>> If --force is specified, the submodule will be checked out (using git checkout --force if appropriate), even if the commit\n>> specified in the index of the containing repository already matches the commit checked out in the submodule.\n>>\n>> I'm not sure this is conveying all the information it should be conveying.\n>> It seems to making the user wonder, \"How at all does 'git submodule update --force'\n>> differs from 'git submodule update'?\" also \"using git checkout --force if appropriate\"\n>> seems to be invoking all sorts confusion as \"appropriate\" is superfluous.\n> \n> When \"submodule update\" is invoked with the `--force` flag, that flag is passed\n> on to the 'checkout' operation. If you do not give the --force, then\n> the checkout\n> will also be done without --force.\n> \n\nIf that's the case then shouldn't the \"if appropriate\" part of \"(using\ngit checkout --force if appropriate)\" be dropped? That seems to make it\nclear, at least for me. Or is intended as '--force' will not be passed\nto git checkout all the time?\n\n>>\n>> How could these confusions be clarified?\n> \n> I tried giving an alternative snippet above, not sure how else to tell.\n> \n\n\n\n-- \nKaartic\n\nQuote: \"Be creative. Be adventurous. Be original. And above all else, be\nyoung.\" - Wonder Woman\n\n"},{"id":"336285","messageId":"CAGZ79kZ97-sLS4mP28rLoMqf2z8KU0FZ5=fcogynYQKdxji=ng@mail.gmail.com","threadId":"47553","inReplyTo":"64503247-66ad-03cf-26ba-3383337971b5@gmail.com","subject":"Re: [PATCH 0/8] Doc/submodules: a few updates","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-09T18:50:10Z","receivedAt":"2018-01-09T18:50:20Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Tue, Jan 9, 2018 at 9:06 AM, Kaartic Sivaraam\n wrote:\n> On Tuesday 09 January 2018 12:38 AM, Stefan Beller wrote:\n>> On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam\n>> wrote:\n>>\n>> While small patches are really appreciated for code (bisect, automated\n>> testing, and\n>> the general difficulty to reason about code, as a very small change\n>> may affect the whole\n>> code base), I am not sure if they benefit in documentation.\n>> Documentation is a rather\n>> local human readable thing, so by changing one sentence we don't\n>> affect the understanding\n>> of documentation at a completely unrelated place.\n>>\n>> Also it helps to read more than just sentence fragments, i.e. I tried\n>> looking at the\n>> whole paragraph for review. May I suggest to squash them all and\n>> resend as one patch?\n>>\n>\n> I wouldn't mind that. I thought it might be easy to find to find the\n> parts I changed when the patches are small. So, I sent them without\n> squashing them together. In case you feel it's not worth, let me know so\n> I'll squash them in.\n>\n> BTW, in case I did squash them in, would it be nice to keep the commit\n> subjects of the current patch series as bullet points in the unified\n> commit message?\n\nSure.\n\n>> I wonder if this indicates a lack of documentation when the active\n>> flags were introduced.\n>> They are found in 'man git config', but maybe we need to spell them\n>> out explicitly\n>> in the submodule related docs.\n>>\n>\n> Possibly. So, why not in Documentation/gitsubmodules! Here's a replaced\n> version of that paragraph,\n>\n> * The configuration file `$GIT_DIR/config` in the superproject.\n> Typically this file is used to specify whether the submodule\n> is recursed into at all via the `active` flag for example. A\n> submodule is considered active if `submodule..url` is set\n> or if the submodules path is present in `submodule.active` or\n> if `submodule..url` is set.\n\nI wonder if we'd want to give an example later, and first describe the\nmechanics precisely:\n\n The configuration file `$GIT_DIR/config` in the superproject.\n Git only recurses into active submodules. A submodule is\n considered active (a) if `submodule..active` is set\n or (b) if the submodules path is matches the pathsepc in\n `submodule.active` or (c) if `submodule..url` is set.\n (c) is a historical artefact and will be ignored if the pathspec\n set in (b) excludes the submodule. For example:\n\n [submodule \"foo\"]\n active = false\n url = https://example.org/foo\n [submodule \"bar\"]\n active = true\n url = https://example.org/bar\n [submodule \"baz\"]\n url = https://example.org/baz\n\n In the above config only the submodule bar and baz are active,\n bar due to (a) and baz due to (c). Another example\n\n [submodule \"foo\"]\n active = true\n url = https://example.org/foo\n [submodule \"bar\"]\n url = https://example.org/bar\n [submodule \"baz\"]\n url = https://example.org/baz\n [submodule \"bob\"]\n ignore = true\n [submodule]\n active = b*\n active = (:exclude) baz\n\n In here all submodules except baz (foo, bar, bob) are active.\n 'foo' due to its own active flag and all the others due to the\n submodule active pathspec, which specifies that any submodule\n starting with 'b' except 'baz' are also active, no matter if the .url field\n is present.\n\n>>> 2.\n>>>\n>>> man git submodule\n>>>\n>>> update\n>>> ...\n>>>\n>>> checkout\n>>> ....\n>>>\n>>> If --force is specified, the submodule will be checked out (using git checkout --force if appropriate), even if the commit\n>>> specified in the index of the containing repository already matches the commit checked out in the submodule.\n>>>\n>>> I'm not sure this is conveying all the information it should be conveying.\n>>> It seems to making the user wonder, \"How at all does 'git submodule update --force'\n>>> differs from 'git submodule update'?\" also \"using git checkout --force if appropriate\"\n>>> seems to be invoking all sorts confusion as \"appropriate\" is superfluous.\n>>\n>> When \"submodule update\" is invoked with the `--force` flag, that flag is passed\n>> on to the 'checkout' operation. If you do not give the --force, then\n>> the checkout\n>> will also be done without --force.\n>>\n>\n> If that's the case then shouldn't the \"if appropriate\" part of \"(using\n> git checkout --force if appropriate)\" be dropped? That seems to make it\n> clear, at least for me. Or is intended as '--force' will not be passed\n> to git checkout all the time?\n>\n\nYes, essentially we only pass the force flag when we were given the force flag\n(\"when appropriate\" :) Not sure how to say that otherwise. But dropping sounds\ngood)\n\nStefan\n"},{"id":"336294","messageId":"CAGZ79kZkM1jEg4qcTz9CCkOzUx-PX5BOyeprWOht6_hNfYvkjg@mail.gmail.com","threadId":"47553","inReplyTo":"3d85256e-4f19-b9d6-323a-d683dbfd8cf7@gmail.com","subject":"Re: [PATCH 3/8] Doc/gitsubmodules: specify how submodules help in reduced size","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-09T19:01:56Z","receivedAt":"2018-01-09T19:02:04Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Tue, Jan 9, 2018 at 8:01 AM, Kaartic Sivaraam\n wrote:\n> On Tuesday 09 January 2018 12:08 AM, Stefan Beller wrote:\n>>> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n>>> index cb795c6b6..3f73983d5 100644\n>>> --- a/Documentation/gitsubmodules.txt\n>>> +++ b/Documentation/gitsubmodules.txt\n>>> @@ -63,6 +63,9 @@ Submodules can be used for at least two different use cases:\n>>> * Transfer size:\n>>> In its current form Git requires the whole working tree present. It\n>>> does not allow partial trees to be transferred in fetch or clone.\n>>> + If you have your project as multiple repositories tied together as\n>>> + submodules in a superproject, you can avoid fetching the working\n>>> + trees of the repositories you are not interested in.\n>>\n>> You do not fetch a working tree, but a whole repository?\n>>\n>\n> Maybe I misunderstood submodules when I wrote that example. Could you\n> help out with a better and precise replacement?\n\nIf your project consists of multiple repositories tied together, some submodules\nmay not be of interest for all users, who do not need to fetch such submodule\nrepositories.\n\n> Just putting in some context as to why I did this change, I thought this\n> was the only thing that lacked an example and wanted to make it consistent.\n\nOh, sure I like the example; I was just worried about the wording, as a worktree\nis part of a repository, and the repository is the whole thing. In the\ncurrent situation\nyou can only fetch all-or-nothing, specifically you cannot fetch \"just\nthe worktree\"\n(a shallow clone/fetch is the closest to that, but that still has the\nsame amount of\ninformation the .git dir, than in the working tree)\n"},{"id":"336301","messageId":"CAGZ79kZKMKZGWSvPMPHWJ9SeNQSegeiZ3SvMtK+gEYp1dFxYyA@mail.gmail.com","threadId":"47553","inReplyTo":"b59bd56a-f88b-a65a-263f-2b6d2f57dd99@gmail.com","subject":"Re: [PATCH 4/8] Doc/gitsubmodules: avoid abbreviations","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-09T19:26:44Z","receivedAt":"2018-01-09T19:26:51Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Tue, Jan 9, 2018 at 8:06 AM, Kaartic Sivaraam\n wrote:\n> On Tuesday 09 January 2018 12:15 AM, Stefan Beller wrote:\n>>>\n>>> - * The command line for those commands that support taking submodule specs.\n>>\n>> ++ The command line for those commands that support taking submodules\n>> as part of their pathspecs[1].\n>> ++\n>> ++[1] pathspec is an official term according to `man gitglossary`.\n>>\n>> Maybe?\n>>\n>\n> Yeah, I actually did think 'specification' wasn't a the best fit for\n> this (should have mentioned that somewhere) Now, the real term came out :)\n>\n> Just to be sure, that \"[1] pathspec ...\" part goes to the end of the\n> document doesn't it?\n\nThe [1] part was just to highlight it for the sake of this discussion;\nI would not include it into the man page.\n\nStefan\n"},{"id":"336303","messageId":"e1d93f61-b58e-4155-1431-56e51c69b29d@gmail.com","threadId":"47553","inReplyTo":"CAGZ79kZkM1jEg4qcTz9CCkOzUx-PX5BOyeprWOht6_hNfYvkjg@mail.gmail.com","subject":"Re: [PATCH 3/8] Doc/gitsubmodules: specify how submodules help in reduced size","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-09T19:30:28Z","receivedAt":"2018-01-09T19:30:41Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"On Wednesday 10 January 2018 12:31 AM, Stefan Beller wrote:\n> On Tue, Jan 9, 2018 at 8:01 AM, Kaartic Sivaraam\n> wrote:\n>> On Tuesday 09 January 2018 12:08 AM, Stefan Beller wrote:\n>>>> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n>>>> index cb795c6b6..3f73983d5 100644\n>>>> --- a/Documentation/gitsubmodules.txt\n>>>> +++ b/Documentation/gitsubmodules.txt\n>>>> @@ -63,6 +63,9 @@ Submodules can be used for at least two different use cases:\n>>>> * Transfer size:\n>>>> In its current form Git requires the whole working tree present. It\n>>>> does not allow partial trees to be transferred in fetch or clone.\n>>>> + If you have your project as multiple repositories tied together as\n>>>> + submodules in a superproject, you can avoid fetching the working\n>>>> + trees of the repositories you are not interested in.\n>>>\n>>> You do not fetch a working tree, but a whole repository?\n>>>\n>>\n>> Maybe I misunderstood submodules when I wrote that example. Could you\n>> help out with a better and precise replacement?\n> \n> If your project consists of multiple repositories tied together, some submodules\n> may not be of interest for all users, who do not need to fetch such submodule\n> repositories.\n> \n\nOK, now I get why I couldn't get your point. I actually was thinking of\nthe version of the message I had tweaked for v2 when reading your\nmessage. It doesn't have the confusing meaning. It actually reads,\n\n ...\n If the project you work on consists of multiple repositories tied\n together as submodules in a superproject, you can avoid fetching the\n working trees of the repositories you are not interested in.\n\nSo, my version takes the perspective of the person who gains the\nadvantage of having to clone unnecessary repos. And yours, the\nperspective of the person who gives the consumer of the repo that\nadvantage. Both sound nice to me. But if mine doesn't sound nice to you,\nlet me know so that I could replace it with your version.\n\n\n>> Just putting in some context as to why I did this change, I thought this\n>> was the only thing that lacked an example and wanted to make it consistent.\n> \n> Oh, sure I like the example; I was just worried about the wording, as a worktree\n> is part of a repository, and the repository is the whole thing. In the\n> current situation\n> you can only fetch all-or-nothing, specifically you cannot fetch \"just\n> the worktree\"\n> (a shallow clone/fetch is the closest to that, but that still has the\n> same amount of\n> information the .git dir, than in the working tree)\n> \n\nI get that!\n\n"},{"id":"336305","messageId":"CAGZ79kbQoLCodgR+JGXf_K1kS2Orjzp3W+7ZQBM0gX9je6d3Rg@mail.gmail.com","threadId":"47553","inReplyTo":"f82949ed-5dbd-eab4-d917-8fe675b1c517@gmail.com","subject":"Re: [PATCH 6/8] Doc/gitsubmodules: improve readability of certain lines","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-09T19:31:56Z","receivedAt":"2018-01-09T19:32:02Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":">>> The submodule's `$GIT_DIR/config` file would come into play when running\n>>> `git push --recurse-submodules=check` in the superproject, as this would\n>>> @@ -107,13 +108,13 @@ If the submodule is not yet initialized, then the configuration\n>>> inside the submodule does not exist yet, so configuration where to\n>>> obtain the submodule from is configured here for example.\n>>>\n>\n> I caught this in the context while replying. \"so configuration where to\n> obtain the submodule from is configured here for example.\" doesn't seem\n> to read well. Maybe removing configuration from the sentence will make\n> it sound better?\n>\n>\n>>> - * the `.gitmodules` file inside the superproject. Additionally to the\n>>> - required mapping between submodule's name and path, a project usually\n>>> + * The `.gitmodules` file inside the superproject. Additionally, if mapping\n>>> + is required between a submodule's name and its path, a project usually\n>>\n>> This changes meaning, originally it tries to say:\n>>\n>> * it requires mapping path <-> names.\n>\n> I get this ...\n>\n>> * but there can be more.\n>\n> ... but not this. Did the previous version really try to say this?\n> Anyways how does this sound?\n\nWell that was me being very sloppy trying to say that there might be\nsubmodule..{url, ignored, shallow} settings which just happen to\nbe there.\n\n> * The `.gitmodules` file inside the superproject. A project usually\n> uses this file to suggest defaults for the upstream collection\n> of repositories for the mapping that is required between a\n> submodule's name and its path.\n>\n> I think it conveys the \"it requires mapping path <-> names.\" correctly\n> but doesn't convey the \"but there can be more.\" part. I'm not sure how\n> to get that into the sentence, correctly.\n\nI did not consider that part the important part, hence my sloppiness.\nSorry for the confusion.\n\nMy main point was to say that the mapping is the important part and\nmust be found in the .gitmodules file, otherwise we do not consider\nit a submodule (for whatever \"it\" is, maybe a gitlink at a path=name).\n\nStefan\n"},{"id":"336306","messageId":"0236169c-daa8-c3ed-ab2e-27a7d7d88328@gmail.com","threadId":"47553","inReplyTo":"CAGZ79kZKMKZGWSvPMPHWJ9SeNQSegeiZ3SvMtK+gEYp1dFxYyA@mail.gmail.com","subject":"Re: [PATCH 4/8] Doc/gitsubmodules: avoid abbreviations","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-09T19:32:07Z","receivedAt":"2018-01-09T19:32:18Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"On Wednesday 10 January 2018 12:56 AM, Stefan Beller wrote:\n> On Tue, Jan 9, 2018 at 8:06 AM, Kaartic Sivaraam\n> wrote:\n>> On Tuesday 09 January 2018 12:15 AM, Stefan Beller wrote:\n>>>>\n>>>> - * The command line for those commands that support taking submodule specs.\n>>>\n>>> ++ The command line for those commands that support taking submodules\n>>> as part of their pathspecs[1].\n>>> ++\n>>> ++[1] pathspec is an official term according to `man gitglossary`.\n>>>\n>>> Maybe?\n>>>\n>>\n>> Yeah, I actually did think 'specification' wasn't a the best fit for\n>> this (should have mentioned that somewhere) Now, the real term came out :)\n>>\n>> Just to be sure, that \"[1] pathspec ...\" part goes to the end of the\n>> document doesn't it?\n> \n> The [1] part was just to highlight it for the sake of this discussion;\n> I would not include it into the man page.\n> \n\nThat '++' before it made me think otherwise :)\n\n"},{"id":"336309","messageId":"f2753a3f-3e9c-b653-c29b-3399160c5e22@gmail.com","threadId":"47553","inReplyTo":"CAGZ79kbQoLCodgR+JGXf_K1kS2Orjzp3W+7ZQBM0gX9je6d3Rg@mail.gmail.com","subject":"Re: [PATCH 6/8] Doc/gitsubmodules: improve readability of certain lines","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-09T19:57:35Z","receivedAt":"2018-01-09T19:57:52Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"On Wednesday 10 January 2018 01:01 AM, Stefan Beller wrote:\n>>>> The submodule's `$GIT_DIR/config` file would come into play when running\n>>>> `git push --recurse-submodules=check` in the superproject, as this would\n>>>> @@ -107,13 +108,13 @@ If the submodule is not yet initialized, then the configuration\n>>>> inside the submodule does not exist yet, so configuration where to\n>>>> obtain the submodule from is configured here for example.\n>>>>\n>>\n>> I caught this in the context while replying. \"so configuration where to\n>> obtain the submodule from is configured here for example.\" doesn't seem\n>> to read well. Maybe removing configuration from the sentence will make\n>> it sound better?\n>>\n\nI'm going to make this change.\n\n\n>>\n>>>> - * the `.gitmodules` file inside the superproject. Additionally to the\n>>>> - required mapping between submodule's name and path, a project usually\n>>>> + * The `.gitmodules` file inside the superproject. Additionally, if mapping\n>>>> + is required between a submodule's name and its path, a project usually\n>>>\n>>> This changes meaning, originally it tries to say:\n>>>\n>>> * it requires mapping path <-> names.\n>>\n>> I get this ...\n>>\n>>> * but there can be more.\n>>\n>> ... but not this. Did the previous version really try to say this?\n>> Anyways how does this sound?\n> \n> Well that was me being very sloppy trying to say that there might be\n> submodule..{url, ignored, shallow} settings which just happen to\n> be there.\n> \n>> * The `.gitmodules` file inside the superproject. A project usually\n>> uses this file to suggest defaults for the upstream collection\n>> of repositories for the mapping that is required between a\n>> submodule's name and its path.\n>>\n>> I think it conveys the \"it requires mapping path <-> names.\" correctly\n>> but doesn't convey the \"but there can be more.\" part. I'm not sure how\n>> to get that into the sentence, correctly.\n> \n> I did not consider that part the important part, hence my sloppiness.\n> Sorry for the confusion.\n> \n> My main point was to say that the mapping is the important part and\n> must be found in the .gitmodules file, otherwise we do not consider\n> it a submodule (for whatever \"it\" is, maybe a gitlink at a path=name).\n> \n\nSo, I'm going to use the version that I specified above as I think it\nseems to convey that clearly (at least to me),\n\n The `.gitmodules` file inside the superproject. A project usually\n uses this file to suggest defaults for the upstream collection\n of repositories for the mapping that is required between a\n submodule's name and its path.\n\nLet me know, if there are issues.\n\nThanks,\nKaartic\n\n"},{"id":"336337","messageId":"20180110064959.5491-1-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180106184614.20115-1-kaartic.sivaraam@gmail.com","subject":"[PATCH v2 0/2] Doc/submodules: a few updates","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-10T06:49:57Z","receivedAt":"2018-01-10T06:50:36Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Quoting from v1,\n\n These are just a few improvements that I thought would make the documentation\n related to submodules a little better in various way such as readability,\n consistency etc., These were things I noticed while reading thise documents.\n\nChange since v2: \n\n I've squashed the fine grained patches into 2 patches that touch two distinct\n documents. This v2 conatins a lot of changes suggested for v1 and few that I\n caught by myself since v1.\n\nThis patch is based on 'master' just like v1.\n\nInter-word-diff v1..v2:\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 5c4d941cc..801d291ca 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -140,7 +140,7 @@ through the `submodule..update` configuration are:\n\t checked out in the submodule on a detached HEAD.\n+\nIf `--force` is specified, the submodule will be checked out (using\n`git checkout [---force` if appropriate),-]{+--force`),+} even if the commit specified\nin the index of the containing repository already matches the commit\nchecked out in the submodule.\n\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex 339fb73db..ce2369c2d 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -36,7 +36,7 @@ The `gitlink` entry contains the object name of the commit that the\nsuperproject expects the submodule’s working directory to be at.\n\nThe section `submodule.foo.*` in the `.gitmodules` file gives additional\nhints to [-Gits-]{+Git's+} porcelain layer. For example, the `submodule.foo.url`\nsetting specifies where to obtain the submodule.\n\nSubmodules can be used for at least two different use cases:\n@@ -51,21 +51,21 @@ Submodules can be used for at least two different use cases:\n\n2. Splitting a (logically single) project into multiple\n repositories and tying them back together. This can be used to\n overcome current limitations of [-Gits-]{+Git's+} implementation to have\n finer grained access:\n\n * Size of the [-git-]{+Git+} repository:\n In its current form Git scales up poorly for large repositories containing\n content that is not compressed by delta computation between trees.\n [-Therefore-]{+For example,+} you can use submodules to hold large binary assets\n and these repositories [-are then-]{+can be+} shallowly cloned such that you do not\n have a large history locally.\n * Transfer size:\n In its current form Git requires the whole working tree present. It\n does not allow partial trees to be transferred in fetch or clone.\n If [-you have your-]{+the+} project [-as-]{+you work on consists of+} multiple repositories tied\n together as submodules in a superproject, you can avoid fetching the\n working trees of the repositories you are not interested in.\n * Access control:\n By restricting user access to submodules, this can be used to implement\n read/write policies for different users.\n@@ -76,10 +76,10 @@ The configuration of submodules\nSubmodule operations can be configured using the following mechanisms\n(from highest to lowest precedence):\n\n * The command line [-arguments of-]{+for+} those commands that support taking [-submodule-]\n[- specifications.-]{+submodules+}\n{+ as part of their pathspecs.+} Most commands have a boolean flag\n [-'--recurse-submodules'-]{+`--recurse-submodules`+} which specify whether [-they should-]{+to+} recurse into submodules.\n Examples are [-`ls-files` or-]{+`grep` and+} `checkout`.\n Some commands take enums, such as `fetch` and `push`, where you can\n specify how submodules are affected.\n\n@@ -101,17 +101,17 @@ remotes are configured in the submodule as usual in the `$GIT_DIR/config`\nfile.\n\n * The configuration file `$GIT_DIR/config` in the superproject.\n [-Typical configuration at this place is controlling if a submodule-]\n[- is recursed-]{+Git only recurses+} into [-at all via the `active` flag for example.-]{+active submodules (see 'ACTIVE SUBMODULES'+}\n{+ section below).+}\n+\nIf the submodule is not yet initialized, then the configuration\ninside the submodule does not exist yet, so[-configuration-] where to\nobtain the submodule from is configured here for example.\n\n * The `.gitmodules` file inside the superproject. [-Additionally, if mapping-]\n[- is required between a submodule's name and its path, a-]{+A+} project usually\n uses this file to suggest defaults for the upstream collection\n of [-repositories.-]{+repositories for the mapping that is required between a+}\n{+ submodule's name and its path.+}\n+\nThis file mainly serves as the mapping between the name and path of submodules\nin the superproject, such that the submodule's Git directory can be\n@@ -141,8 +141,8 @@ directory is automatically moved to `$GIT_DIR/modules//`\nof the superproject.\n\n * Deinitialized submodule: A `gitlink`, and a `.gitmodules` entry,\nbut no submodule working directory. The submodule’s [-git-]{+Git+} directory\nmay be there as after deinitializing the [-git-]{+Git+} directory is kept around.\nThe directory which is supposed to be the working directory is empty instead.\n+\nA submodule can be deinitialized by running `git submodule deinit`.\n@@ -164,6 +164,53 @@ from another repository.\nTo completely remove a submodule, manually delete\n`$GIT_DIR/modules//`.\n\n{+Active submodules+}\n{+-----------------+}\n\n{+A submodule is considered active,+}\n\n{+ (a) if `submodule..active` is set+}\n{+ or+}\n{+ (b) if the submodules path matches the pathspec in `submodule.active`+}\n{+ or+}\n{+ (c) if `submodule..url` is set.+}\n\n{+For example:+}\n\n{+ [submodule \"foo\"]+}\n{+ active = false+}\n{+ url = https://example.org/foo+}\n{+ [submodule \"bar\"]+}\n{+ active = true+}\n{+ url = https://example.org/bar+}\n{+ [submodule \"baz\"]+}\n{+ url = https://example.org/baz+}\n\n{+In the above config only the submodule bar and baz are active,+}\n{+bar due to (a) and baz due to (c).+}\n\n{+Note that '(c)' is a historical artefact and will be ignored if the+}\n{+pathspec set in (b) excludes the submodule. For example:+}\n\n{+ [submodule \"foo\"]+}\n{+ active = true+}\n{+ url = https://example.org/foo+}\n{+ [submodule \"bar\"]+}\n{+ url = https://example.org/bar+}\n{+ [submodule \"baz\"]+}\n{+ url = https://example.org/baz+}\n{+ [submodule \"bob\"]+}\n{+ ignore = true+}\n{+ [submodule]+}\n{+ active = b*+}\n{+ active = (:exclude) baz+}\n\n{+In here all submodules except baz (foo, bar, bob) are active.+}\n{+'foo' due to its own active flag and all the others due to the+}\n{+submodule active pathspec, which specifies that any submodule+}\n{+starting with 'b' except 'baz' are also active, no matter if+}\n{+the .url field is present.+}\n\nWorkflow for a third party library\n----------------------------------\n\n\n\nKaartic Sivaraam (2):\n Doc/gitsubmodules: make some changes to improve readability and syntax\n Doc/git-submodule: improve readability and grammar of a sentence\n\n Documentation/git-submodule.txt | 12 +++---\n Documentation/gitsubmodules.txt | 93 +++++++++++++++++++++++++++++++----------\n 2 files changed, 78 insertions(+), 27 deletions(-)\n\n-- \n2.16.0.rc0.223.g4a4ac8367\n\n"},{"id":"336338","messageId":"20180110064959.5491-2-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180110064959.5491-1-kaartic.sivaraam@gmail.com","subject":"[PATCH v2 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-10T06:49:58Z","receivedAt":"2018-01-10T06:50:39Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"* Only mention porcelain commands in examples\n\n* Split a sentence for better readability\n\n* Add missing apostrophes\n\n* Clearly specify the advantages of using submodules\n\n* Avoid abbreviations\n\n* Use \"Git\" consistently\n\n* Improve readability of certain lines\n\n* Clarify when a submodule is considered active\n\nHelped-by: Eric Sunshine \nHelped-by: Stefan Beller \nSigned-off-by: Kaartic Sivaraam \n---\n Documentation/gitsubmodules.txt | 93 +++++++++++++++++++++++++++++++----------\n 1 file changed, 72 insertions(+), 21 deletions(-)\n\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex 46cf120f6..ce2369c2d 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -36,8 +36,8 @@ The `gitlink` entry contains the object name of the commit that the\n superproject expects the submodule’s working directory to be at.\n \n The section `submodule.foo.*` in the `.gitmodules` file gives additional\n-hints to Gits porcelain layer such as where to obtain the submodule via\n-the `submodule.foo.url` setting.\n+hints to Git's porcelain layer. For example, the `submodule.foo.url`\n+setting specifies where to obtain the submodule.\n \n Submodules can be used for at least two different use cases:\n \n@@ -51,18 +51,21 @@ Submodules can be used for at least two different use cases:\n \n 2. Splitting a (logically single) project into multiple\n repositories and tying them back together. This can be used to\n- overcome current limitations of Gits implementation to have\n+ overcome current limitations of Git's implementation to have\n finer grained access:\n \n- * Size of the git repository:\n+ * Size of the Git repository:\n In its current form Git scales up poorly for large repositories containing\n content that is not compressed by delta computation between trees.\n- However you can also use submodules to e.g. hold large binary assets\n- and these repositories are then shallowly cloned such that you do not\n+ For example, you can use submodules to hold large binary assets\n+ and these repositories can be shallowly cloned such that you do not\n have a large history locally.\n * Transfer size:\n In its current form Git requires the whole working tree present. It\n does not allow partial trees to be transferred in fetch or clone.\n+ If the project you work on consists of multiple repositories tied\n+ together as submodules in a superproject, you can avoid fetching the\n+ working trees of the repositories you are not interested in.\n * Access control:\n By restricting user access to submodules, this can be used to implement\n read/write policies for different users.\n@@ -73,9 +76,10 @@ The configuration of submodules\n Submodule operations can be configured using the following mechanisms\n (from highest to lowest precedence):\n \n- * The command line for those commands that support taking submodule specs.\n- Most commands have a boolean flag '--recurse-submodules' whether to\n- recurse into submodules. Examples are `ls-files` or `checkout`.\n+ * The command line for those commands that support taking submodules\n+ as part of their pathspecs. Most commands have a boolean flag\n+ `--recurse-submodules` which specify whether to recurse into submodules.\n+ Examples are `grep` and `checkout`.\n Some commands take enums, such as `fetch` and `push`, where you can\n specify how submodules are affected.\n \n@@ -87,8 +91,8 @@ Submodule operations can be configured using the following mechanisms\n For example an effect from the submodule's `.gitignore` file\n would be observed when you run `git status --ignore-submodules=none` in\n the superproject. This collects information from the submodule's working\n-directory by running `status` in the submodule, which does pay attention\n-to its `.gitignore` file.\n+directory by running `status` in the submodule while paying attention\n+to the `.gitignore` file of the submodule.\n +\n The submodule's `$GIT_DIR/config` file would come into play when running\n `git push --recurse-submodules=check` in the superproject, as this would\n@@ -97,20 +101,20 @@ remotes are configured in the submodule as usual in the `$GIT_DIR/config`\n file.\n \n * The configuration file `$GIT_DIR/config` in the superproject.\n- Typical configuration at this place is controlling if a submodule\n- is recursed into at all via the `active` flag for example.\n+ Git only recurses into active submodules (see 'ACTIVE SUBMODULES'\n+ section below).\n +\n If the submodule is not yet initialized, then the configuration\n-inside the submodule does not exist yet, so configuration where to\n+inside the submodule does not exist yet, so where to\n obtain the submodule from is configured here for example.\n \n- * the `.gitmodules` file inside the superproject. Additionally to the\n- required mapping between submodule's name and path, a project usually\n+ * The `.gitmodules` file inside the superproject. A project usually\n uses this file to suggest defaults for the upstream collection\n- of repositories.\n+ of repositories for the mapping that is required between a\n+ submodule's name and its path.\n +\n-This file mainly serves as the mapping between name and path in\n-the superproject, such that the submodule's git directory can be\n+This file mainly serves as the mapping between the name and path of submodules\n+in the superproject, such that the submodule's Git directory can be\n located.\n +\n If the submodule has never been initialized, this is the only place\n@@ -137,8 +141,8 @@ directory is automatically moved to `$GIT_DIR/modules//`\n of the superproject.\n \n * Deinitialized submodule: A `gitlink`, and a `.gitmodules` entry,\n-but no submodule working directory. The submodule’s git directory\n-may be there as after deinitializing the git directory is kept around.\n+but no submodule working directory. The submodule’s Git directory\n+may be there as after deinitializing the Git directory is kept around.\n The directory which is supposed to be the working directory is empty instead.\n +\n A submodule can be deinitialized by running `git submodule deinit`.\n@@ -160,6 +164,53 @@ from another repository.\n To completely remove a submodule, manually delete\n `$GIT_DIR/modules//`.\n \n+Active submodules\n+-----------------\n+\n+A submodule is considered active,\n+\n+ (a) if `submodule..active` is set\n+ or\n+ (b) if the submodules path matches the pathspec in `submodule.active`\n+ or\n+ (c) if `submodule..url` is set.\n+\n+For example:\n+\n+ [submodule \"foo\"]\n+ active = false\n+ url = https://example.org/foo\n+ [submodule \"bar\"]\n+ active = true\n+ url = https://example.org/bar\n+ [submodule \"baz\"]\n+ url = https://example.org/baz\n+\n+In the above config only the submodule bar and baz are active,\n+bar due to (a) and baz due to (c).\n+\n+Note that '(c)' is a historical artefact and will be ignored if the\n+pathspec set in (b) excludes the submodule. For example:\n+\n+ [submodule \"foo\"]\n+ active = true\n+ url = https://example.org/foo\n+ [submodule \"bar\"]\n+ url = https://example.org/bar\n+ [submodule \"baz\"]\n+ url = https://example.org/baz\n+ [submodule \"bob\"]\n+ ignore = true\n+ [submodule]\n+ active = b*\n+ active = (:exclude) baz\n+\n+In here all submodules except baz (foo, bar, bob) are active.\n+'foo' due to its own active flag and all the others due to the\n+submodule active pathspec, which specifies that any submodule\n+starting with 'b' except 'baz' are also active, no matter if\n+the .url field is present.\n+\n Workflow for a third party library\n ----------------------------------\n \n-- \n2.16.0.rc0.223.g4a4ac8367\n\n"},{"id":"336339","messageId":"20180110064959.5491-3-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180110064959.5491-1-kaartic.sivaraam@gmail.com","subject":"[PATCH v2 2/2] Doc/git-submodule: improve readability and grammar of a sentence","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-10T06:49:59Z","receivedAt":"2018-01-10T06:50:41Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"While at it, correctly quote important words.\n\nSigned-off-by: Kaartic Sivaraam \n---\n Documentation/git-submodule.txt | 12 ++++++------\n 1 file changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex ff612001d..801d291ca 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -132,15 +132,15 @@ expects by cloning missing submodules and updating the working tree of\n the submodules. The \"updating\" can be done in several ways depending\n on command line options and the value of `submodule..update`\n configuration variable. The command line option takes precedence over\n-the configuration variable. if neither is given, a checkout is performed.\n-update procedures supported both from the command line as well as setting\n-`submodule..update`:\n+the configuration variable. If neither is given, a 'checkout' is performed.\n+The 'update' procedures supported both from the command line as well as\n+through the `submodule..update` configuration are:\n \n \tcheckout;; the commit recorded in the superproject will be\n \t checked out in the submodule on a detached HEAD.\n +\n If `--force` is specified, the submodule will be checked out (using\n-`git checkout --force` if appropriate), even if the commit specified\n+`git checkout --force`), even if the commit specified\n in the index of the containing repository already matches the commit\n checked out in the submodule.\n \n@@ -150,8 +150,8 @@ checked out in the submodule.\n \tmerge;; the commit recorded in the superproject will be merged\n \t into the current branch in the submodule.\n \n-The following procedures are only available via the `submodule..update`\n-configuration variable:\n+The following 'update' procedures are only available via the\n+`submodule..update` configuration variable:\n \n \tcustom command;; arbitrary shell command that takes a single\n \t argument (the sha1 of the commit recorded in the\n-- \n2.16.0.rc0.223.g4a4ac8367\n\n"},{"id":"336422","messageId":"CAGZ79kaEw7m=5c65-7n3kX7-zfPzHMeOXF0r-7D-RjsAEhg3Pw@mail.gmail.com","threadId":"47553","inReplyTo":"20180110064959.5491-2-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH v2 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-10T20:49:12Z","receivedAt":"2018-01-10T20:49:22Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Tue, Jan 9, 2018 at 10:49 PM, Kaartic Sivaraam\n wrote:\n> * Only mention porcelain commands in examples\n>\n> * Split a sentence for better readability\n>\n> * Add missing apostrophes\n>\n> * Clearly specify the advantages of using submodules\n>\n> * Avoid abbreviations\n>\n> * Use \"Git\" consistently\n>\n> * Improve readability of certain lines\n>\n> * Clarify when a submodule is considered active\n>\n> Helped-by: Eric Sunshine \n> Helped-by: Stefan Beller \n> Signed-off-by: Kaartic Sivaraam \n> ---\n\nThanks for sending it in one patch,\nStefan\n\n> Documentation/gitsubmodules.txt | 93 +++++++++++++++++++++++++++++++----------\n> 1 file changed, 72 insertions(+), 21 deletions(-)\n>\n> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n> index 46cf120f6..ce2369c2d 100644\n> --- a/Documentation/gitsubmodules.txt\n> +++ b/Documentation/gitsubmodules.txt\n> @@ -36,8 +36,8 @@ The `gitlink` entry contains the object name of the commit that the\n> superproject expects the submodule’s working directory to be at.\n>\n> The section `submodule.foo.*` in the `.gitmodules` file gives additional\n> -hints to Gits porcelain layer such as where to obtain the submodule via\n> -the `submodule.foo.url` setting.\n> +hints to Git's porcelain layer. For example, the `submodule.foo.url`\n> +setting specifies where to obtain the submodule.\n>\n> Submodules can be used for at least two different use cases:\n>\n> @@ -51,18 +51,21 @@ Submodules can be used for at least two different use cases:\n>\n> 2. Splitting a (logically single) project into multiple\n> repositories and tying them back together. This can be used to\n> - overcome current limitations of Gits implementation to have\n> + overcome current limitations of Git's implementation to have\n> finer grained access:\n>\n> - * Size of the git repository:\n> + * Size of the Git repository:\n> In its current form Git scales up poorly for large repositories containing\n> content that is not compressed by delta computation between trees.\n> - However you can also use submodules to e.g. hold large binary assets\n> - and these repositories are then shallowly cloned such that you do not\n> + For example, you can use submodules to hold large binary assets\n> + and these repositories can be shallowly cloned such that you do not\n> have a large history locally.\n> * Transfer size:\n> In its current form Git requires the whole working tree present. It\n> does not allow partial trees to be transferred in fetch or clone.\n> + If the project you work on consists of multiple repositories tied\n> + together as submodules in a superproject, you can avoid fetching the\n> + working trees of the repositories you are not interested in.\n> * Access control:\n> By restricting user access to submodules, this can be used to implement\n> read/write policies for different users.\n> @@ -73,9 +76,10 @@ The configuration of submodules\n> Submodule operations can be configured using the following mechanisms\n> (from highest to lowest precedence):\n>\n> - * The command line for those commands that support taking submodule specs.\n> - Most commands have a boolean flag '--recurse-submodules' whether to\n> - recurse into submodules. Examples are `ls-files` or `checkout`.\n> + * The command line for those commands that support taking submodules\n> + as part of their pathspecs. Most commands have a boolean flag\n> + `--recurse-submodules` which specify whether to recurse into submodules.\n> + Examples are `grep` and `checkout`.\n> Some commands take enums, such as `fetch` and `push`, where you can\n> specify how submodules are affected.\n>\n> @@ -87,8 +91,8 @@ Submodule operations can be configured using the following mechanisms\n> For example an effect from the submodule's `.gitignore` file\n> would be observed when you run `git status --ignore-submodules=none` in\n> the superproject. This collects information from the submodule's working\n> -directory by running `status` in the submodule, which does pay attention\n> -to its `.gitignore` file.\n> +directory by running `status` in the submodule while paying attention\n> +to the `.gitignore` file of the submodule.\n> +\n> The submodule's `$GIT_DIR/config` file would come into play when running\n> `git push --recurse-submodules=check` in the superproject, as this would\n> @@ -97,20 +101,20 @@ remotes are configured in the submodule as usual in the `$GIT_DIR/config`\n> file.\n>\n> * The configuration file `$GIT_DIR/config` in the superproject.\n> - Typical configuration at this place is controlling if a submodule\n> - is recursed into at all via the `active` flag for example.\n> + Git only recurses into active submodules (see 'ACTIVE SUBMODULES'\n> + section below).\n\nThe section below is capitalized differently?\n\n\n> +\n> If the submodule is not yet initialized, then the configuration\n> -inside the submodule does not exist yet, so configuration where to\n> +inside the submodule does not exist yet, so where to\n> obtain the submodule from is configured here for example.\n>\n> - * the `.gitmodules` file inside the superproject. Additionally to the\n> - required mapping between submodule's name and path, a project usually\n> + * The `.gitmodules` file inside the superproject. A project usually\n> uses this file to suggest defaults for the upstream collection\n> - of repositories.\n> + of repositories for the mapping that is required between a\n> + submodule's name and its path.\n> +\n> -This file mainly serves as the mapping between name and path in\n> -the superproject, such that the submodule's git directory can be\n> +This file mainly serves as the mapping between the name and path of submodules\n> +in the superproject, such that the submodule's Git directory can be\n> located.\n> +\n> If the submodule has never been initialized, this is the only place\n> @@ -137,8 +141,8 @@ directory is automatically moved to `$GIT_DIR/modules//`\n> of the superproject.\n>\n> * Deinitialized submodule: A `gitlink`, and a `.gitmodules` entry,\n> -but no submodule working directory. The submodule’s git directory\n> -may be there as after deinitializing the git directory is kept around.\n> +but no submodule working directory. The submodule’s Git directory\n> +may be there as after deinitializing the Git directory is kept around.\n> The directory which is supposed to be the working directory is empty instead.\n> +\n> A submodule can be deinitialized by running `git submodule deinit`.\n> @@ -160,6 +164,53 @@ from another repository.\n> To completely remove a submodule, manually delete\n> `$GIT_DIR/modules//`.\n\n\n> +Active submodules\n\nThe examples were not meant to be taken literally into the patch. ;)\n(I should have been more careful for that :P)\n\n> +-----------------\n> +\n> +A submodule is considered active,\n> +\n> + (a) if `submodule..active` is set\n> + or\n> + (b) if the submodules path matches the pathspec in `submodule.active`\n> + or\n> + (c) if `submodule..url` is set.\n\nand these are evaluated in this order, so if (a) or (b) is set but\nindicates that the submodule is not active, we're done evaluating.\nas seen by the example, if we have an .active = false set, the url\ndoesn't matter whether it is present or not.\n\n> +\n> +For example:\n> +\n> + [submodule \"foo\"]\n> + active = false\n> + url = https://example.org/foo\n> + [submodule \"bar\"]\n> + active = true\n> + url = https://example.org/bar\n> + [submodule \"baz\"]\n> + url = https://example.org/baz\n> +\n> +In the above config only the submodule bar and baz are active,\n> +bar due to (a) and baz due to (c).\n\n\"foo\" is inactive because (a) takes precedence over (c).\n\n> +\n> +Note that '(c)' is a historical artefact and will be ignored if the\n> +pathspec set in (b) excludes the submodule. For example:\n> +\n> + [submodule \"foo\"]\n> + active = true\n> + url = https://example.org/foo\n> + [submodule \"bar\"]\n> + url = https://example.org/bar\n> + [submodule \"baz\"]\n> + url = https://example.org/baz\n> + [submodule \"bob\"]\n> + ignore = true\n> + [submodule]\n> + active = b*\n> + active = (:exclude) baz\n\n :(exclude)baz\n\nThis is regular pathspec magic, see 'pathspec' in 'man gitglossary'\n\n> +In here all submodules except baz (foo, bar, bob) are active.\n> +'foo' due to its own active flag and all the others due to the\n> +submodule active pathspec, which specifies that any submodule\n> +starting with 'b' except 'baz' are also active, no matter if\n> +the .url field is present.\n> +\n> Workflow for a third party library\n> ----------------------------------\n>\n> --\n> 2.16.0.rc0.223.g4a4ac8367\n>\n"},{"id":"336591","messageId":"20180114173737.13012-1-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180110064959.5491-1-kaartic.sivaraam@gmail.com","subject":"[PATCH v3 0/2] Doc/submodules: a few updates","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-14T17:37:35Z","receivedAt":"2018-01-14T17:38:17Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Quoting from v1,\n\n These are just a few improvements that I thought would make the documentation\n related to submodules a little better in various way such as readability,\n consistency etc., These were things I noticed while reading thise documents.\n\nChanges since v2:\n\n - Made some changes suggested by Stefan.\n - A few more that caught my eyes.\n\nInter diff between v2 and v3:\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 801d291ca..71c5618e8 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -70,8 +70,8 @@ status [--cached] [--recursive] [--] [...]::\n \tShow the status of the submodules. This will print the SHA-1 of the\n \tcurrently checked out commit for each submodule, along with the\n \tsubmodule path and the output of 'git describe' for the\n-\tSHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not\n-\tinitialized, `+` if the currently checked out submodule commit\n+\tSHA-1. Each SHA-1 will possibly be prefixed with `-` if the submodule is\n+\tnot initialized, `+` if the currently checked out submodule commit\n \tdoes not match the SHA-1 found in the index of the containing\n \trepository and `U` if the submodule has merge conflicts.\n +\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex ce2369c2d..47bbc62e8 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -101,7 +101,7 @@ remotes are configured in the submodule as usual in the `$GIT_DIR/config`\n file.\n \n * The configuration file `$GIT_DIR/config` in the superproject.\n- Git only recurses into active submodules (see 'ACTIVE SUBMODULES'\n+ Git only recurses into active submodules (see \"ACTIVE SUBMODULES\"\n section below).\n +\n If the submodule is not yet initialized, then the configuration\n@@ -164,52 +164,59 @@ from another repository.\n To completely remove a submodule, manually delete\n `$GIT_DIR/modules//`.\n \n-Active submodules\n+ACTIVE SUBMODULES\n -----------------\n \n A submodule is considered active,\n \n- (a) if `submodule..active` is set\n+ (a) if `submodule..active` is set to `true`\n or\n- (b) if the submodules path matches the pathspec in `submodule.active`\n+ (b) if the submodule's path matches the pathspec in `submodule.active`\n or\n (c) if `submodule..url` is set.\n \n+and these are evaluated in this order.\n+\n For example:\n \n- [submodule \"foo\"]\n- active = false\n- url = https://example.org/foo\n- [submodule \"bar\"]\n- active = true\n- url = https://example.org/bar\n- [submodule \"baz\"]\n- url = https://example.org/baz\n+ [submodule \"foo\"]\n+ active = false\n+ url = https://example.org/foo\n+ [submodule \"bar\"]\n+ active = true\n+ url = https://example.org/bar\n+ [submodule \"baz\"]\n+ url = https://example.org/baz\n \n-In the above config only the submodule bar and baz are active,\n-bar due to (a) and baz due to (c).\n+In the above config only the submodule 'bar' and 'baz' are active,\n+'bar' due to (a) and 'baz' due to (c). 'foo' is inactive because\n+(a) takes precedence over (c).\n \n-Note that '(c)' is a historical artefact and will be ignored if the\n-pathspec set in (b) excludes the submodule. For example:\n+Note that (c) is a historical artefact and will be ignored if the\n+(a) and (b) specify that the submodule is not active. In other words,\n+if we have an `submodule..active` set to `false` or if the\n+submodule's path is excluded in the pathspec in `submodule.active`, the\n+url doesn't matter whether it is present or not. This is illustrated in\n+the example that follows.\n \n- [submodule \"foo\"]\n- active = true\n- url = https://example.org/foo\n- [submodule \"bar\"]\n- url = https://example.org/bar\n- [submodule \"baz\"]\n- url = https://example.org/baz\n- [submodule \"bob\"]\n- ignore = true\n- [submodule]\n- active = b*\n- active = (:exclude) baz\n+ [submodule \"foo\"]\n+ active = true\n+ url = https://example.org/foo\n+ [submodule \"bar\"]\n+ url = https://example.org/bar\n+ [submodule \"baz\"]\n+ url = https://example.org/baz\n+ [submodule \"bob\"]\n+ ignore = true\n+ [submodule]\n+ active = b*\n+ active = :(exclude) baz\n \n-In here all submodules except baz (foo, bar, bob) are active.\n+In here all submodules except 'baz' (foo, bar, bob) are active.\n 'foo' due to its own active flag and all the others due to the\n submodule active pathspec, which specifies that any submodule\n-starting with 'b' except 'baz' are also active, no matter if\n-the .url field is present.\n+starting with 'b' except 'baz' are also active, regardless of the\n+presence of the .url field.\n \n Workflow for a third party library\n ----------------------------------\n\n\n\nKaartic Sivaraam (2):\n Doc/gitsubmodules: make some changes to improve readability and syntax\n Doc/git-submodule: improve readability and grammar of a sentence\n\n Documentation/git-submodule.txt | 16 +++----\n Documentation/gitsubmodules.txt | 100 +++++++++++++++++++++++++++++++---------\n 2 files changed, 87 insertions(+), 29 deletions(-)\n\n-- \n2.16.0.rc1.281.g969645f98\n\n"},{"id":"336592","messageId":"20180114173737.13012-2-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180114173737.13012-1-kaartic.sivaraam@gmail.com","subject":"[PATCH v3 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-14T17:37:36Z","receivedAt":"2018-01-14T17:38:22Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"* Only mention porcelain commands in examples\n\n* Split a sentence for better readability\n\n* Add missing apostrophes\n\n* Clearly specify the advantages of using submodules\n\n* Avoid abbreviations\n\n* Use \"Git\" consistently\n\n* Improve readability of certain lines\n\n* Clarify when a submodule is considered active\n\nHelped-by: Eric Sunshine \nHelped-by: Stefan Beller \nSigned-off-by: Kaartic Sivaraam \n---\n Documentation/gitsubmodules.txt | 100 +++++++++++++++++++++++++++++++---------\n 1 file changed, 79 insertions(+), 21 deletions(-)\n\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex 46cf120f6..4d6c17782 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -36,8 +36,8 @@ The `gitlink` entry contains the object name of the commit that the\n superproject expects the submodule’s working directory to be at.\n \n The section `submodule.foo.*` in the `.gitmodules` file gives additional\n-hints to Gits porcelain layer such as where to obtain the submodule via\n-the `submodule.foo.url` setting.\n+hints to Git's porcelain layer. For example, the `submodule.foo.url`\n+setting specifies where to obtain the submodule.\n \n Submodules can be used for at least two different use cases:\n \n@@ -51,18 +51,21 @@ Submodules can be used for at least two different use cases:\n \n 2. Splitting a (logically single) project into multiple\n repositories and tying them back together. This can be used to\n- overcome current limitations of Gits implementation to have\n+ overcome current limitations of Git's implementation to have\n finer grained access:\n \n- * Size of the git repository:\n+ * Size of the Git repository:\n In its current form Git scales up poorly for large repositories containing\n content that is not compressed by delta computation between trees.\n- However you can also use submodules to e.g. hold large binary assets\n- and these repositories are then shallowly cloned such that you do not\n+ For example, you can use submodules to hold large binary assets\n+ and these repositories can be shallowly cloned such that you do not\n have a large history locally.\n * Transfer size:\n In its current form Git requires the whole working tree present. It\n does not allow partial trees to be transferred in fetch or clone.\n+ If the project you work on consists of multiple repositories tied\n+ together as submodules in a superproject, you can avoid fetching the\n+ working trees of the repositories you are not interested in.\n * Access control:\n By restricting user access to submodules, this can be used to implement\n read/write policies for different users.\n@@ -73,9 +76,10 @@ The configuration of submodules\n Submodule operations can be configured using the following mechanisms\n (from highest to lowest precedence):\n \n- * The command line for those commands that support taking submodule specs.\n- Most commands have a boolean flag '--recurse-submodules' whether to\n- recurse into submodules. Examples are `ls-files` or `checkout`.\n+ * The command line for those commands that support taking submodules\n+ as part of their pathspecs. Most commands have a boolean flag\n+ `--recurse-submodules` which specify whether to recurse into submodules.\n+ Examples are `grep` and `checkout`.\n Some commands take enums, such as `fetch` and `push`, where you can\n specify how submodules are affected.\n \n@@ -87,8 +91,8 @@ Submodule operations can be configured using the following mechanisms\n For example an effect from the submodule's `.gitignore` file\n would be observed when you run `git status --ignore-submodules=none` in\n the superproject. This collects information from the submodule's working\n-directory by running `status` in the submodule, which does pay attention\n-to its `.gitignore` file.\n+directory by running `status` in the submodule while paying attention\n+to the `.gitignore` file of the submodule.\n +\n The submodule's `$GIT_DIR/config` file would come into play when running\n `git push --recurse-submodules=check` in the superproject, as this would\n@@ -97,20 +101,20 @@ remotes are configured in the submodule as usual in the `$GIT_DIR/config`\n file.\n \n * The configuration file `$GIT_DIR/config` in the superproject.\n- Typical configuration at this place is controlling if a submodule\n- is recursed into at all via the `active` flag for example.\n+ Git only recurses into active submodules (see \"ACTIVE SUBMODULES\"\n+ section below).\n +\n If the submodule is not yet initialized, then the configuration\n-inside the submodule does not exist yet, so configuration where to\n+inside the submodule does not exist yet, so where to\n obtain the submodule from is configured here for example.\n \n- * the `.gitmodules` file inside the superproject. Additionally to the\n- required mapping between submodule's name and path, a project usually\n+ * The `.gitmodules` file inside the superproject. A project usually\n uses this file to suggest defaults for the upstream collection\n- of repositories.\n+ of repositories for the mapping that is required between a\n+ submodule's name and its path.\n +\n-This file mainly serves as the mapping between name and path in\n-the superproject, such that the submodule's git directory can be\n+This file mainly serves as the mapping between the name and path of submodules\n+in the superproject, such that the submodule's Git directory can be\n located.\n +\n If the submodule has never been initialized, this is the only place\n@@ -137,8 +141,8 @@ directory is automatically moved to `$GIT_DIR/modules//`\n of the superproject.\n \n * Deinitialized submodule: A `gitlink`, and a `.gitmodules` entry,\n-but no submodule working directory. The submodule’s git directory\n-may be there as after deinitializing the git directory is kept around.\n+but no submodule working directory. The submodule’s Git directory\n+may be there as after deinitializing the Git directory is kept around.\n The directory which is supposed to be the working directory is empty instead.\n +\n A submodule can be deinitialized by running `git submodule deinit`.\n@@ -160,6 +164,60 @@ from another repository.\n To completely remove a submodule, manually delete\n `$GIT_DIR/modules//`.\n \n+ACTIVE SUBMODULES\n+-----------------\n+\n+A submodule is considered active,\n+\n+ (a) if `submodule..active` is set to `true`\n+ or\n+ (b) if the submodule's path matches the pathspec in `submodule.active`\n+ or\n+ (c) if `submodule..url` is set.\n+\n+and these are evaluated in this order.\n+\n+For example:\n+\n+ [submodule \"foo\"]\n+ active = false\n+ url = https://example.org/foo\n+ [submodule \"bar\"]\n+ active = true\n+ url = https://example.org/bar\n+ [submodule \"baz\"]\n+ url = https://example.org/baz\n+\n+In the above config only the submodule 'bar' and 'baz' are active,\n+'bar' due to (a) and 'baz' due to (c). 'foo' is inactive because\n+(a) takes precedence over (c)\n+\n+Note that (c) is a historical artefact and will be ignored if the\n+(a) and (b) specify that the submodule is not active. In other words,\n+if we have an `submodule..active` set to `false` or if the\n+submodule's path is excluded in the pathspec in `submodule.active`, the\n+url doesn't matter whether it is present or not. This is illustrated in\n+the example that follows.\n+\n+ [submodule \"foo\"]\n+ active = true\n+ url = https://example.org/foo\n+ [submodule \"bar\"]\n+ url = https://example.org/bar\n+ [submodule \"baz\"]\n+ url = https://example.org/baz\n+ [submodule \"bob\"]\n+ ignore = true\n+ [submodule]\n+ active = b*\n+ active = :(exclude) baz\n+\n+In here all submodules except 'baz' (foo, bar, bob) are active.\n+'foo' due to its own active flag and all the others due to the\n+submodule active pathspec, which specifies that any submodule\n+starting with 'b' except 'baz' are also active, regardless of the\n+presence of the .url field.\n+\n Workflow for a third party library\n ----------------------------------\n \n-- \n2.16.0.rc1.281.g969645f98\n\n"},{"id":"336593","messageId":"20180114173737.13012-3-kaartic.sivaraam@gmail.com","threadId":"47553","inReplyTo":"20180114173737.13012-1-kaartic.sivaraam@gmail.com","subject":"[PATCH v3 2/2] Doc/git-submodule: improve readability and grammar of a sentence","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-14T17:37:37Z","receivedAt":"2018-01-14T17:38:27Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"While at it, correctly quote important words.\n\nSigned-off-by: Kaartic Sivaraam \n---\n Documentation/git-submodule.txt | 16 ++++++++--------\n 1 file changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex ff612001d..71c5618e8 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -70,8 +70,8 @@ status [--cached] [--recursive] [--] [...]::\n \tShow the status of the submodules. This will print the SHA-1 of the\n \tcurrently checked out commit for each submodule, along with the\n \tsubmodule path and the output of 'git describe' for the\n-\tSHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not\n-\tinitialized, `+` if the currently checked out submodule commit\n+\tSHA-1. Each SHA-1 will possibly be prefixed with `-` if the submodule is\n+\tnot initialized, `+` if the currently checked out submodule commit\n \tdoes not match the SHA-1 found in the index of the containing\n \trepository and `U` if the submodule has merge conflicts.\n +\n@@ -132,15 +132,15 @@ expects by cloning missing submodules and updating the working tree of\n the submodules. The \"updating\" can be done in several ways depending\n on command line options and the value of `submodule..update`\n configuration variable. The command line option takes precedence over\n-the configuration variable. if neither is given, a checkout is performed.\n-update procedures supported both from the command line as well as setting\n-`submodule..update`:\n+the configuration variable. If neither is given, a 'checkout' is performed.\n+The 'update' procedures supported both from the command line as well as\n+through the `submodule..update` configuration are:\n \n \tcheckout;; the commit recorded in the superproject will be\n \t checked out in the submodule on a detached HEAD.\n +\n If `--force` is specified, the submodule will be checked out (using\n-`git checkout --force` if appropriate), even if the commit specified\n+`git checkout --force`), even if the commit specified\n in the index of the containing repository already matches the commit\n checked out in the submodule.\n \n@@ -150,8 +150,8 @@ checked out in the submodule.\n \tmerge;; the commit recorded in the superproject will be merged\n \t into the current branch in the submodule.\n \n-The following procedures are only available via the `submodule..update`\n-configuration variable:\n+The following 'update' procedures are only available via the\n+`submodule..update` configuration variable:\n \n \tcustom command;; arbitrary shell command that takes a single\n \t argument (the sha1 of the commit recorded in the\n-- \n2.16.0.rc1.281.g969645f98\n\n"},{"id":"336673","messageId":"xmqqzi5dtvvg.fsf@gitster.mtv.corp.google.com","threadId":"47553","inReplyTo":"20180114173737.13012-1-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH v3 0/2] Doc/submodules: a few updates","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-01-16T20:02:43Z","receivedAt":"2018-01-16T20:02:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kaartic Sivaraam writes:\n\n> These are just a few improvements that I thought would make the documentation\n> related to submodules a little better in various way such as readability,\n> consistency etc., These were things I noticed while reading thise documents.\n\nOverall they look like reasonable improvements. I had a few \"Huh?\"\nmoments while reading the resulting text, but nothing show-stopping.\n"},{"id":"336674","messageId":"CAGZ79kZYidKKCNF1=ZCZaOgpNZu-tuaD4_56V1DTd9++_8YN=Q@mail.gmail.com","threadId":"47553","inReplyTo":"20180114173737.13012-2-kaartic.sivaraam@gmail.com","subject":"Re: [PATCH v3 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-01-16T20:03:52Z","receivedAt":"2018-01-16T20:04:00Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Sun, Jan 14, 2018 at 9:37 AM, Kaartic Sivaraam\n wrote:\n> * Only mention porcelain commands in examples\n>\n> * Split a sentence for better readability\n>\n> * Add missing apostrophes\n>\n> * Clearly specify the advantages of using submodules\n>\n> * Avoid abbreviations\n>\n> * Use \"Git\" consistently\n>\n> * Improve readability of certain lines\n>\n> * Clarify when a submodule is considered active\n>\n> Helped-by: Eric Sunshine \n> Helped-by: Stefan Beller \n> Signed-off-by: Kaartic Sivaraam \n> ---\n\nThanks,\nStefan\n\n> Documentation/gitsubmodules.txt | 100 +++++++++++++++++++++++++++++++---------\n> 1 file changed, 79 insertions(+), 21 deletions(-)\n>\n> diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\n> index 46cf120f6..4d6c17782 100644\n> --- a/Documentation/gitsubmodules.txt\n> +++ b/Documentation/gitsubmodules.txt\n> @@ -36,8 +36,8 @@ The `gitlink` entry contains the object name of the commit that the\n> superproject expects the submodule’s working directory to be at.\n>\n> The section `submodule.foo.*` in the `.gitmodules` file gives additional\n> -hints to Gits porcelain layer such as where to obtain the submodule via\n> -the `submodule.foo.url` setting.\n> +hints to Git's porcelain layer. For example, the `submodule.foo.url`\n> +setting specifies where to obtain the submodule.\n>\n> Submodules can be used for at least two different use cases:\n>\n> @@ -51,18 +51,21 @@ Submodules can be used for at least two different use cases:\n>\n> 2. Splitting a (logically single) project into multiple\n> repositories and tying them back together. This can be used to\n> - overcome current limitations of Gits implementation to have\n> + overcome current limitations of Git's implementation to have\n> finer grained access:\n>\n> - * Size of the git repository:\n> + * Size of the Git repository:\n> In its current form Git scales up poorly for large repositories containing\n> content that is not compressed by delta computation between trees.\n> - However you can also use submodules to e.g. hold large binary assets\n> - and these repositories are then shallowly cloned such that you do not\n> + For example, you can use submodules to hold large binary assets\n> + and these repositories can be shallowly cloned such that you do not\n> have a large history locally.\n> * Transfer size:\n> In its current form Git requires the whole working tree present. It\n> does not allow partial trees to be transferred in fetch or clone.\n> + If the project you work on consists of multiple repositories tied\n> + together as submodules in a superproject, you can avoid fetching the\n> + working trees of the repositories you are not interested in.\n> * Access control:\n> By restricting user access to submodules, this can be used to implement\n> read/write policies for different users.\n> @@ -73,9 +76,10 @@ The configuration of submodules\n> Submodule operations can be configured using the following mechanisms\n> (from highest to lowest precedence):\n>\n> - * The command line for those commands that support taking submodule specs.\n> - Most commands have a boolean flag '--recurse-submodules' whether to\n> - recurse into submodules. Examples are `ls-files` or `checkout`.\n> + * The command line for those commands that support taking submodules\n> + as part of their pathspecs. Most commands have a boolean flag\n> + `--recurse-submodules` which specify whether to recurse into submodules.\n> + Examples are `grep` and `checkout`.\n> Some commands take enums, such as `fetch` and `push`, where you can\n> specify how submodules are affected.\n>\n> @@ -87,8 +91,8 @@ Submodule operations can be configured using the following mechanisms\n> For example an effect from the submodule's `.gitignore` file\n> would be observed when you run `git status --ignore-submodules=none` in\n> the superproject. This collects information from the submodule's working\n> -directory by running `status` in the submodule, which does pay attention\n> -to its `.gitignore` file.\n> +directory by running `status` in the submodule while paying attention\n> +to the `.gitignore` file of the submodule.\n> +\n> The submodule's `$GIT_DIR/config` file would come into play when running\n> `git push --recurse-submodules=check` in the superproject, as this would\n> @@ -97,20 +101,20 @@ remotes are configured in the submodule as usual in the `$GIT_DIR/config`\n> file.\n>\n> * The configuration file `$GIT_DIR/config` in the superproject.\n> - Typical configuration at this place is controlling if a submodule\n> - is recursed into at all via the `active` flag for example.\n> + Git only recurses into active submodules (see \"ACTIVE SUBMODULES\"\n> + section below).\n> +\n> If the submodule is not yet initialized, then the configuration\n> -inside the submodule does not exist yet, so configuration where to\n> +inside the submodule does not exist yet, so where to\n> obtain the submodule from is configured here for example.\n>\n> - * the `.gitmodules` file inside the superproject. Additionally to the\n> - required mapping between submodule's name and path, a project usually\n> + * The `.gitmodules` file inside the superproject. A project usually\n> uses this file to suggest defaults for the upstream collection\n> - of repositories.\n> + of repositories for the mapping that is required between a\n> + submodule's name and its path.\n> +\n> -This file mainly serves as the mapping between name and path in\n> -the superproject, such that the submodule's git directory can be\n> +This file mainly serves as the mapping between the name and path of submodules\n> +in the superproject, such that the submodule's Git directory can be\n> located.\n> +\n> If the submodule has never been initialized, this is the only place\n> @@ -137,8 +141,8 @@ directory is automatically moved to `$GIT_DIR/modules//`\n> of the superproject.\n>\n> * Deinitialized submodule: A `gitlink`, and a `.gitmodules` entry,\n> -but no submodule working directory. The submodule’s git directory\n> -may be there as after deinitializing the git directory is kept around.\n> +but no submodule working directory. The submodule’s Git directory\n> +may be there as after deinitializing the Git directory is kept around.\n> The directory which is supposed to be the working directory is empty instead.\n> +\n> A submodule can be deinitialized by running `git submodule deinit`.\n> @@ -160,6 +164,60 @@ from another repository.\n> To completely remove a submodule, manually delete\n> `$GIT_DIR/modules//`.\n>\n> +ACTIVE SUBMODULES\n> +-----------------\n> +\n> +A submodule is considered active,\n> +\n> + (a) if `submodule..active` is set to `true`\n> + or\n> + (b) if the submodule's path matches the pathspec in `submodule.active`\n> + or\n> + (c) if `submodule..url` is set.\n> +\n> +and these are evaluated in this order.\n> +\n> +For example:\n> +\n> + [submodule \"foo\"]\n> + active = false\n> + url = https://example.org/foo\n> + [submodule \"bar\"]\n> + active = true\n> + url = https://example.org/bar\n> + [submodule \"baz\"]\n> + url = https://example.org/baz\n> +\n> +In the above config only the submodule 'bar' and 'baz' are active,\n> +'bar' due to (a) and 'baz' due to (c). 'foo' is inactive because\n> +(a) takes precedence over (c)\n> +\n> +Note that (c) is a historical artefact and will be ignored if the\n> +(a) and (b) specify that the submodule is not active. In other words,\n> +if we have an `submodule..active` set to `false` or if the\n> +submodule's path is excluded in the pathspec in `submodule.active`, the\n> +url doesn't matter whether it is present or not. This is illustrated in\n> +the example that follows.\n> +\n> + [submodule \"foo\"]\n> + active = true\n> + url = https://example.org/foo\n> + [submodule \"bar\"]\n> + url = https://example.org/bar\n> + [submodule \"baz\"]\n> + url = https://example.org/baz\n> + [submodule \"bob\"]\n> + ignore = true\n> + [submodule]\n> + active = b*\n> + active = :(exclude) baz\n> +\n> +In here all submodules except 'baz' (foo, bar, bob) are active.\n> +'foo' due to its own active flag and all the others due to the\n> +submodule active pathspec, which specifies that any submodule\n> +starting with 'b' except 'baz' are also active, regardless of the\n> +presence of the .url field.\n> +\n> Workflow for a third party library\n> ----------------------------------\n>\n> --\n> 2.16.0.rc1.281.g969645f98\n>\n"},{"id":"336689","messageId":"699d15e0-c178-1a5a-13b3-c34c6764a9a3@gmail.com","threadId":"47553","inReplyTo":"xmqqzi5dtvvg.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v3 0/2] Doc/submodules: a few updates","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2018-01-17T02:45:39Z","receivedAt":"2018-01-17T02:45:50Z","isPatch":true,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"On Wednesday 17 January 2018 01:32 AM, Junio C Hamano wrote:\n> I had a few \"Huh?\"\n> moments while reading the resulting text, but nothing show-stopping.\n> \n\nIt always happens when there are people around who are trying to be over\ncareful :)\n\nAnyways, it's only now that I remember that I've missed a change that I\nthought of doing. The change is about clarifying what a \"de-initialized\"\nsubmodule means and what an \"inactive\" submodule means and how they work\ntogether (IIUC, a submodule has not active flag when its deinitialized).\nI foresee people confusing 'init' and 'active'. So, I thought the\ndocumentation should be helpful enough in that aspect.\nDocumenation/gitsubmodules doesn't seem to be talking much about 'init'.\n(It talks about 'active' a lot after these patches :)\n\nNow I think it's better to do that as separate change and move this\nforward as I don't want to make this clumsy anymore. Please let me know,\nif I'm over thinking things again. :)\n\n-- \nKaartic\n\n"}]}