{"thread":{"id":"39388","subject":"[PATCH] submodule documentation: Reorder introductory paragraphs","startedAt":"2015-05-20T23:11:57Z","lastAt":"2015-05-22T19:47:38Z","messageCount":13,"participants":["Stefan Beller","Heiko Voigt","Junio C Hamano","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"261727","messageId":"1432163517-22785-1-git-send-email-sbeller@google.com","threadId":"39388","inReplyTo":null,"subject":"[PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-05-20T23:11:57Z","receivedAt":"2015-05-20T23:11:57Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"It's better to start the man page with a description of what submodules\nactually are instead of saying what they are not.\n\nReorder the paragraphs such that\nthe first short paragraph introduces the submodule concept,\nthe second paragraph highlights the usage of the submodule command,\nthe third paragraph giving background information,\nand finally the fourth paragraph discusing alternatives such\nas subtrees and remotes, which we don't want to be confused with.\n\nThis ordering deepens the knowledge on submodules with each paragraph.\nFirst the basic questions like \"How/what\" will be answered, while the\nunderlying concepts will be taught at a later time.\n\nMaking sure it is not confused with subtrees and remotes is not really\nenhancing knowledge of submodules itself, but rather painting the big\npicture of git concepts, so you could also argue to have it as the second\nparagraph. Personally I think this may confuse readers, specially newcomers\nthough.\n\nSigned-off-by: Stefan Beller <sbeller@google.com>\n---\n Documentation/git-submodule.txt | 54 ++++++++++++++++++++---------------------\n 1 file changed, 26 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 2c25916..6c38c0d 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -25,35 +25,12 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Submodules allow foreign repositories to be embedded within\n-a dedicated subdirectory of the source tree, always pointed\n-at a particular commit.\n+Submodules allow other repositories to be embedded within\n+a dedicated subdirectory of the source tree pointing\n+at a particular commit in the other repository.\n \n-They are not to be confused with remotes, which are meant mainly\n-for branches of the same project; submodules are meant for\n-different projects you would like to make part of your source tree,\n-while the history of the two projects still stays completely\n-independent and you cannot modify the contents of the submodule\n-from within the main project.\n-If you want to merge the project histories and want to treat the\n-aggregated whole as a single project from then on, you may want to\n-add a remote for the other project and use the 'subtree' merge strategy,\n-instead of treating the other project as a submodule. Directories\n-that come from both projects can be cloned and checked out as a whole\n-if you choose to go that route.\n-\n-Submodules are composed from a so-called `gitlink` tree entry\n-in the main repository that refers to a particular commit object\n-within the inner repository that is completely separate.\n-A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the\n-root of the source tree assigns a logical name to the submodule and\n-describes the default URL the submodule shall be cloned from.\n-The logical name can be used for overriding this URL within your\n-local repository configuration (see 'submodule init').\n-\n-This command will manage the tree entries and contents of the\n-gitmodules file for you, as well as inspect the status of your\n-submodules and update them.\n+This command will manage the submodules for you, as well as\n+inspect the status of your submodules and update them.\n When adding a new submodule to the tree, the 'add' subcommand\n is to be used.  However, when pulling a tree containing submodules,\n these will not be checked out by default;\n@@ -64,6 +41,27 @@ using the 'status' subcommand and get a detailed overview of the\n difference between the index and checkouts using the 'summary'\n subcommand.\n \n+Submodules are composed from a so-called `gitlink` tree entry\n+in the main repository that refers to a particular commit object\n+within the inner repository that is completely separate.\n+A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the\n+root of the source tree assigns a logical name to the submodule and\n+describes the default URL the submodule shall be cloned from.\n+The logical name can be used for overriding this URL within your\n+local repository configuration (see 'submodule init').\n+\n+Submodules are not to be confused with remotes, which are meant\n+mainly for branches of the same project; submodules are meant for\n+different projects you would like to make part of your source tree,\n+while the history of the two projects still stays completely\n+independent and you cannot modify the contents of the submodule\n+from within the main project.\n+If you want to merge the project histories and want to treat the\n+aggregated whole as a single project from then on, you may want to\n+add a remote for the other project and use the 'subtree' merge strategy,\n+instead of treating the other project as a submodule. Directories\n+that come from both projects can be cloned and checked out as a whole\n+if you choose to go that route.\n \n COMMANDS\n --------\n-- \n2.4.0.194.gc518059\n"},{"id":"261776","messageId":"20150521130429.GB22553@book.hvoigt.net","threadId":"39388","inReplyTo":"1432163517-22785-1-git-send-email-sbeller@google.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Heiko Voigt","fromEmail":"hvoigt@hvoigt.net","sentAt":"2015-05-21T13:04:30Z","receivedAt":"2015-05-21T13:04:30Z","isPatch":true,"sender":{"key":"hvoigt@hvoigt.net","avatar":"https://avatars.githubusercontent.com/u/184958?v=4"},"body":"On Wed, May 20, 2015 at 04:11:57PM -0700, Stefan Beller wrote:\n> It's better to start the man page with a description of what submodules\n> actually are instead of saying what they are not.\n> \n> Reorder the paragraphs such that\n> the first short paragraph introduces the submodule concept,\n> the second paragraph highlights the usage of the submodule command,\n> the third paragraph giving background information,\n> and finally the fourth paragraph discusing alternatives such\n> as subtrees and remotes, which we don't want to be confused with.\n> \n> This ordering deepens the knowledge on submodules with each paragraph.\n> First the basic questions like \"How/what\" will be answered, while the\n> underlying concepts will be taught at a later time.\n> \n> Making sure it is not confused with subtrees and remotes is not really\n> enhancing knowledge of submodules itself, but rather painting the big\n> picture of git concepts, so you could also argue to have it as the second\n> paragraph. Personally I think this may confuse readers, specially newcomers\n> though.\n> \n> Signed-off-by: Stefan Beller <sbeller@google.com>\n\nLooks good to me.\n\nCheers Heiko\n"},{"id":"261810","messageId":"xmqqoaldkfmy.fsf@gitster.dls.corp.google.com","threadId":"39388","inReplyTo":"1432163517-22785-1-git-send-email-sbeller@google.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-21T17:24:37Z","receivedAt":"2015-05-21T17:24:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller <sbeller@google.com> writes:\n\n> Reorder the paragraphs such that\n> the first short paragraph introduces the submodule concept,\n> the second paragraph highlights the usage of the submodule command,\n> the third paragraph giving background information,\n> and finally the fourth paragraph discusing alternatives such\n> as subtrees and remotes, which we don't want to be confused with.\n>\n> This ordering deepens the knowledge on submodules with each paragraph.\n> First the basic questions like \"How/what\" will be answered, while the\n> underlying concepts will be taught at a later time.\n\nSounds good.\n\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 2c25916..6c38c0d 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -25,35 +25,12 @@ SYNOPSIS\n>  \n>  DESCRIPTION\n>  -----------\n> -Submodules allow foreign repositories to be embedded within\n> -a dedicated subdirectory of the source tree, always pointed\n> -at a particular commit.\n> +Submodules allow other repositories to be embedded within\n> +a dedicated subdirectory of the source tree pointing\n> +at a particular commit in the other repository.\n\nNot a new problem, but I can misread this as if it requires the\ntop-level superproject to have one single dedicated directory D to\nhouse all the foreign projects under it, D/project1, D/project2, ...\n\n> -This command will manage the tree entries and contents of the\n> -gitmodules file for you, as well as inspect the status of your\n> -submodules and update them.\n> +This command will manage the submodules for you, as well as\n> +inspect the status of your submodules and update them.\n\nNot a new problem, but does the command really \"manage them for\nyou\"?  I view it more like \"You can use this command to manage,\ninspect and update the submodules\".\n"},{"id":"261819","messageId":"CAGZ79katx04bKiyyvS1JnzQ40G0dGO-yS+zYY4jQ62X4DpmbxA@mail.gmail.com","threadId":"39388","inReplyTo":"xmqqoaldkfmy.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-05-21T17:43:55Z","receivedAt":"2015-05-21T17:43:55Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Thu, May 21, 2015 at 10:24 AM, Junio C Hamano <gitster@pobox.com> wrote:\n> Stefan Beller <sbeller@google.com> writes:\n>\n>> Reorder the paragraphs such that\n>> the first short paragraph introduces the submodule concept,\n>> the second paragraph highlights the usage of the submodule command,\n>> the third paragraph giving background information,\n>> and finally the fourth paragraph discusing alternatives such\n>> as subtrees and remotes, which we don't want to be confused with.\n>>\n>> This ordering deepens the knowledge on submodules with each paragraph.\n>> First the basic questions like \"How/what\" will be answered, while the\n>> underlying concepts will be taught at a later time.\n>\n> Sounds good.\n>\n>> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n>> index 2c25916..6c38c0d 100644\n>> --- a/Documentation/git-submodule.txt\n>> +++ b/Documentation/git-submodule.txt\n>> @@ -25,35 +25,12 @@ SYNOPSIS\n>>\n>>  DESCRIPTION\n>>  -----------\n>> -Submodules allow foreign repositories to be embedded within\n>> -a dedicated subdirectory of the source tree, always pointed\n>> -at a particular commit.\n>> +Submodules allow other repositories to be embedded within\n>> +a dedicated subdirectory of the source tree pointing\n>> +at a particular commit in the other repository.\n>\n> Not a new problem, but I can misread this as if it requires the\n> top-level superproject to have one single dedicated directory D to\n> house all the foreign projects under it, D/project1, D/project2, ...\n\nI agree, maybe we should reword the paragraphs themselves as well.\n\n    Submodules allow you to keep another Git repository in a subdirectory\n    of your repository. The other repository has its own history, which does not\n    interfere with the history of the current repository. This can be used to\n    have external dependencies such as libraries for example.\n\n>\n>> -This command will manage the tree entries and contents of the\n>> -gitmodules file for you, as well as inspect the status of your\n>> -submodules and update them.\n>> +This command will manage the submodules for you, as well as\n>> +inspect the status of your submodules and update them.\n>\n> Not a new problem, but does the command really \"manage them for\n> you\"?  I view it more like \"You can use this command to manage,\n> inspect and update the submodules\".\n\nI agree.\n"},{"id":"261843","messageId":"9AF4B2205E154BDA863E8CAAACAE0BDF@PhilipOakley","threadId":"39388","inReplyTo":"1432163517-22785-1-git-send-email-sbeller@google.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-05-21T20:03:25Z","receivedAt":"2015-05-21T20:03:25Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Stefan Beller\" <sbeller@google.com>\n> It's better to start the man page with a description of what \n> submodules\n> actually are instead of saying what they are not.\n>\n> Reorder the paragraphs such that\n> the first short paragraph introduces the submodule concept,\n> the second paragraph highlights the usage of the submodule command,\n> the third paragraph giving background information,\n> and finally the fourth paragraph discusing alternatives such\n> as subtrees and remotes, which we don't want to be confused with.\n>\n> This ordering deepens the knowledge on submodules with each paragraph.\n> First the basic questions like \"How/what\" will be answered, while the\n> underlying concepts will be taught at a later time.\n>\n> Making sure it is not confused with subtrees and remotes is not really\n> enhancing knowledge of submodules itself, but rather painting the big\n> picture of git concepts, so you could also argue to have it as the \n> second\n> paragraph. Personally I think this may confuse readers, specially \n> newcomers\n> though.\n>\n> Signed-off-by: Stefan Beller <sbeller@google.com>\n> ---\n> Documentation/git-submodule.txt | 54 \n> ++++++++++++++++++++---------------------\n> 1 file changed, 26 insertions(+), 28 deletions(-)\n>\n> diff --git a/Documentation/git-submodule.txt \n> b/Documentation/git-submodule.txt\n> index 2c25916..6c38c0d 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -25,35 +25,12 @@ SYNOPSIS\n>\n> DESCRIPTION\n> -----------\n> -Submodules allow foreign repositories to be embedded within\n> -a dedicated subdirectory of the source tree, always pointed\n> -at a particular commit.\n> +Submodules allow other repositories to be embedded within\n> +a dedicated subdirectory of the source tree pointing\n> +at a particular commit in the other repository.\n>\n> -They are not to be confused with remotes, which are meant mainly\n> -for branches of the same project; submodules are meant for\n> -different projects you would like to make part of your source tree,\n> -while the history of the two projects still stays completely\n> -independent and you cannot modify the contents of the submodule\n> -from within the main project.\n> -If you want to merge the project histories and want to treat the\n> -aggregated whole as a single project from then on, you may want to\n> -add a remote for the other project and use the 'subtree' merge \n> strategy,\n> -instead of treating the other project as a submodule. Directories\n> -that come from both projects can be cloned and checked out as a whole\n> -if you choose to go that route.\n> -\n> -Submodules are composed from a so-called `gitlink` tree entry\n> -in the main repository that refers to a particular commit object\n> -within the inner repository that is completely separate.\n> -A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the\n> -root of the source tree assigns a logical name to the submodule and\n> -describes the default URL the submodule shall be cloned from.\n> -The logical name can be used for overriding this URL within your\n> -local repository configuration (see 'submodule init').\n> -\n> -This command will manage the tree entries and contents of the\n> -gitmodules file for you, as well as inspect the status of your\n> -submodules and update them.\n> +This command will manage the submodules for you, as well as\n> +inspect the status of your submodules and update them.\n> When adding a new submodule to the tree, the 'add' subcommand\n> is to be used.  However, when pulling a tree containing submodules,\n> these will not be checked out by default;\n> @@ -64,6 +41,27 @@ using the 'status' subcommand and get a detailed \n> overview of the\n> difference between the index and checkouts using the 'summary'\n> subcommand.\n>\n> +Submodules are composed from a so-called `gitlink` tree entry\n> +in the main repository that refers to a particular commit object\n> +within the inner repository that is completely separate.\n> +A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the\n> +root of the source tree assigns a logical name to the submodule and\n> +describes the default URL the submodule shall be cloned from.\n> +The logical name can be used for overriding this URL within your\n> +local repository configuration (see 'submodule init').\n> +\n> +Submodules are not to be confused with remotes, which are meant\n> +mainly for branches of the same project;\n\nThis use of 'branches' didn't work for me. \"remotes are meant mainly for \nbranches of the same project\" ?\n\n>  submodules are meant for\n> +different projects you would like to make part of your source tree,\n> +while the history of the two projects still stays completely\n> +independent and you cannot modify the contents of the submodule\n> +from within the main project.\n> +If you want to merge the project histories and want to treat the\n> +aggregated whole as a single project from then on, you may want to\n> +add a remote for the other project and use the 'subtree' merge \n> strategy,\n> +instead of treating the other project as a submodule. Directories\n> +that come from both projects can be cloned and checked out as a whole\n> +if you choose to go that route.\n>\n--\nPhilip \n"},{"id":"261860","messageId":"CAGZ79kZ5yxG7k++9QFRhnb=6A3HD64Kz3_B9UBrHA+Akht8tZw@mail.gmail.com","threadId":"39388","inReplyTo":"9AF4B2205E154BDA863E8CAAACAE0BDF@PhilipOakley","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-05-21T22:08:30Z","receivedAt":"2015-05-21T22:08:30Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Thu, May 21, 2015 at 1:03 PM, Philip Oakley <philipoakley@iee.org> wrote:\n>> +Submodules are not to be confused with remotes, which are meant\n>> +mainly for branches of the same project;\n>\n>\n> This use of 'branches' didn't work for me. \"remotes are meant mainly for\n> branches of the same project\" ?\n>\n\nMaybe\n\n    Submodules should not be confused with remote repositories, which are\n    meant to track the same repository, just at another location; ...\n\n? Though I'm not yet completely happy with that either.\n"},{"id":"261888","messageId":"6259B4241C4241D8A9104D3A49C36957@PhilipOakley","threadId":"39388","inReplyTo":"CAGZ79kZ5yxG7k++9QFRhnb=6A3HD64Kz3_B9UBrHA+Akht8tZw@mail.gmail.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-05-22T06:59:56Z","receivedAt":"2015-05-22T06:59:56Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Stefan Beller\" <sbeller@google.com>\n> On Thu, May 21, 2015 at 1:03 PM, Philip Oakley <philipoakley@iee.org> \n> wrote:\n>>> +Submodules are not to be confused with remotes, which are meant\n>>> +mainly for branches of the same project;\n>>\n>>\n>> This use of 'branches' didn't work for me. \"remotes are meant mainly \n>> for\n>> branches of the same project\" ?\n>>\n>\n> Maybe\n>\n>    Submodules should not be confused with remote repositories, which \n> are\n>    meant to track the same repository, just at another location; ...\n>\n> ? Though I'm not yet completely happy with that either.\n>\n\nI like that better. I was going to check what the git glossary said a \nremote was, but the commute to work beckons...\n\nPhilip \n"},{"id":"261911","messageId":"xmqqwq00fzlv.fsf@gitster.dls.corp.google.com","threadId":"39388","inReplyTo":"CAGZ79kZ5yxG7k++9QFRhnb=6A3HD64Kz3_B9UBrHA+Akht8tZw@mail.gmail.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-22T14:36:44Z","receivedAt":"2015-05-22T14:36:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller <sbeller@google.com> writes:\n\n> On Thu, May 21, 2015 at 1:03 PM, Philip Oakley <philipoakley@iee.org> wrote:\n>>> +Submodules are not to be confused with remotes, which are meant\n>>> +mainly for branches of the same project;\n>>\n>> This use of 'branches' didn't work for me. \"remotes are meant mainly for\n>> branches of the same project\" ?\n\nThe \"branch\" in the original is used in a much wider sense than\nusual branch (i.e. ref/heads/ thing you have locally); it refers to\nforks of the same project but with a bit of twist.  When you say\nrepository A is a fork of the same project as my local repository,\nyou would give an impression that A is not the authoritative copy of\nthe project.  But you can say my repository and that repository A\nare branches of the same project, you give zero information as to\nA's authoritativeness.\n\n>     Submodules should not be confused with remote repositories, which are\n>     meant to track the same repository, just at another location; ...\n\nI do not think this is a great improvement.  You now conflated\n\"repository\" to mean \"project\" in the latter half of the sentence,\nwhile you are trying to explain what a \"remote repository\" is.\n\nYour copy of git.git is not the same repository as mine; they have\ndifferent histories.  Both repositories are used to work on the same\nproject.  \"submoules are not remotes, which are other repositories\nof the same project\", perhaps?\n"},{"id":"261927","messageId":"CAGZ79kYiG9=px3P+k1shqvt8ouXmfJjeKgCarj6KEQy08WAmjg@mail.gmail.com","threadId":"39388","inReplyTo":"xmqqwq00fzlv.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-05-22T17:05:54Z","receivedAt":"2015-05-22T17:05:54Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Fri, May 22, 2015 at 7:36 AM, Junio C Hamano <gitster@pobox.com> wrote:\n> Stefan Beller <sbeller@google.com> writes:\n>\n>> On Thu, May 21, 2015 at 1:03 PM, Philip Oakley <philipoakley@iee.org> wrote:\n>>>> +Submodules are not to be confused with remotes, which are meant\n>>>> +mainly for branches of the same project;\n>>>\n>>> This use of 'branches' didn't work for me. \"remotes are meant mainly for\n>>> branches of the same project\" ?\n>\n> The \"branch\" in the original is used in a much wider sense than\n> usual branch (i.e. ref/heads/ thing you have locally); it refers to\n> forks of the same project but with a bit of twist.  When you say\n> repository A is a fork of the same project as my local repository,\n> you would give an impression that A is not the authoritative copy of\n> the project.  But you can say my repository and that repository A\n> are branches of the same project, you give zero information as to\n> A's authoritativeness.\n\nWhile this is correct, I think it is also confusing, because 'branch'\nis a command which deals with local branches only in my perception\nTo deal with remote branches you need to use the commands\n{remote, fetch, pull}.\n\nSo when someone mentions \"branch\" I need to think of local operations\nin one repository and not on different distributed histories.\n\n>\n>>     Submodules should not be confused with remote repositories, which are\n>>     meant to track the same repository, just at another location; ...\n>\n> I do not think this is a great improvement.  You now conflated\n> \"repository\" to mean \"project\" in the latter half of the sentence,\n> while you are trying to explain what a \"remote repository\" is.\n\nThat's true.\n\n>\n> Your copy of git.git is not the same repository as mine; they have\n> different histories.  Both repositories are used to work on the same\n> project.  \"submoules are not remotes, which are other repositories\n> of the same project\", perhaps?\n\nThat makes sense.\n"},{"id":"261931","messageId":"xmqqvbfked6u.fsf@gitster.dls.corp.google.com","threadId":"39388","inReplyTo":"CAGZ79kYiG9=px3P+k1shqvt8ouXmfJjeKgCarj6KEQy08WAmjg@mail.gmail.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-22T17:26:17Z","receivedAt":"2015-05-22T17:26:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller <sbeller@google.com> writes:\n\n> On Fri, May 22, 2015 at 7:36 AM, Junio C Hamano <gitster@pobox.com> wrote:\n>> Stefan Beller <sbeller@google.com> writes:\n>>\n>>> On Thu, May 21, 2015 at 1:03 PM, Philip Oakley <philipoakley@iee.org> wrote:\n>>>>> +Submodules are not to be confused with remotes, which are meant\n>>>>> +mainly for branches of the same project;\n>>>>\n>>>> This use of 'branches' didn't work for me. \"remotes are meant mainly for\n>>>> branches of the same project\" ?\n>>\n>> The \"branch\" in the original is used in a much wider sense than\n>> usual branch (i.e. ref/heads/ thing you have locally); it refers to\n>> forks of the same project but with a bit of twist.  When you say\n>> repository A is a fork of the same project as my local repository,\n>> you would give an impression that A is not the authoritative copy of\n>> the project.  But you can say my repository and that repository A\n>> are branches of the same project, you give zero information as to\n>> A's authoritativeness.\n>\n> While this is correct, I think it is also confusing, because...\n\nOh, no question about it.  In modern Git parlance, it confuses by\nconflating 'branch' (which is local ref/heads/ thing) with something\nentirely different.  I wasn't saying \"'branch' is correct and we\nshould keep the description that way\".\n\nIf you dig ancient list archives, you see Linus and I using 'branch'\nto mean \"your copy of the project\" quite often, and that is likely\nwhere the above phrase originated.  It was one of those \"explaining\nhistorical background\", nothing more.\n\nI probably should start prefixing all my \"explaining historical\nbackground\" sentences as such.\n\n>> I do not think this is a great improvement.  You now conflated\n>> \"repository\" to mean \"project\" in the latter half of the sentence,\n>> while you are trying to explain what a \"remote repository\" is.\n>\n> That's true.\n>>\n>> Your copy of git.git is not the same repository as mine; they have\n>> different histories.  Both repositories are used to work on the same\n>> project.  \"submoules are not remotes, which are other repositories\n>> of the same project\", perhaps?\n>\n> That makes sense.\n\nThanks.\n"},{"id":"261932","messageId":"05CAAED4A70A416590A620BF584E7F3D@PhilipOakley","threadId":"39388","inReplyTo":"CAGZ79kYiG9=px3P+k1shqvt8ouXmfJjeKgCarj6KEQy08WAmjg@mail.gmail.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-05-22T17:35:41Z","receivedAt":"2015-05-22T17:35:41Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Stefan Beller\" <sbeller@google.com>\n> On Fri, May 22, 2015 at 7:36 AM, Junio C Hamano <gitster@pobox.com> \n> wrote:\n>> Stefan Beller <sbeller@google.com> writes:\n>>\n>>> On Thu, May 21, 2015 at 1:03 PM, Philip Oakley \n>>> <philipoakley@iee.org> wrote:\n>>>>> +Submodules are not to be confused with remotes, which are meant\n>>>>> +mainly for branches of the same project;\n>>>>\n>>>> This use of 'branches' didn't work for me. \"remotes are meant \n>>>> mainly for\n>>>> branches of the same project\" ?\n>>\n>> The \"branch\" in the original is used in a much wider sense than\n>> usual branch (i.e. ref/heads/ thing you have locally); it refers to\n>> forks of the same project but with a bit of twist.  When you say\n>> repository A is a fork of the same project as my local repository,\n>> you would give an impression that A is not the authoritative copy of\n>> the project.  But you can say my repository and that repository A\n>> are branches of the same project, you give zero information as to\n>> A's authoritativeness.\n>\n> While this is correct, I think it is also confusing, because 'branch'\n> is a command which deals with local branches only in my perception\n> To deal with remote branches you need to use the commands\n> {remote, fetch, pull}.\n>\n> So when someone mentions \"branch\" I need to think of local operations\n> in one repository and not on different distributed histories.\n>\n\nIf we are having difficulties defining a \"remote\" here (its not defined \nin gitglossary.txt anyway), why not simply put a full stop (period) \nafter the \"Submodules are not to be confused with remotes.\", and bypass \nthe problem, avoiding digging the hole deeper.\n\n>>\n>>>     Submodules should not be confused with remote repositories, \n>>> which are\n>>>     meant to track the same repository, just at another location; \n>>> ...\n>>\n>> I do not think this is a great improvement.  You now conflated\n>> \"repository\" to mean \"project\" in the latter half of the sentence,\n>> while you are trying to explain what a \"remote repository\" is.\n>\n> That's true.\n>\n>>\n>> Your copy of git.git is not the same repository as mine; they have\n>> different histories.  Both repositories are used to work on the same\n>> project.  \"submoules are not remotes, which are other repositories\n>> of the same project\", perhaps?\n>\n> That makes sense.\n>\n\nIf maybe that the feature we should pick on is the common root of the \ndevelopment between the local and remote repository, and quite distinct \nfor the submodule. This allows remotes to be on the same machine, as \nwell as distant machines and server.\n\nIt is I believe technically possible to have a submodule which is its \nown super project, with and without recursion, but would be very \natypical, and would belong in the 'don't do that' category \n"},{"id":"261934","messageId":"CAGZ79kYD9hjKGK=G7p+3-JEiFP7gGd8ERzdnocGDU8S1h6nDNA@mail.gmail.com","threadId":"39388","inReplyTo":"05CAAED4A70A416590A620BF584E7F3D@PhilipOakley","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-05-22T17:51:57Z","receivedAt":"2015-05-22T17:51:57Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Fri, May 22, 2015 at 10:35 AM, Philip Oakley <philipoakley@iee.org> wrote:\n> From: \"Stefan Beller\" <sbeller@google.com>\n>>\n>> On Fri, May 22, 2015 at 7:36 AM, Junio C Hamano <gitster@pobox.com> wrote:\n>>>\n>>> Stefan Beller <sbeller@google.com> writes:\n>>>\n>>>> On Thu, May 21, 2015 at 1:03 PM, Philip Oakley <philipoakley@iee.org>\n>>>> wrote:\n>>>>>>\n>>>>>> +Submodules are not to be confused with remotes, which are meant\n>>>>>> +mainly for branches of the same project;\n>>>>>\n>>>>>\n>>>>> This use of 'branches' didn't work for me. \"remotes are meant mainly\n>>>>> for\n>>>>> branches of the same project\" ?\n>>>\n>>>\n>>> The \"branch\" in the original is used in a much wider sense than\n>>> usual branch (i.e. ref/heads/ thing you have locally); it refers to\n>>> forks of the same project but with a bit of twist.  When you say\n>>> repository A is a fork of the same project as my local repository,\n>>> you would give an impression that A is not the authoritative copy of\n>>> the project.  But you can say my repository and that repository A\n>>> are branches of the same project, you give zero information as to\n>>> A's authoritativeness.\n>>\n>>\n>> While this is correct, I think it is also confusing, because 'branch'\n>> is a command which deals with local branches only in my perception\n>> To deal with remote branches you need to use the commands\n>> {remote, fetch, pull}.\n>>\n>> So when someone mentions \"branch\" I need to think of local operations\n>> in one repository and not on different distributed histories.\n>>\n>\n> If we are having difficulties defining a \"remote\" here (its not defined in\n> gitglossary.txt anyway),\n\nNow that we have a discussion on what remotes are, I'll send a patch for that\nas well.\n\n> why not simply put a full stop (period) after the\n> \"Submodules are not to be confused with remotes.\", and bypass the problem,\n> avoiding digging the hole deeper.\n\nI think we should dig deeper and point out the differences as it may\nnot be clear what\nthe differences are for new comers. Not digging deeper sounds to me like saying\n\n    'git frotz' is not to be confused with 'git bar' FULL STOP AND I\nWONT TELL YOU WHY!\n\nwhich is not helpful. (Why is the documentation pointing out there is\na difference to\nthat other command/concept, but not saying what is different?)\n\n>\n>>>\n>>>>     Submodules should not be confused with remote repositories, which\n>>>> are\n>>>>     meant to track the same repository, just at another location; ...\n>>>\n>>>\n>>> I do not think this is a great improvement.  You now conflated\n>>> \"repository\" to mean \"project\" in the latter half of the sentence,\n>>> while you are trying to explain what a \"remote repository\" is.\n>>\n>>\n>> That's true.\n>>\n>>>\n>>> Your copy of git.git is not the same repository as mine; they have\n>>> different histories.  Both repositories are used to work on the same\n>>> project.  \"submoules are not remotes, which are other repositories\n>>> of the same project\", perhaps?\n>>\n>>\n>> That makes sense.\n>>\n>\n> If maybe that the feature we should pick on is the common root of the\n> development between the local and remote repository, and quite distinct for\n> the submodule. This allows remotes to be on the same machine, as well as\n> distant machines and server.\n\nI don't think this is actually true for all remotes. Think of shallow clones\n(they have no root or a different root) or even subtrees which are pulled\nin via a remotes?\n\nThe main thing about remotes is \"not being here\" (as in \"part of this\nrepository\". As you point out it can be nearby in the local fs or even on\nanother machine, or in the cloud)\n\n>\n> It is I believe technically possible to have a submodule which is its own\n> super project, with and without recursion, but would be very atypical, and\n> would belong in the 'don't do that' category\n"},{"id":"261942","messageId":"7A83EF56E45A425A9756B4B084CA69A1@PhilipOakley","threadId":"39388","inReplyTo":"CAGZ79kYD9hjKGK=G7p+3-JEiFP7gGd8ERzdnocGDU8S1h6nDNA@mail.gmail.com","subject":"Re: [PATCH] submodule documentation: Reorder introductory paragraphs","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-05-22T19:47:38Z","receivedAt":"2015-05-22T19:47:38Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Stefan Beller\" <sbeller@google.com>\n> On Fri, May 22, 2015 at 10:35 AM, Philip Oakley <philipoakley@iee.org> \n> wrote:\n>> From: \"Stefan Beller\" <sbeller@google.com>\n>>>\n>>> On Fri, May 22, 2015 at 7:36 AM, Junio C Hamano <gitster@pobox.com> \n>>> wrote:\n>>>>\n>>>> Stefan Beller <sbeller@google.com> writes:\n>>>>\n>>>>> On Thu, May 21, 2015 at 1:03 PM, Philip Oakley \n>>>>> <philipoakley@iee.org>\n>>>>> wrote:\n>>>>>>>\n>>>>>>> +Submodules are not to be confused with remotes, which are meant\n>>>>>>> +mainly for branches of the same project;\n>>>>>>\n>>>>>>\n>>>>>> This use of 'branches' didn't work for me. \"remotes are meant \n>>>>>> mainly\n>>>>>> for\n>>>>>> branches of the same project\" ?\n>>>>\n>>>>\n>>>> The \"branch\" in the original is used in a much wider sense than\n>>>> usual branch (i.e. ref/heads/ thing you have locally); it refers to\n>>>> forks of the same project but with a bit of twist.  When you say\n>>>> repository A is a fork of the same project as my local repository,\n>>>> you would give an impression that A is not the authoritative copy \n>>>> of\n>>>> the project.  But you can say my repository and that repository A\n>>>> are branches of the same project, you give zero information as to\n>>>> A's authoritativeness.\n>>>\n>>>\n>>> While this is correct, I think it is also confusing, because \n>>> 'branch'\n>>> is a command which deals with local branches only in my perception\n>>> To deal with remote branches you need to use the commands\n>>> {remote, fetch, pull}.\n>>>\n>>> So when someone mentions \"branch\" I need to think of local \n>>> operations\n>>> in one repository and not on different distributed histories.\n>>>\n>>\n>> If we are having difficulties defining a \"remote\" here (its not \n>> defined in\n>> gitglossary.txt anyway),\n>\n> Now that we have a discussion on what remotes are, I'll send a patch \n> for that\n> as well.\n>\n>> why not simply put a full stop (period) after the\n>> \"Submodules are not to be confused with remotes.\", and bypass the \n>> problem,\n>> avoiding digging the hole deeper.\n>\n> I think we should dig deeper and point out the differences as it may\n> not be clear what\n> the differences are for new comers. Not digging deeper sounds to me \n> like saying\n>\n>    'git frotz' is not to be confused with 'git bar' FULL STOP AND I\n> WONT TELL YOU WHY!\n\nHi Stefan,\nThis was more of a case of \"simply a full stop, 'cos I can't easily tell \nyou why\" ;-).  I've seen too many work situations (*) where colleagues \njust dig deeper when they should stop digging, hence the note. It may be \nthat the style of reason could be changed. This is the final \nintroductory paragraph and was being pushed down partly because of this \nproblem (explaining things by saying what its not).\n\n(*) The usual phrase in a report would be \"A moments thought will show \nthat ...\" for those concepts that would take two pages to explain and \nwould still be misunderstood by the unthinking folks.\n\nThat all said, if a nice well understood explanatory phrase can be found \nthen I'm all for it.\n\n>\n> which is not helpful. (Why is the documentation pointing out there is\n> a difference to\n> that other command/concept, but not saying what is different?)\n>\n>>\n>>>>\n>>>>>     Submodules should not be confused with remote repositories, \n>>>>> which\n>>>>> are\n>>>>>     meant to track the same repository, just at another location; \n>>>>> ...\n>>>>\n>>>>\n>>>> I do not think this is a great improvement.  You now conflated\n>>>> \"repository\" to mean \"project\" in the latter half of the sentence,\n>>>> while you are trying to explain what a \"remote repository\" is.\n>>>\n>>>\n>>> That's true.\n>>>\n>>>>\n>>>> Your copy of git.git is not the same repository as mine; they have\n>>>> different histories.  Both repositories are used to work on the \n>>>> same\n>>>> project.  \"submoules are not remotes, which are other repositories\n>>>> of the same project\", perhaps?\n>>>\n>>>\n>>> That makes sense.\n>>>\n>>\n>> If maybe that the feature we should pick on is the common root of the\n>> development between the local and remote repository, and quite \n>> distinct for\n>> the submodule. This allows remotes to be on the same machine, as well \n>> as\n>> distant machines and server.\n>\n> I don't think this is actually true for all remotes. Think of shallow \n> clones\n> (they have no root or a different root) or even subtrees which are \n> pulled\n> in via a remotes?\n\nI'd avoided mentioning that potential explanation mud-hole on the same \nbasis that it would be hard.\n\n>\n> The main thing about remotes is \"not being here\" (as in \"part of this\n> repository\". As you point out it can be nearby in the local fs or even \n> on\n> another machine, or in the cloud)\n>\n>>\n>> It is I believe technically possible to have a submodule which is its \n>> own\n>> super project, with and without recursion, but would be very \n>> atypical, and\n>> would belong in the 'don't do that' category\n>\nregards\nPhilip \n"}]}