{"thread":{"id":"39442","subject":"[PATCH] glossary: add \"remote\" and \"submodule\"","startedAt":"2015-05-27T21:13:29Z","lastAt":"2015-05-28T18:50:17Z","messageCount":9,"participants":["Stefan Beller","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"262279","messageId":"1432761209-4120-1-git-send-email-sbeller@google.com","threadId":"39442","inReplyTo":null,"subject":"[PATCH] glossary: add \"remote\" and \"submodule\"","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-05-27T21:13:29Z","receivedAt":"2015-05-27T21:13:29Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Noticed-by: Philip Oakley \nSigned-off-by: Stefan Beller \n---\n Documentation/glossary-content.txt | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex bf383c2..e303135 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -469,6 +469,11 @@ The most notable example is `HEAD`.\n \t<> to describe the mapping between remote\n \t<> and local ref.\n \n+[[def_remote]]remote repository::\n+\tA <> which is used to track the same\n+\tproject but resides somewhere else. To communicate with remotes,\n+\tsee <> or <>.\n+\n [[def_remote_tracking_branch]]remote-tracking branch::\n \tA <> that is used to follow changes from another\n \t<>. It typically looks like\n@@ -515,6 +520,11 @@ The most notable example is `HEAD`.\n \tis created by giving the `--depth` option to linkgit:git-clone[1], and\n \tits history can be later deepened with linkgit:git-fetch[1].\n \n+[[def_submodule]]submodule::\n+\tA <> inside another repository. The two\n+\trepositories have different history, though the outer repository\n+\tknows the commit of the inner repository.\n+\n [[def_symref]]symref::\n \tSymbolic reference: instead of containing the <>\n \tid itself, it is of the format 'ref: refs/some/thing' and when\n-- \n2.4.1.345.gab207b6.dirty\n"},{"id":"262295","messageId":"xmqq617dk621.fsf@gitster.dls.corp.google.com","threadId":"39442","inReplyTo":"1432761209-4120-1-git-send-email-sbeller@google.com","subject":"Re: [PATCH] glossary: add \"remote\" and \"submodule\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-27T22:29:42Z","receivedAt":"2015-05-27T22:29:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> Noticed-by: Philip Oakley \n> Signed-off-by: Stefan Beller \n> ---\n> Documentation/glossary-content.txt | 10 ++++++++++\n> 1 file changed, 10 insertions(+)\n>\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index bf383c2..e303135 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -469,6 +469,11 @@ The most notable example is `HEAD`.\n> \t<> to describe the mapping between remote\n> \t<> and local ref.\n> \n> +[[def_remote]]remote repository::\n> +\tA <> which is used to track the same\n> +\tproject but resides somewhere else. To communicate with remotes,\n> +\tsee <> or <>.\n> +\n\nOK.\n\n> @@ -515,6 +520,11 @@ The most notable example is `HEAD`.\n> \tis created by giving the `--depth` option to linkgit:git-clone[1], and\n> \tits history can be later deepened with linkgit:git-fetch[1].\n> \n> +[[def_submodule]]submodule::\n> +\tA <> inside another repository. The two\n> +\trepositories have different history, though the outer repository\n> +\tknows the commit of the inner repository.\n\nI'd stress that they are not just different histories (as the\n'master' and the 'maint' branches of my project has different\nhistories) but they are separate projects. Perhaps like this?\n\n A repository that holds the history of a separate project\n inside another repository (the latter of which is called\n superproject). The containing superproject knows about the\n names of (but does not hold copies of) commit objects of the\n contained submodules.\n\nIt is not like that it is strange or unintuitive that the\nsuperproject knows about some commits in its submodule. \"X, though\nY\" however makes it sound as if Y is true \"despite X\". I do not\nthink there is any \"despite\" here.\n"},{"id":"262297","messageId":"CAGZ79kbz6d8j1p5d-pO2cpou76ivhkCQPq4cpGxozc-9cnACPQ@mail.gmail.com","threadId":"39442","inReplyTo":"xmqq617dk621.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] glossary: add \"remote\" and \"submodule\"","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-05-27T22:59:41Z","receivedAt":"2015-05-27T22:59:41Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Wed, May 27, 2015 at 3:29 PM, Junio C Hamano wrote:\n> Stefan Beller writes:\n>\n>> Noticed-by: Philip Oakley \n>> Signed-off-by: Stefan Beller \n>> ---\n>> Documentation/glossary-content.txt | 10 ++++++++++\n>> 1 file changed, 10 insertions(+)\n>>\n>> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n>> index bf383c2..e303135 100644\n>> --- a/Documentation/glossary-content.txt\n>> +++ b/Documentation/glossary-content.txt\n>> @@ -469,6 +469,11 @@ The most notable example is `HEAD`.\n>> <> to describe the mapping between remote\n>> <> and local ref.\n>>\n>> +[[def_remote]]remote repository::\n>> + A <> which is used to track the same\n>> + project but resides somewhere else. To communicate with remotes,\n>> + see <> or <>.\n>> +\n>\n> OK.\n>\n>> @@ -515,6 +520,11 @@ The most notable example is `HEAD`.\n>> is created by giving the `--depth` option to linkgit:git-clone[1], and\n>> its history can be later deepened with linkgit:git-fetch[1].\n>>\n>> +[[def_submodule]]submodule::\n>> + A <> inside another repository. The two\n>> + repositories have different history, though the outer repository\n>> + knows the commit of the inner repository.\n>\n> I'd stress that they are not just different histories (as the\n> 'master' and the 'maint' branches of my project has different\n> histories) but they are separate projects. Perhaps like this?\n\nThis is a very subtle distinction IMHO, as both master and maint\n\"are the same project\". Looking from enough distance, it's just the\ngit project without the fine detail of what makes these 2 histories different.\nI tried coming up with a short paragraph, which may explain my choice\nof words. But correctness trumps brevity indeed.\n\n>\n> A repository that holds the history of a separate project\n> inside another repository (the latter of which is called\n> superproject).\n\nThis is better than what I proposed, but confusing. When naming\na project a submodule, my mental standpoint is the superproject.\n(\"This project has the submodule foo and bar\"). But In your description\nthe superproject is called \"another repository\".\n\n> The containing superproject knows about the\n> names of (but does not hold copies of) commit objects of the\n> contained submodules.\n\nThat makes sense to point out here. Though should we also introduce\n\"superproject\" now?\n\n>\n> It is not like that it is strange or unintuitive that the\n> superproject knows about some commits in its submodule. \"X, though\n> Y\" however makes it sound as if Y is true \"despite X\". I do not\n> think there is any \"despite\" here.\n"},{"id":"262298","messageId":"xmqqwpztiptw.fsf@gitster.dls.corp.google.com","threadId":"39442","inReplyTo":"CAGZ79kbz6d8j1p5d-pO2cpou76ivhkCQPq4cpGxozc-9cnACPQ@mail.gmail.com","subject":"Re: [PATCH] glossary: add \"remote\" and \"submodule\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-27T23:05:31Z","receivedAt":"2015-05-27T23:05:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n>>> +[[def_submodule]]submodule::\n>>> + A <> inside another repository. The two\n>>> + repositories have different history, though the outer repository\n>>> + knows the commit of the inner repository.\n>>\n> ... But correctness trumps brevity indeed.\n\nI do not think the correct way is that much longer, though.\n\nA repository inside another repository. The two repositories have different history\nA repository that holds the history of a separate project inside another repository\n\nHeh, they are the same length, no?\n\n>\n>>\n>> A repository that holds the history of a separate project\n>> inside another repository (the latter of which is called\n>> superproject).\n>\n> This is better than what I proposed, but confusing. When naming\n> a project a submodule, my mental standpoint is the superproject.\n> (\"This project has the submodule foo and bar\"). But In your description\n> the superproject is called \"another repository\".\n\nThat is because you are adding an entry for \"submodule\" to the\nglossary, no? I was writing from submodule's point of view, i.e. \"I\n(submodule) is inside another repository, and my project is separate\nfrom that other repository's\".\n\n>> The containing superproject knows about the\n>> names of (but does not hold copies of) commit objects of the\n>> contained submodules.\n>\n> That makes sense to point out here. Though should we also introduce\n> \"superproject\" now?\n\nYes, that is what I was hinting at.\n"},{"id":"262300","messageId":"CAGZ79kauSsZK3_X+zTwL8TKuZiHNMGvMZfoCemW9-K7RWgrgCA@mail.gmail.com","threadId":"39442","inReplyTo":"xmqqwpztiptw.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] glossary: add \"remote\" and \"submodule\"","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-05-27T23:29:13Z","receivedAt":"2015-05-27T23:29:13Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Wed, May 27, 2015 at 4:05 PM, Junio C Hamano wrote:\n> Stefan Beller writes:\n>\n>>>> +[[def_submodule]]submodule::\n>>>> + A <> inside another repository. The two\n>>>> + repositories have different history, though the outer repository\n>>>> + knows the commit of the inner repository.\n>>>\n>> ... But correctness trumps brevity indeed.\n>\n> I do not think the correct way is that much longer, though.\n>\n> A repository inside another repository. The two repositories have different history\n> A repository that holds the history of a separate project inside another repository\n>\n> Heh, they are the same length, no?\n>\n>>\n>>>\n>>> A repository that holds the history of a separate project\n>>> inside another repository (the latter of which is called\n>>> superproject).\n>>\n>> This is better than what I proposed, but confusing. When naming\n>> a project a submodule, my mental standpoint is the superproject.\n>> (\"This project has the submodule foo and bar\"). But In your description\n>> the superproject is called \"another repository\".\n>\n> That is because you are adding an entry for \"submodule\" to the\n> glossary, no? I was writing from submodule's point of view, i.e. \"I\n> (submodule) is inside another repository, and my project is separate\n> from that other repository's\".\n\nThe submodule doesn't know it's a submodule though, so the point of view\n\"I (as a submodule)\" only happens rarely in the real world?\nI have a library in mind when talking about submodules. And the libraries\nmaintainer may not care if their library is used as a submodule or just\n\"make install\"ed or just put somewhere in the filesystem\n\nUsually submodules are only interesting from the superprojects point of view,\nlike \"I want to upgrade libfoo now, so I make a commit changing the gitlink\nof the submodule to point at that tag/commit\"\nThat's why I found the presented perspective a bit strange.\n\n>\n>>> The containing superproject knows about the\n>>> names of (but does not hold copies of) commit objects of the\n>>> contained submodules.\n>>\n>> That makes sense to point out here. Though should we also introduce\n>> \"superproject\" now?\n>\n> Yes, that is what I was hinting at.\n\nok\n"},{"id":"262303","messageId":"1432777801-6073-1-git-send-email-sbeller@google.com","threadId":"39442","inReplyTo":"CAGZ79kauSsZK3_X+zTwL8TKuZiHNMGvMZfoCemW9-K7RWgrgCA@mail.gmail.com","subject":"[PATCH] glossary: add \"remote\", \"submodule\", \"superproject\"","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-05-28T01:50:01Z","receivedAt":"2015-05-28T01:50:01Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Noticed-by: Philip Oakley \nHelped-by: Junio C Hamano \nSigned-off-by: Stefan Beller \n---\n Documentation/glossary-content.txt | 17 +++++++++++++++++\n 1 file changed, 17 insertions(+)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex bf383c2..23ab692 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -469,6 +469,11 @@ The most notable example is `HEAD`.\n \t<> to describe the mapping between remote\n \t<> and local ref.\n \n+[[def_remote]]remote repository::\n+\tA <> which is used to track the same\n+\tproject but resides somewhere else. To communicate with remotes,\n+\tsee <> or <>.\n+\n [[def_remote_tracking_branch]]remote-tracking branch::\n \tA <> that is used to follow changes from another\n \t<>. It typically looks like\n@@ -515,6 +520,18 @@ The most notable example is `HEAD`.\n \tis created by giving the `--depth` option to linkgit:git-clone[1], and\n \tits history can be later deepened with linkgit:git-fetch[1].\n \n+[[def_submodule]]submodule::\n+\tA <> that holds the history of a\n+\tseparate project inside another repository (the latter of\n+\twhich is called <>). The\n+\tcontaining superproject knows about the names of (but does\n+\tnot hold copies of) commit objects of the contained submodules.\n+\n+[[def_superproject]]superproject::\n+\tA <> that references other repositories\n+\tinside itself as <>. The superproject\n+\ttracks only the remote and the name of the submodule.\n+\n [[def_symref]]symref::\n \tSymbolic reference: instead of containing the <>\n \tid itself, it is of the format 'ref: refs/some/thing' and when\n-- \n2.4.1.345.gab207b6.dirty\n"},{"id":"262339","messageId":"xmqqk2vsirbe.fsf@gitster.dls.corp.google.com","threadId":"39442","inReplyTo":"1432777801-6073-1-git-send-email-sbeller@google.com","subject":"Re: [PATCH] glossary: add \"remote\", \"submodule\", \"superproject\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-28T16:45:41Z","receivedAt":"2015-05-28T16:45:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> Noticed-by: Philip Oakley \n> Helped-by: Junio C Hamano \n> Signed-off-by: Stefan Beller \n> ---\n> Documentation/glossary-content.txt | 17 +++++++++++++++++\n> 1 file changed, 17 insertions(+)\n\nThe updates in this version relative to the previous one looks very\ngood, at least to me. A bit more comments.\n\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index bf383c2..23ab692 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -469,6 +469,11 @@ The most notable example is `HEAD`.\n> \t<> to describe the mapping between remote\n> \t<> and local ref.\n> \n> +[[def_remote]]remote repository::\n> +\tA <> which is used to track the same\n> +\tproject but resides somewhere else. To communicate with remotes,\n> +\tsee <> or <>.\n> +\n\nThe last sentence sounds a tiny bit strange, in that I have to do a\nbit more than just see the explanation of these commands in order to\ncommunicate with remotes.\n\nBut it probably is just me.\n\n> @@ -515,6 +520,18 @@ The most notable example is `HEAD`.\n> \tis created by giving the `--depth` option to linkgit:git-clone[1], and\n> \tits history can be later deepened with linkgit:git-fetch[1].\n> \n> +[[def_submodule]]submodule::\n> +\tA <> that holds the history of a\n> +\tseparate project inside another repository (the latter of\n> +\twhich is called <>). The\n> +\tcontaining superproject knows about the names of (but does\n> +\tnot hold copies of) commit objects of the contained submodules.\n\nI agree with one point you mentioned in one of your messages, which\nis that a submodule is not aware that it is used as part of a larger\nproject. That makes me wonder if the last sentence sits better in\nthe description of the superproject, rather than the description of\nthe submodule.\n\n> +[[def_superproject]]superproject::\n> +\tA <> that references other repositories\n> +\tinside itself as <>.\n\nPerhaps \"repositories of other projects\"? Does \"inside\" make it\nclear enough that we are talking about the relationship between\nworking trees of the superproject and submodules?\n\n> +\tThe superproject\n> +\ttracks only the remote and the name of the submodule.\n\nI am not sure what this sentence means [*1*], and I do not know if\n(a corrected version of) such a description is necessary here.\n\nThanks.\n\n[Footnote]\n\n*1* The superproject records a bit more than \"remote and name\" in\n.gitmodules, and of course it records the history of the paths that\nthe submodule is bound to over time, with specific commits from the\nsubmodule in its history.\n"},{"id":"262352","messageId":"CAGZ79kb7M9L-xkMEG1GhAhYVWPR3env2fLiWt4fpbB=e6+jUhA@mail.gmail.com","threadId":"39442","inReplyTo":"xmqqk2vsirbe.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] glossary: add \"remote\", \"submodule\", \"superproject\"","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2015-05-28T17:52:17Z","receivedAt":"2015-05-28T17:52:17Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Thu, May 28, 2015 at 9:45 AM, Junio C Hamano wrote:\n> Stefan Beller writes:\n>\n>> Noticed-by: Philip Oakley \n>> Helped-by: Junio C Hamano \n>> Signed-off-by: Stefan Beller \n>> ---\n>> Documentation/glossary-content.txt | 17 +++++++++++++++++\n>> 1 file changed, 17 insertions(+)\n>\n> The updates in this version relative to the previous one looks very\n> good, at least to me. A bit more comments.\n>\n>> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n>> index bf383c2..23ab692 100644\n>> --- a/Documentation/glossary-content.txt\n>> +++ b/Documentation/glossary-content.txt\n>> @@ -469,6 +469,11 @@ The most notable example is `HEAD`.\n>> <> to describe the mapping between remote\n>> <> and local ref.\n>>\n>> +[[def_remote]]remote repository::\n>> + A <> which is used to track the same\n>> + project but resides somewhere else. To communicate with remotes,\n>> + see <> or <>.\n>> +\n>\n> The last sentence sounds a tiny bit strange, in that I have to do a\n> bit more than just see the explanation of these commands in order to\n> communicate with remotes.\n\nMaybe s/see/use/ here?\n\n>\n> But it probably is just me.\n>\n>> @@ -515,6 +520,18 @@ The most notable example is `HEAD`.\n>> is created by giving the `--depth` option to linkgit:git-clone[1], and\n>> its history can be later deepened with linkgit:git-fetch[1].\n>>\n>> +[[def_submodule]]submodule::\n>> + A <> that holds the history of a\n>> + separate project inside another repository (the latter of\n>> + which is called <>). The\n>> + containing superproject knows about the names of (but does\n>> + not hold copies of) commit objects of the contained submodules.\n>\n> I agree with one point you mentioned in one of your messages, which\n> is that a submodule is not aware that it is used as part of a larger\n> project. That makes me wonder if the last sentence sits better in\n> the description of the superproject, rather than the description of\n> the submodule.\n\nMoved in the upcoming reroll.\n\n>\n>> +[[def_superproject]]superproject::\n>> + A <> that references other repositories\n>> + inside itself as <>.\n>\n> Perhaps \"repositories of other projects\"? Does \"inside\" make it\n> clear enough that we are talking about the relationship between\n> working trees of the superproject and submodules?\n\n\n A <> that references repositories\n of other projects in its working tree as <>.\n\n>\n>> + The superproject\n>> + tracks only the remote and the name of the submodule.\n>\n> I am not sure what this sentence means [*1*], and I do not know if\n> (a corrected version of) such a description is necessary here.\n\nWhen looking at submodules and subtrees I feel they behave similar\nto symbolic and hard links. If you delete the remote of the submodule\nyou need to take care when dealing with the superproject, similar\nto repairing a dangling symlink. (\"Is it gone or just moved? Where\ndo I point it now?\")\n\nMy intend here was to show that submodules are fragile like symlinks are.\n\nUsually a repository (or a file in that analogy) is quite self contained,\nif you have a copy of the repository, you can do lots of operation on it\nlike reading, changing(writing), moving. If there is a broken (git/sym-)link\nreading in full becomes a hassle, as parts are missing.\n\nI am not sure if the discussion belongs into the glossary though.\nBut where would you start looking for information if you want to decided\nwhether to use submodules or subtrees?\n\n>\n> Thanks.\n>\n> [Footnote]\n>\n> *1* The superproject records a bit more than \"remote and name\" in\n> .gitmodules, and of course it records the history of the paths that\n> the submodule is bound to over time, with specific commits from the\n> submodule in its history.\n>\n"},{"id":"262359","messageId":"xmqqlhg8h6za.fsf@gitster.dls.corp.google.com","threadId":"39442","inReplyTo":"CAGZ79kb7M9L-xkMEG1GhAhYVWPR3env2fLiWt4fpbB=e6+jUhA@mail.gmail.com","subject":"Re: [PATCH] glossary: add \"remote\", \"submodule\", \"superproject\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-05-28T18:50:17Z","receivedAt":"2015-05-28T18:50:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> I am not sure if the discussion belongs into the glossary though.\n\nProbably not. Perhaps in tutorial.\n"}]}