{"thread":{"id":"54695","subject":"[PATCH] glossary: improve \"branch\" definition","startedAt":"2020-11-23T20:05:59Z","lastAt":"2020-12-03T13:59:55Z","messageCount":8,"participants":["Sergey Organov","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"410561","messageId":"87blfnhm8w.fsf@osv.gnss.ru","threadId":"54695","inReplyTo":null,"subject":"[PATCH] glossary: improve \"branch\" definition","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2020-11-23T20:05:51Z","receivedAt":"2020-11-23T20:05:59Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"The old phrasing is at least questionable, if not wrong, as there are\na lot of branches out there that didn't see active development for\nyears, yet they are still branches, ready to become active again any\ntime.\n\nSigned-off-by: Sergey Organov \n---\n Documentation/glossary-content.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 090c888335d3..8bf198e72771 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -18,7 +18,7 @@\n \tUntyped <>, e.g. the contents of a file.\n \n [[def_branch]]branch::\n-\tA \"branch\" is an active line of development. The most recent\n+\tA \"branch\" is a separate line of development. The most recent\n \t<> on a branch is referred to as the tip of\n \tthat branch. The tip of the branch is referenced by a branch\n \t<>, which moves forward as additional development\n-- \n2.25.1\n\n"},{"id":"410582","messageId":"xmqq7dqbn1nl.fsf@gitster.c.googlers.com","threadId":"54695","inReplyTo":"87blfnhm8w.fsf@osv.gnss.ru","subject":"Re: [PATCH] glossary: improve \"branch\" definition","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-11-23T22:34:06Z","receivedAt":"2020-11-23T22:34:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> The old phrasing is at least questionable, if not wrong, as there are\n> a lot of branches out there that didn't see active development for\n> years, yet they are still branches, ready to become active again any\n> time.\n>\n> Signed-off-by: Sergey Organov \n> ---\n> Documentation/glossary-content.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index 090c888335d3..8bf198e72771 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -18,7 +18,7 @@\n> \tUntyped <>, e.g. the contents of a file.\n> \n> [[def_branch]]branch::\n> -\tA \"branch\" is an active line of development. The most recent\n> +\tA \"branch\" is a separate line of development. The most recent\n\nA dormant branch cannot be an \"active\" line of development, so in\nthat sense, the original is wrong. The description is better\nwithout the adjective \"active\".\n\nBut do we need to say \"a separate line of development\", instead of\njust \"a line of development\"? What is \"a line of development\" that\nis not separate? What extra pieces of information are we trying to\nconvey by having the word \"separate\" there?\n\n> \t<> on a branch is referred to as the tip of\n> \tthat branch. The tip of the branch is referenced by a branch\n> \t<>, which moves forward as additional development\n"},{"id":"410590","messageId":"87im9vekzf.fsf@osv.gnss.ru","threadId":"54695","inReplyTo":"xmqq7dqbn1nl.fsf@gitster.c.googlers.com","subject":"Re: [PATCH] glossary: improve \"branch\" definition","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2020-11-23T23:01:24Z","receivedAt":"2020-11-23T23:01:29Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> The old phrasing is at least questionable, if not wrong, as there are\n>> a lot of branches out there that didn't see active development for\n>> years, yet they are still branches, ready to become active again any\n>> time.\n>>\n>> Signed-off-by: Sergey Organov \n>> ---\n>> Documentation/glossary-content.txt | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n>> index 090c888335d3..8bf198e72771 100644\n>> --- a/Documentation/glossary-content.txt\n>> +++ b/Documentation/glossary-content.txt\n>> @@ -18,7 +18,7 @@\n>> \tUntyped <>, e.g. the contents of a file.\n>> \n>> [[def_branch]]branch::\n>> -\tA \"branch\" is an active line of development. The most recent\n>> +\tA \"branch\" is a separate line of development. The most recent\n>\n> A dormant branch cannot be an \"active\" line of development, so in\n> that sense, the original is wrong. The description is better\n> without the adjective \"active\".\n>\n> But do we need to say \"a separate line of development\", instead of\n> just \"a line of development\"? What is \"a line of development\" that\n> is not separate? What extra pieces of information are we trying to\n> convey by having the word \"separate\" there?\n\nI think it tries to convey a notion that 2 branches represent separate\nlines of development. I.e., that the whole purpose of branching is to\nprovide support for independent, or parallel, or /separate/ lines of\ndevelopment.\n\nI'm not going to insist on the exact wording though, -- just wanted to\nbring attention to the issue, and \"separate\" was somehow the first word\nthat came to mind when I edited the text.\n\nAs an after-thought, I'd probably add that branch in Git is represented\nby a chain of commits, and then I'd refer to most recent commit of the\nchain, instead of most recent commit on the branch. That'd make\ndefinition more formal and precise. Makes sense?\n\n-- Sergey Organov\n"},{"id":"410599","messageId":"xmqqr1ojlkng.fsf@gitster.c.googlers.com","threadId":"54695","inReplyTo":"87im9vekzf.fsf@osv.gnss.ru","subject":"Re: [PATCH] glossary: improve \"branch\" definition","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-11-23T23:26:43Z","receivedAt":"2020-11-23T23:27:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n>> But do we need to say \"a separate line of development\", instead of\n>> just \"a line of development\"? What is \"a line of development\" that\n>> is not separate? What extra pieces of information are we trying to\n>> convey by having the word \"separate\" there?\n>\n> I think it tries to convey a notion that 2 branches represent separate\n> lines of development. I.e., that the whole purpose of branching is to\n> provide support for independent, or parallel, or /separate/ lines of\n> development.\n\nSo in the context of talking about a branch, there is no need to say\n\"a separate line\". It only starts making sense to use the word\n\"separate\" whey you say \"this is a line of development. By the way,\nthere is another line of development that is separate from the first\none\".\n\n> I'm not going to insist on the exact wording though, -- just wanted to\n> bring attention to the issue, and \"separate\" was somehow the first word\n> that came to mind when I edited the text.\n>\n> As an after-thought, I'd probably add that branch in Git is represented\n> by a chain of commits, and then I'd refer to most recent commit of the\n> chain, instead of most recent commit on the branch. That'd make\n> definition more formal and precise. Makes sense?\n\nIt brings up a more serious issue, though. \n\n o---o---o---o---x A\n / \\\n ---o---o---o---o---o---o---y B\n\nThe only thing everybody can agree on in the above history is that\ncommit 'x' is at the tip of the branch A, and commit 'y' is at the\ntip of the branch B, and 'y^' is on the branch B. There is no good\nanswer to questions like\n\n where does branch 'A' begin?\n where does branch 'B' begin?\n\nPerhaps the merge to 'B' was from another branch that no longer\nexists (because the whole 4-commit chain was merged at that point to\nthe integration branch 'B'), and 'A' was forked from that branch\nwhose name was forgotten.\n\nAny commit in the history represents a line of development behind\nthat commit, and whether a commit is pointed at by a ref does not\nchange that. And development is not even a line when you include\nforking and merging.\n\nIn the mental model of Git about branches, I think the only one\nthing people can agree on is that a branch points at a commit, and\nchecking it out and making a commit on top of it will change that\nbranch to point at the newly created commit. And this view supports\nthe word \"separate\"---whether you have two branches pointing at the\nsame commit or a different one, building a new commit on and\nadvancing the tip of one branch does not affect the other branch.\n\nCome to think of it, the original \"active\" may not have been so bad\na word to begin with. It is misleading in the sense that \"active\"\nused in the original statement does not mean \"currently checked\nout\", but if we read it as \"potentially active---can grow in its own\ndirection\", it does convey that each branch can (although does not\nhave to) represent its own line of development.\n\nSo, I dunno. I'd say just settling on the simplest \"is a line of\ndevelopment\" would be the easiest path for now.\n\n\n"},{"id":"410721","messageId":"87r1oi1kig.fsf@osv.gnss.ru","threadId":"54695","inReplyTo":"xmqqr1ojlkng.fsf@gitster.c.googlers.com","subject":"Re: [PATCH] glossary: improve \"branch\" definition","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2020-11-24T22:02:15Z","receivedAt":"2020-11-24T22:02:21Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>>> But do we need to say \"a separate line of development\", instead of\n>>> just \"a line of development\"? What is \"a line of development\" that\n>>> is not separate? What extra pieces of information are we trying to\n>>> convey by having the word \"separate\" there?\n>>\n>> I think it tries to convey a notion that 2 branches represent separate\n>> lines of development. I.e., that the whole purpose of branching is to\n>> provide support for independent, or parallel, or /separate/ lines of\n>> development.\n>\n> So in the context of talking about a branch, there is no need to say\n> \"a separate line\". It only starts making sense to use the word\n> \"separate\" whey you say \"this is a line of development. By the way,\n> there is another line of development that is separate from the first\n> one\".\n>\n>> I'm not going to insist on the exact wording though, -- just wanted to\n>> bring attention to the issue, and \"separate\" was somehow the first word\n>> that came to mind when I edited the text.\n>>\n>> As an after-thought, I'd probably add that branch in Git is represented\n>> by a chain of commits, and then I'd refer to most recent commit of the\n>> chain, instead of most recent commit on the branch. That'd make\n>> definition more formal and precise. Makes sense?\n>\n> It brings up a more serious issue, though. \n>\n> o---o---o---o---x A\n> / \\\n> ---o---o---o---o---o---o---y B\n>\n> The only thing everybody can agree on in the above history is that\n> commit 'x' is at the tip of the branch A, and commit 'y' is at the\n> tip of the branch B,\n\nYeah, sure.\n\n> and 'y^' is on the branch B.\n\nI'm not that sure about 'y^', sorry, even if it now has no other\nreferences.\n\nI'm only sure that commits not reachable as first parents from B are not\non the branch B, and that there is a chain, even if empty, from \"Git\nbranch B\" (through first parent) that constitutes particular branch in\nthe user domain.\n\n> There is no good answer to questions like\n>\n> where does branch 'A' begin?\n> where does branch 'B' begin?\n\nThere is: \"it's undefined\".\n\nWhy does it matter for definition of the term \"branch\"? I think it\ndoesn't. Glossary didn't define where branches begin, and it'd still\nrefuse to define it. What's the issue with that?\n\nWhere exactly given branch starts lies entirely in the user domain, not\nin Git domain, so we don't need to define this in the Git glossary, I\nthink. We can mention why we left it undefined though, if it makes\nsense.\n\n>\n> Perhaps the merge to 'B' was from another branch that no longer\n> exists (because the whole 4-commit chain was merged at that point to\n> the integration branch 'B'), and 'A' was forked from that branch\n> whose name was forgotten.\n\nPerhaps, but I can't see how it's relevant to the glossary. It'd be\nessential if Git remembered on which branch which commit has been\ncreated, but it (fortunately) doesn't, so it (fortunately) isn't.\n\n> Any commit in the history represents a line of development behind\n> that commit, and whether a commit is pointed at by a ref does not\n> change that.\n\nSure. Moreover, user is free to consider this particular line of\ndevelopment to be a \"branch\", in his vocabulary.\n\nWe do not call /every/ line of development \"branch\" in Git proper, or do\nwe? I'd say that in Git proper \"branch\" is not a line of development at\nall, because Git doesn't care.\n\n> And development is not even a line when you include forking and\n> merging.\n\nDevelopment isn't. A line of development is \"a line\" by definition\nthough.\n\n>\n> In the mental model of Git about branches, I think the only one\n> thing people can agree on is that a branch points at a commit, and\n> checking it out and making a commit on top of it will change that\n> branch to point at the newly created commit. And this view supports\n> the word \"separate\"---whether you have two branches pointing at the\n> same commit or a different one, building a new commit on and\n> advancing the tip of one branch does not affect the other branch.\n\nSo, as it does make sense, why don't we stick to \"separate\"?\n\n> Come to think of it, the original \"active\" may not have been so bad\n> a word to begin with. It is misleading in the sense that \"active\"\n> used in the original statement does not mean \"currently checked\n> out\", but if we read it as \"potentially active---can grow in its own\n> direction\", it does convey that each branch can (although does not\n> have to) represent its own line of development.\n\nI don't get it. \"Potentially active\" is not what is a distinction of the\n\"branch\". Every commit is potentially active: \"git checkout\n\" and grow new history out of it. Further, even current branch\ncould be inactive, so I still fail to see any reason to use \"active\" in\nbranch definition.\n\n>\n> So, I dunno. I'd say just settling on the simplest \"is a line of\n> development\" would be the easiest path for now.\n\nThinking more about it, this first phrase is entirely user-domain\nentity, so we will have hard time to come up with strict definition\nanyway, and \"is a line of development\" is as fine with me as \"is a\nseparate line...\", cause both have nothing to do with Git the program\n:-)\n\nNow, if we stay inside Git proper in the glossary, we'd need to get rid\nof this first phrase and stick to what \"branch\" is in Git. And in Git\nit's just a specific type of reference that (unlike, say, tags) follows\nnew commits. It's interesting that from this definition follows that we\nmay easily consider HEAD to be a meta-branch, that, in addition to\nproperties of other branches, first, defines the point in the DAG new\ncommits are to be grown from, and second, can point to another branch.\n\nFor what it's worth, here is description of the \"branch\", as I see it:\n\nbranch: /branch/ is the way to refer by name to particular line of\n development represented as a /chain/ of commits. /Branch/ is\n implemented as specific kind of /reference/, called branch\n /head/, that always points to the most recent commit of the\n branch /chain/ it gives name to. This most recent commit of the\n branch chain is referred to as the tip of the branch. Branch\n head moves forward along with the branch tip as branch chain\n grows due to addition of new commits.\n\n Git /repository/ can have an arbitrary number of branches, but\n\tyour /working tree/ could be associated with at most one of them\n\tat any given time (the \"current\" or \"checked out\" branch), and\n\tspecial /reference/ called /HEAD/ points to the head of that\n\tbranch in this case.\n\n Alternatively, /HEAD/ could point directly to a commit rather\n than to a branch head, in which case an unnamed chain will grow\n from this commit as additional commits are being made. This mode\n of operation is referred to as \"detached HEAD\", though for\n uniformity it could be regarded as being on \"unnamed branch\".\n You can still give name to this \"unnamed branch\" at any time thus\n turning it into yet another regular branch.\n\n\n-- Sergey Organov\n"},{"id":"411155","messageId":"877dq05swb.fsf@osv.gnss.ru","threadId":"54695","inReplyTo":"xmqqr1ojlkng.fsf@gitster.c.googlers.com","subject":"Re: [PATCH] glossary: improve \"branch\" definition","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2020-12-02T11:50:12Z","receivedAt":"2020-12-02T11:50:58Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>>> But do we need to say \"a separate line of development\", instead of\n>>> just \"a line of development\"? What is \"a line of development\" that\n>>> is not separate? What extra pieces of information are we trying to\n>>> convey by having the word \"separate\" there?\n>>\n>> I think it tries to convey a notion that 2 branches represent separate\n>> lines of development. I.e., that the whole purpose of branching is to\n>> provide support for independent, or parallel, or /separate/ lines of\n>> development.\n>\n> So in the context of talking about a branch, there is no need to say\n> \"a separate line\". It only starts making sense to use the word\n> \"separate\" whey you say \"this is a line of development. By the way,\n> there is another line of development that is separate from the first\n> one\".\n\n[...]\n\n> In the mental model of Git about branches, I think the only one\n> thing people can agree on is that a branch points at a commit, and\n> checking it out and making a commit on top of it will change that\n> branch to point at the newly created commit. And this view supports\n> the word \"separate\"---whether you have two branches pointing at the\n> same commit or a different one, building a new commit on and\n> advancing the tip of one branch does not affect the other branch.\n\nSo, what do we finally do? Just remove \"active\", or replace it with\n\"separate\"?\n\nIt's fine with me either way. Will you just fix it yourself, or should I\nre-roll if \"separate\" is not accepted?\n\n-- Sergey\n"},{"id":"411184","messageId":"xmqq5z5jlsw3.fsf@gitster.c.googlers.com","threadId":"54695","inReplyTo":"877dq05swb.fsf@osv.gnss.ru","subject":"Re: [PATCH] glossary: improve \"branch\" definition","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-12-02T22:55:56Z","receivedAt":"2020-12-02T22:56:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> So, what do we finally do? Just remove \"active\", or replace it with\n> \"separate\"?\n> ...\n> It's fine with me either way. Will you just fix it yourself, or should I\n> re-roll if \"separate\" is not accepted?\n\nLet's see ... gitster goes and looks for what he suggested ...\n\n So, I dunno. I'd say just settling on the simplest \"is a line of\n development\" would be the easiest path for now.\n\nI've queued the following.\n\nThanks for pinging a stalled thread.\n\n--- >8 ------ >8 ------ >8 ------ >8 ------ >8 ------ >8 ------ >8 ---\nFrom: Sergey Organov \nDate: Mon, 23 Nov 2020 23:05:51 +0300\nSubject: [PATCH] glossary: improve \"branch\" definition\n\nThe old phrasing is at least questionable, if not wrong, as there are\na lot of branches out there that didn't see active development for\nyears, yet they are still branches, ready to become active again any\ntime.\n\nSigned-off-by: Sergey Organov \nSigned-off-by: Junio C Hamano \n---\n\nNotes (amlog):\n Message-Id: <87blfnhm8w.fsf@osv.gnss.ru>\n\n Documentation/glossary-content.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 090c888335..67c7a50b96 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -18,7 +18,7 @@\n \tUntyped <>, e.g. the contents of a file.\n \n [[def_branch]]branch::\n-\tA \"branch\" is an active line of development. The most recent\n+\tA \"branch\" is a line of development. The most recent\n \t<> on a branch is referred to as the tip of\n \tthat branch. The tip of the branch is referenced by a branch\n \t<>, which moves forward as additional development\n-- \n2.29.2-577-g9ac7fd3f3f\n\n"},{"id":"411221","messageId":"87ft4nhuba.fsf@osv.gnss.ru","threadId":"54695","inReplyTo":"xmqq5z5jlsw3.fsf@gitster.c.googlers.com","subject":"Re: [PATCH] glossary: improve \"branch\" definition","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2020-12-03T13:51:05Z","receivedAt":"2020-12-03T13:59:55Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> So, what do we finally do? Just remove \"active\", or replace it with\n>> \"separate\"?\n>> ...\n>> It's fine with me either way. Will you just fix it yourself, or should I\n>> re-roll if \"separate\" is not accepted?\n>\n> Let's see ... gitster goes and looks for what he suggested ...\n>\n> So, I dunno. I'd say just settling on the simplest \"is a line of\n> development\" would be the easiest path for now.\n>\n> I've queued the following.\n\nNice, thanks!\n\n-- Sergey\n\n>\n> Thanks for pinging a stalled thread.\n>\n> --- >8 ------ >8 ------ >8 ------ >8 ------ >8 ------ >8 ------ >8 ---\n> From: Sergey Organov \n> Date: Mon, 23 Nov 2020 23:05:51 +0300\n> Subject: [PATCH] glossary: improve \"branch\" definition\n>\n> The old phrasing is at least questionable, if not wrong, as there are\n> a lot of branches out there that didn't see active development for\n> years, yet they are still branches, ready to become active again any\n> time.\n>\n> Signed-off-by: Sergey Organov \n> Signed-off-by: Junio C Hamano \n> ---\n>\n> Notes (amlog):\n> Message-Id: <87blfnhm8w.fsf@osv.gnss.ru>\n>\n> Documentation/glossary-content.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index 090c888335..67c7a50b96 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -18,7 +18,7 @@\n> \tUntyped <>, e.g. the contents of a file.\n> \n> [[def_branch]]branch::\n> -\tA \"branch\" is an active line of development. The most recent\n> +\tA \"branch\" is a line of development. The most recent\n> \t<> on a branch is referred to as the tip of\n> \tthat branch. The tip of the branch is referenced by a branch\n> \t<>, which moves forward as additional development\n"}]}