{"thread":{"id":"56027","subject":"PATCH: improve git switch documentation","startedAt":"2021-06-29T15:28:57Z","lastAt":"2021-07-19T17:52:27Z","messageCount":103,"participants":["Martin","Junio C Hamano","Matt Rogers","Sergey Organov","Felipe Contreras","Randall S. Becker","Bagas Sanjaya","Kerry, Richard"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"428756","messageId":"c593a699-eaf2-c7ab-b522-bfd224fce829@mfriebe.de","threadId":"56027","inReplyTo":null,"subject":"PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-06-29T15:28:48Z","receivedAt":"2021-06-29T15:28:57Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"Below is a patch, that I believe would improve the documentation of git \nswitch.\n\nThe exact new wording is of course open for debate.\n\nReasoning for the change.\n\nThe current doc does not explain why the option is a \"forceful\" option.\nNor does explain the consequences.\n\nInstead it leaves it to the user to lookup the alternate command, and \nfind the meaning of\n     git branch -f newbranch\n\nOnly if the user does that successfully, the user may learn about the \nfull consequences of their actions.\n\nI believe this info should be part of the \"git switch\" doc, itself. \n(Especially due to the severity that the action may have).\n\n\n\n From 46580d07f95a18c94925afd141ba55e52a82c8e1 Mon Sep 17 00:00:00 2001\nFrom: Martin \nDate: Tue, 29 Jun 2021 17:22:25 +0200\nSubject: [PATCH] Update git-switch.txt\n\n---\n Documentation/git-switch.txt | 8 ++++++--\n 1 file changed, 6 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\nindex 5c438cd5058758..80acafad1f4a46 100644\n--- a/Documentation/git-switch.txt\n+++ b/Documentation/git-switch.txt\n@@ -70,8 +70,12 @@ $ git switch \n -C ::\n --force-create ::\n \tSimilar to `--create` except that if `` already\n-\texists, it will be reset to ``. This is a\n-\tconvenient shortcut for:\n+\texists, it will be reset to ``.\n+\tThis forces the branch to the new location. It also forces\n+\tany commit hold by the branch to be dropped, unless the\n+\tcommit is also part of any other branch too. You may\n+\ttherefore loose some of your data.\n+\tThis is a convenient shortcut for:\n +\n ------------\n $ git branch -f \n\n"},{"id":"428757","messageId":"xmqqk0mcy6g2.fsf@gitster.g","threadId":"56027","inReplyTo":"c593a699-eaf2-c7ab-b522-bfd224fce829@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-06-29T16:35:41Z","receivedAt":"2021-06-29T16:35:47Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin writes:\n\n> Below is a patch, that I believe would improve the documentation of\n> git switch.\n>\n> The exact new wording is of course open for debate.\n>\n> Reasoning for the change.\n>\n> The current doc does not explain why the option is a \"forceful\" option.\n> Nor does explain the consequences.\n>\n> Instead it leaves it to the user to lookup the alternate command, and\n> find the meaning of\n>     git branch -f newbranch\n>\n> Only if the user does that successfully, the user may learn about the\n> full consequences of their actions.\n>\n> I believe this info should be part of the \"git switch\" doc,\n> itself. (Especially due to the severity that the action may have).\n\nPlease place all of the above below the three-dash line.\n\n> From 46580d07f95a18c94925afd141ba55e52a82c8e1 Mon Sep 17 00:00:00 2001\n\nLose this line.\n\n> From: Martin \n\nGet rid of this line, too, as you have your own e-mail address on\nthe real \"From\" line of the e-mail.\n\n> Date: Tue, 29 Jun 2021 17:22:25 +0200\n\nThis too.\n\n> Subject: [PATCH] Update git-switch.txt\n\nAnd this one, too.\n\n>\n\nAnd then justify and describe the change here (see\nDocumentation/SubmittingPatches::describe-changes)\n\nImmediately before the three-dash line below, have your sign-off\n(see Documentation/SubmittingPatches::sign-off).\n\n> ---\n> Documentation/git-switch.txt | 8 ++++++--\n> 1 file changed, 6 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\n> index 5c438cd5058758..80acafad1f4a46 100644\n> --- a/Documentation/git-switch.txt\n> +++ b/Documentation/git-switch.txt\n> @@ -70,8 +70,12 @@ $ git switch \n> -C ::\n> --force-create ::\n> \tSimilar to `--create` except that if `` already\n> -\texists, it will be reset to ``. This is a\n> -\tconvenient shortcut for:\n> +\texists, it will be reset to ``.\n> +\tThis forces the branch to the new location.\n\nI would have written \"This forces the branch to point at a different\ncommit\", as we do not have to use a fuzzy word \"location\" in this\ncontext (is it a location in the directory structure in the working\ntree? is it a location in the history dag? is it a location in\nsome other dimension?).\n\nUp to this point, it makes sense.\n\n> + It also forces\n> +\tany commit hold by the branch to be dropped, unless the\n> +\tcommit is also part of any other branch too. You may\n> +\ttherefore loose some of your data.\n\nAside from typo on \"lose\" (not \"loose\") and \"held\" (not \"hold\"),\nthis paragraph does not seem to add much value, at least to me, and\nI suspect that it makes things even more confusing to new readers.\n\n * Repointing the branch tip to a different commit is not limited to\n \"git switch -C\". Any commands that allow you to move the branch\n tip, like \"git branch -f\", \"git checkout -B\", \"git push --force\",\n \"git reset\", share the same property and singling \"switch -C\" out\n gives a false impression that all other commands are OK.\n\n * \"to be dropped\" is unnecessarily alarming (and not even correct).\n \"gc\" will not reclaim while the reflog entries hold onto them.\n\n \"Some commits that used to be reachable from the original branch\n tip may become unreachable.\" would not be an incorrect\n description per-se (and would be a vast improvement over what is\n in the posted patch), but it is dubious to stress the obvious,\n especially given that the whole point of \"branch -f\" is to make\n wrong commits disappear by pointing at corrected commits with the\n branch tip.\n\nBecause \"switch -c \", unlike \"switch \"\nwould not have to touch the working tree at all, the only reason why\nthe user has to force the operation by using \"-C\" is to override the\nsafety offered by \"-c\" that protects existing branches from accidental\noverwriting. Perhaps adding some description on \"why\" -c prevents\nan existing branch from being overwritten would help reduce the\nconfusion better than an additional warning on \"-C\"?\n\nThanks.\n"},{"id":"428770","messageId":"b667ca37-b3cb-fce2-a298-63c3b839089d@mfriebe.de","threadId":"56027","inReplyTo":"xmqqk0mcy6g2.fsf@gitster.g","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-06-29T19:04:10Z","receivedAt":"2021-06-29T19:04:22Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"I'll redo the patch, when we got a better text....\n\nOn 29/06/2021 18:35, Junio C Hamano wrote:\n> Martin writes:\n>\n>> \tSimilar to `--create` except that if `` already\n>> -\texists, it will be reset to ``. This is a\n>> -\tconvenient shortcut for:\n>> +\texists, it will be reset to ``.\n>> +\tThis forces the branch to the new location.\n> I would have written \"This forces the branch to point at a different\n> commit\", as we do not have to use a fuzzy word \"location\" in this\n> context (is it a location in the directory structure in the working\n> tree? is it a location in the history dag? is it a location in\n> some other dimension?).\nOk.\n\n> Up to this point, it makes sense.\n>\n>> + It also forces\n>> +\tany commit hold by the branch to be dropped, unless the\n>> +\tcommit is also part of any other branch too. You may\n>> +\ttherefore loose some of your data.\n> Aside from typo on \"lose\" (not \"loose\") and \"held\" (not \"hold\"),\n> this paragraph does not seem to add much value, at least to me, and\n> I suspect that it makes things even more confusing to new readers.\n>\n> * Repointing the branch tip to a different commit is not limited to\n> \"git switch -C\". Any commands that allow you to move the branch\n> tip, like \"git branch -f\", \"git checkout -B\", \"git push --force\",\n> \"git reset\", share the same property and singling \"switch -C\" out\n> gives a false impression that all other commands are OK.\nWell, yes. There may be more doc pages that could be updated. But that \nshould not stop us\nfrom starting at some point.\nI chose \"git switch\", because as I understand it, it was made in an \neffort to make git\neasier to use (by distinguishing between the clumped together commands \nthat were\nall done with \"git checkout\")\nIn that sense, I see \"git switch\" as a particular important improvement \nfor people new\nto git. Hence I felt that its documentation needed the extra bit of \nattention.\n\n> * \"to be dropped\" is unnecessarily alarming (and not even correct).\n> \"gc\" will not reclaim while the reflog entries hold onto them.\n>\n> \"Some commits that used to be reachable from the original branch\n> tip may become unreachable.\" would not be an incorrect\n> description per-se (and would be a vast improvement over what is\n> in the posted patch), but it is dubious to stress the obvious,\n> especially given that the whole point of \"branch -f\" is to make\n> wrong commits disappear by pointing at corrected commits with the\n> branch tip.\nMy text may indeed have lacked clarity. I was trying to emphasize to \nhard, that this\ncommand's \"force\" enables 2 actions that may both not be wanted. Usually \nif one applies\n\"force\" to a command only one such action is expected, or at least I \nwould only expect the one.\nThe actions being, giving up the link to the commit that is the tip of \nthe branch; and\nmaking commits unreachable.  (for an expert in git tightly linked \ntogether, but not for everyone)\n\nBecause you already need force, just to give up link to the tip, it is \nnot clear that there\nmight be additional unwanted actions that are enabled with the same \"force\".\n(And the \"unreachable commits\" do not always happen, which makes it even\nmore dangerous, as a user may misjudge if it applies to his current case \n/ I started\nanother mail on that too).\n\nIn general the direction of your proposed text is ok for me. But I \nhighly doubt that a user\nwho is new to git, will understand \"reachable\" without further context.\nMaybe\n    \" As a result some commits may be removed from the reachable part\n      of the repository and will be scheduled to be purged (see reflog \ndocumentation)\"\n\nor\n    \" As a result some commits may no longer be in a reachable part\n      of the repository and will be scheduled to be purged (see reflog \ndocumentation)\"\n\nIt is the same \"reachable\" that you used (the reflog can be reached, but \none usually does not\nwant the reflog to be the only place from where to access data still needed)\n. It adds the word \"removed\" which most people (regardless of their git \nskill,\nor English skills) will recognize.\n\nThe intend is, that a new user should clearly take the message, those \ncommits will\n\"go away\" (even if they \"only\" go to the reflog)\n\n> Because \"switch -c \", unlike \"switch \"\n> would not have to touch the working tree at all, the only reason why\n> the user has to force the operation by using \"-C\" is to override the\n> safety offered by \"-c\" that protects existing branches from accidental\n> overwriting. Perhaps adding some description on \"why\" -c prevents\n> an existing branch from being overwritten would help reduce the\n> confusion better than an additional warning on \"-C\"?\n>\nWell, I am not convinced. The \"danger\" lies in the \"-C\" (which is why it \nis a \"force\" command).\nSo it should be explained there.\n\nIt could be explained as \"Unlike -c this does not protect your existing \nbranch\".\nBut the entire point is, that the user must be aware what happens when a \nbranch is\nremoved (before it is recreated).\n\nHowever the current documentation only mentions \"if || \nalready exists, it will be reset to \".\nThere is no explanation what \"reset\" means.\nThe doc does not even mention, the branch is ...\"re-created\" or \"removed \nand re-created\".\nNor does it mention that the newly (re-)created  branch is created \nwithout any of the commits that it contained.\n\nAll of this, is very obvious to you and me. But it's not that obvious \nfor new users (who relay on the\ndocs more than anyone else).\n\nBased on that, another approach to create clarity might be\n\n     Force creating a branch, means that an existing branch of the same \nname is removed.\n    And that a new branch is created at the specified . The \nnew branch will not\n    necessarily have all the commits of that the existing branch used to \nhave.\n    It therefore also means that commits from the old existing branch \nmay be no longer reachable.\n\nHere I think it can be left at \"no longer reachable\" as it already has \nbeen indicated, that the commits may no longer be on that branch.\nThe \"also means\" underlines that this is a second potentially unwanted \neffect of this command.\n\n\n"},{"id":"428786","messageId":"xmqqpmw4uwh2.fsf@gitster.g","threadId":"56027","inReplyTo":"b667ca37-b3cb-fce2-a298-63c3b839089d@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-06-29T22:39:21Z","receivedAt":"2021-06-29T22:39:29Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin writes:\n\n> My text may indeed have lacked clarity. I was trying to emphasize to\n> hard, that this\n> command's \"force\" enables 2 actions that may both not be\n> wanted. Usually if one applies\n> \"force\" to a command only one such action is expected, or at least I\n> would only expect the one.\n\nOh, I do agree wholeheartedly if two things are forced at the same\ntime, things can become confusing.\n\nBut the thing is, there are no such \"two things are forced at once\"\nin this case. That is why I emphasized, in my response to you, that\n\"switch -C \" does not touch working tree, so \"ok, the\nswitch stops because it requires some working tree files with\nchanges clobbered, and I can force it to make it happen\" is not\ninvolved. If it were, then it becomes fuzzy if --force is allowing\nan existing branch getting overwritten, or allowing a modification\nin a working tree file getting discarded, or both.\n\nThe one and only thing that is forced is to repoint the tip of an\nexisting branch.\n\n> The actions being, giving up the link to the commit that is the tip of\n> the branch; and\n> making commits unreachable.  (for an expert in git tightly linked\n> together, but not for everyone)\n\nSorry, I do not quite see how the removing the reference to a commit\n(i.e. the commit C that used to be pointed at by the branch would no\nlonger be pointed at by that branch---that is by definition what\nmoving the branch to point at a different commit means) and the\ncommit becoming not reachable from the reference (i.e. such a commit\nC may not be reachable from the branch---unless the new commit it\npoints at happens to be a descendant of C) are not one and the same\nthing. I do not think there is distinction between expert vs\neveryone else involved here at all.\n\nCan you give an example where one of the two holds while the other\none does not?\n\nThanks.\n"},{"id":"428811","messageId":"7870a0ad-8fa1-9dbd-1978-1f44ec6970c5@mfriebe.de","threadId":"56027","inReplyTo":"xmqqpmw4uwh2.fsf@gitster.g","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-06-30T08:50:06Z","receivedAt":"2021-06-30T08:50:15Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 30/06/2021 00:39, Junio C Hamano wrote:\n> Martin writes:\n>\n>> My text may indeed have lacked clarity. I was trying to emphasize to\n>> hard, that this\n>> command's \"force\" enables 2 actions that may both not be\n>> wanted. Usually if one applies\n>> \"force\" to a command only one such action is expected, or at least I\n>> would only expect the one.\n> Oh, I do agree wholeheartedly if two things are forced at the same\n> time, things can become confusing.\n>\n> But the thing is, there are no such \"two things are forced at once\"\n> in this case. That is why I emphasized, in my response to you, that\n> \"switch -C \" does not touch working tree, so \"ok, the\n> switch stops because it requires some working tree files with\n> changes clobbered, and I can force it to make it happen\" is not\n> involved. If it were, then it becomes fuzzy if --force is allowing\n> an existing branch getting overwritten, or allowing a modification\n> in a working tree file getting discarded, or both.\nWell, yes and no. IMHO.\n\n From what I have seen, there are main 2 cases people use -C.\n\n1) By accident, meaning to do something else. Most often meaning to do a \nrebase.\nI.e. some one who is new, desperately to fix \"branch has diverged\".\nFor this, those people need to be made aware that -C does not move the \ncommits.\n\n2) Intentional, when the branch to be re-created points to a commit, \nwhich is hold\n  by further branches. So no commit becomes unreachable.\nIn that case it is not a documentation issue. It is a, how can I enable \nthe re-create,\nbut have git warn me, if I somehow misjudged the situation and on other \nbranch\nhas the commit. That is, when I see this as 2 individually actions, out \nof which I want\nto allow only one. Anyway that is not documentation, and I did sent \nanother mail.\n\nAnd yes, for the documentation, it *should* be clear that, removing a \nbranch, removes the\ncommits on it.\nBut then it must be said, that the branch is first removed. That is not \ncurrently the case.\nI proposed an alternate text to that nature in my last mail.\n\nFor the rest, it is a matter of opinion.\nWhen I think a new user may read this, I believe such consequential \nimplications should\nbe mention rather explicit.\nBut, if your view (the view of the git team is) a new user should have \nread up far enough\nto be fully aware of those consequence, then so be it.\n\nAs per my previous mail, then maybe\n       Force creating a branch, means that an existing branch of the \nsame name is removed.\n      A new branch is created at the specified . The \nnew branch will not\n      necessarily have all the commits that the existing branch used to \nhave.\n\nBut without\n      It therefore also means that commits from the old existing branch \nmay be no longer reachable.\n\n>> The actions being, giving up the link to the commit that is the tip of\n>> the branch; and\n>> making commits unreachable.  (for an expert in git tightly linked\n>> together, but not for everyone)\n> Sorry, I do not quite see how the removing the reference to a commit\n> (i.e. the commit C that used to be pointed at by the branch would no\n> longer be pointed at by that branch---that is by definition what\n> moving the branch to point at a different commit means) and the\n> commit becoming not reachable from the reference (i.e. such a commit\n> C may not be reachable from the branch---unless the new commit it\n> points at happens to be a descendant of C) are not one and the same\n> thing. I do not think there is distinction between expert vs\n> everyone else involved here at all.\n>\n> Can you give an example where one of the two holds while the other\n> one does not?\n>\nWell, if one creates a new feature branch, and instead of forking of \nmaster, one forks of some\nrandom other branch. Then one can immediately re-create it at the \noriginal intended\nbranch point. No commits on the branch, none lost.\nBut teach that to a newbie, and they may have committed to the branch, \nbefore they\nrealize they forked at the wrong point. If the then do -C those commit \nwill be gone. (well, yes the reflog).\n\nPersonally (that may not be a common pattern), I have used two branches \nfor one feature\nbranch. One that holds the tip, and represents my local work.\nOne that I move forward and backward on the branch, to run tests, and \ndecide what\nI already want to push. Forward could be done by ff-merge, but backward \nnot (it's reset, or switch -C).\n\n---------\nAbout your comment on changes in the worktree.\nIn none of my examples do I have any changes in my worktree.\n\nI know that when I just try to switch a branch, git switch will refuse \nto overwrite my changes.\nThe doc for the -C section does not say if it will.\nThat is something I actually would still need to check, and if -C in \naddition to forcing the branch,\nand consequently but only in some cases \"making commits unreachable\", \ndoes also\noverwrite working dir changes that would be yet one more \"forced\" action.\nThat again not everyone may automatically be aware off.\n\n"},{"id":"428859","messageId":"xmqqy2arrmba.fsf@gitster.g","threadId":"56027","inReplyTo":"7870a0ad-8fa1-9dbd-1978-1f44ec6970c5@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-06-30T22:59:21Z","receivedAt":"2021-06-30T22:59:25Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin writes:\n\n> And yes, for the documentation, it *should* be clear that, removing a\n> branch, removes the\n> commits on it.\n> But then it must be said, that the branch is first removed. That is\n> not currently the case.\n\nSorry, but I still do not see how it makes any difference if the\nbranch is first removed and then made to point at somewhere else, or\nthe branch gets just moved without any explicit or impolicit\nremoval. A branch cannot point at two different commits at the same\ntime, so the end result is that the commit at the old tip is no\nlonger pointed at by the branch after the update. In other words,\n\n\t----o---o---X---Y---Z\n\nif it were possible to move the tip of a branch, that used to point\nat commit Z, so that it points at commit X in the above picture,\nwithout making it *not* to point at Z, then I would understand your\nexplanation, but I do not see how it would be possible.\n"},{"id":"428863","messageId":"CAOjrSZuoD5-5FeRXmFPbRxFptyv_x-G3quFqCptvCX_XY9mSyw@mail.gmail.com","threadId":"56027","inReplyTo":"7870a0ad-8fa1-9dbd-1978-1f44ec6970c5@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Matt Rogers","fromEmail":"mattr94@gmail.com","sentAt":"2021-07-01T00:06:47Z","receivedAt":"2021-07-01T00:07:02Z","isPatch":false,"sender":{"key":"mattr94@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5719846?v=4"},"body":"On Wed, Jun 30, 2021 at 4:50 AM Martin wrote:\n>\n> On 30/06/2021 00:39, Junio C Hamano wrote:\n> > Martin writes:\n> >\n> >> My text may indeed have lacked clarity. I was trying to emphasize to\n> >> hard, that this\n> >> command's \"force\" enables 2 actions that may both not be\n> >> wanted. Usually if one applies\n> >> \"force\" to a command only one such action is expected, or at least I\n> >> would only expect the one.\n> > Oh, I do agree wholeheartedly if two things are forced at the same\n> > time, things can become confusing.\n> >\n> > But the thing is, there are no such \"two things are forced at once\"\n> > in this case. That is why I emphasized, in my response to you, that\n> > \"switch -C \" does not touch working tree, so \"ok, the\n> > switch stops because it requires some working tree files with\n> > changes clobbered, and I can force it to make it happen\" is not\n> > involved. If it were, then it becomes fuzzy if --force is allowing\n> > an existing branch getting overwritten, or allowing a modification\n> > in a working tree file getting discarded, or both.\n> Well, yes and no. IMHO.\n>\n> From what I have seen, there are main 2 cases people use -C.\n>\n> 1) By accident, meaning to do something else. Most often meaning to do a\n> rebase.\n> I.e. some one who is new, desperately to fix \"branch has diverged\".\n> For this, those people need to be made aware that -C does not move the\n> commits.\n>\n> 2) Intentional, when the branch to be re-created points to a commit,\n> which is hold\n> by further branches. So no commit becomes unreachable.\n> In that case it is not a documentation issue. It is a, how can I enable\n> the re-create,\n> but have git warn me, if I somehow misjudged the situation and on other\n> branch\n> has the commit. That is, when I see this as 2 individually actions, out\n> of which I want\n> to allow only one. Anyway that is not documentation, and I did sent\n> another mail.\n>\n\nI just want to point out that my usual use-case for using -C (or checkout -f,\nbut the usage is similar enough for this discussion) is when I want to create\na temporary branch with a generic name (e.g. tmp) and I haven't cleaned\nout my unused branches in a while. If I find myself having branched off the\nwrong commit and wanting to move work I already committed, the user should\nbe looking to use either rebase or merge for that.\n\nI would also consider that using a command literally called \"switch\n--force-create\"\ndoes not seem like the obvious first choice for \"My history is\ndifferent than that\nhistory\".\n\n\n\n> And yes, for the documentation, it *should* be clear that, removing a\n> branch, removes the\n> commits on it.\n> But then it must be said, that the branch is first removed. That is not\n> currently the case.\n> I proposed an alternate text to that nature in my last mail.\n>\n> For the rest, it is a matter of opinion.\n> When I think a new user may read this, I believe such consequential\n> implications should\n> be mention rather explicit.\n> But, if your view (the view of the git team is) a new user should have\n> read up far enough\n> to be fully aware of those consequence, then so be it.\n>\n> As per my previous mail, then maybe\n> Force creating a branch, means that an existing branch of the\n> same name is removed.\n> A new branch is created at the specified . The\n> new branch will not\n> necessarily have all the commits that the existing branch used to\n> have.\n>\n\nI think the current documentations usage of \"reset\" in\n\n Similar to --create except that if already exists, it\nwill be reset to .\n\nIs pretty clear about what happens, although it does rely on users\nbeing familiar\nwith the semantics of \"resetting\" a la git reset. I think rephrasing\nit in terms of\nbranch removal/creation actually obfuscates the matter.\n\n\n> Well, if one creates a new feature branch, and instead of forking of\n> master, one forks of some\n> random other branch. Then one can immediately re-create it at the\n> original intended\n> branch point. No commits on the branch, none lost.\n> But teach that to a newbie, and they may have committed to the branch,\n> before they\n> realize they forked at the wrong point. If the then do -C those commit\n> will be gone. (well, yes the reflog).\n>\n\nI don't think that this is a great usage of switch -C. generally I teach people\nto look at the state of their repository via `git log --graph\n--oneline --all` and then\ndecide whether they need to rebase their work or if they can just reset onto the\nbranch they want to.\n\n\n-- \nMatthew Rogers\n"},{"id":"428878","messageId":"b80bf908-0c31-2b3a-6d6c-1a3fba5b2334@mfriebe.de","threadId":"56027","inReplyTo":"xmqqy2arrmba.fsf@gitster.g","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-01T10:06:17Z","receivedAt":"2021-07-01T10:06:23Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 01/07/2021 00:59, Junio C Hamano wrote:\n> Martin writes:\n>\n>> And yes, for the documentation, it *should* be clear that, removing a\n>> branch, removes the\n>> commits on it.\n>> But then it must be said, that the branch is first removed. That is\n>> not currently the case.\n> Sorry, but I still do not see how it makes any difference if the\n> branch is first removed and then made to point at somewhere else, or\n> the branch gets just moved without any explicit or impolicit\n> removal. A branch cannot point at two different commits at the same\n> time, so the end result is that the commit at the old tip is no\n> longer pointed at by the branch after the update.\n\nWell all very obvious, if you know git well.\n\nLet's take a step back. How exactly is the word \"branch\" actually \ndefined? Well it does not matter.\nWhat matters is, how the word is used.\nWhat does a person mean, when they speak of the branch?\n\nAnd the answer is, it's not always clear.\n\nIn the above conversation, we use \"branch\" to speak of the \"pointer to a \nsingle commit\".\nWe do not include any commits, when speaking of the \"branch\".\n(And this is how it is used in the docs, as far as I can find)\n\nHowever a lot of people use \"branch\" to refer to the commits within.\n\"Push a branch to a remote\". That obviously means the objects (e.g. \ncommits) in the branch.\nThe doc says (and yes I am getting a bit picky here)\n >>> Updates remote refs using local refs, while sending objects \nnecessary to complete the given refs.\n\"complete the given ref\". The ref is given by the branch, and completing \nmeans afaik \"to make something part of\"\nMaybe a mistake made, because \"branch\" is (according to my observation) \nso commonly (mis-)used to include the objects.\n\nAnyway, can we agree, that there are people who  (mistakenly) \nuse/understand \"branch\" as including the objects?\nEnough people to call it a \"common mistake\".\nIf so, then we should not ignore this.\n\nWith this use of \"branch\" in mind, (re-)creating an existing  branch on \na new startpoint,\ndoes to the inexperienced user read like a rebase. It recreates all the \ncommits.\nThe fact that as an experienced user, I shake my head in disbelief, does \nnot change this.\n\nBut true, my attempt on adding \"the old branch is removed\" does not either.\nSo not sure which wording will do best.\nProbably\n        \"Creates a new empty branch at \"\n\nEven though \"empty\" may be a sloppy usage too....\n\n\nThe other problem with the current doc is\n\n> On 01/07/2021 02:06, Matt Rogers wrote:\n>> I think the current documentations usage of \"reset\" in\n>>\n>> Similar to --create except that if already exists, it\n>> will be reset to .\n>>\n>> Is pretty clear about what happens, although it does rely on users\n>> being familiar\n>> with the semantics of \"resetting\" a la git reset.\n>\nNot everyone is \"familiar\" with reset.\nAnd if you look up reset, you are left alone if that is a --soft or \n--hard or --mixed.\n\nIn any case, while it is ok, to refer to other parts of the doc, it \nshould still be possible\nto read just the current doc, and get a full understanding of the command.\n\nSo a short addition to the current doc, that explains \"reset\" should be \nadded.\n\nI currently am out of ideas how to word it, other than based on my \nprevious ideas.\n\nBut as in the first part of this mail, maybe just add the \"empty\" to the \nexisting doc?\nSo the existing\n    \"it will be reset to ||. \"\nchanges to\n    \"it will be reset to [become] an empty branch at ||. \"\n\nHappy for any idea, how the reader can be reminded, that \"branch\" is the \npointer only, and excludes any objects that it refers to.\n\nI was just about to write \"any objects in it (in the branch)\". But as \nestablished the objects are not part, therefore not \"in it\"...\nJust how easy it is to think of branch as more than it is.\n\n"},{"id":"428886","messageId":"87wnqaclz8.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"b80bf908-0c31-2b3a-6d6c-1a3fba5b2334@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-01T11:27:55Z","receivedAt":"2021-07-01T11:28:01Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Martin writes:\n\n> On 01/07/2021 00:59, Junio C Hamano wrote:\n>> Martin writes:\n>>\n>>> And yes, for the documentation, it *should* be clear that, removing a\n>>> branch, removes the\n>>> commits on it.\n>>> But then it must be said, that the branch is first removed. That is\n>>> not currently the case.\n>> Sorry, but I still do not see how it makes any difference if the\n>> branch is first removed and then made to point at somewhere else, or\n>> the branch gets just moved without any explicit or impolicit\n>> removal. A branch cannot point at two different commits at the same\n>> time, so the end result is that the commit at the old tip is no\n>> longer pointed at by the branch after the update.\n>\n> Well all very obvious, if you know git well.\n>\n> Let's take a step back. How exactly is the word \"branch\" actually defined? Well it does not matter.\n> What matters is, how the word is used.\n> What does a person mean, when they speak of the branch?\n>\n> And the answer is, it's not always clear.\n\nYep. The \"branch\" may mean a \"chain of commits\" or a \"symbolic reference\nto the tip of the branch\", or even both, depending on the context.\n\nIt's somewhat similar to \"file\" vs \"file name\" in UNIX. You in fact\ndon't remove files in UNIX, you remove file names that refer to files\n(entities on disk), yet \"remove file\" and \"rename file\" are often\nused, even though they are not technically correct.\n\nTo me it's essential feature of Git that when you, say, \"remove branch\",\nyou only delete the symbolic reference, not any chain of commits, and\ndocumentation should not contradict this where it uses the term\n\"branch\".\n\n>\n> In the above conversation, we use \"branch\" to speak of the \"pointer to a single commit\".\n> We do not include any commits, when speaking of the \"branch\".\n> (And this is how it is used in the docs, as far as I can find)\n>\n> However a lot of people use \"branch\" to refer to the commits within.\n> \"Push a branch to a remote\". That obviously means the objects (e.g. commits) in the branch.\n> The doc says (and yes I am getting a bit picky here)\n>>>> Updates remote refs using local refs, while sending objects necessary to complete the given refs.\n> \"complete the given ref\". The ref is given by the branch, and\n> completing means afaik \"to make something part of\"\n> Maybe a mistake made, because \"branch\" is (according to my\n> observation) so commonly (mis-)used to include the objects.\n>\n> Anyway, can we agree, that there are people who  (mistakenly)\n> use/understand \"branch\" as including the objects?\n> Enough people to call it a \"common mistake\".\n> If so, then we should not ignore this.\n\nI don't see this as a mistake. A branch is a chain of commits. It's just\nusing of short term \"branch\" without further clarification that could\nlead to confusion.\n\n>\n> With this use of \"branch\" in mind, (re-)creating an existing  branch\n> on a new startpoint, does to the inexperienced user read like a\n> rebase. It recreates all the commits. The fact that as an experienced\n> user, I shake my head in disbelief, does not change this.\n\nSome understanding of underlying Git model is inevitable here. I'd\nsuggest to use \"branch name\" and other means to disambiguate description\ninstead of trying to describe what happens using wrong underlying model.\n\n>\n> But true, my attempt on adding \"the old branch is removed\" does not either.\n> So not sure which wording will do best.\n> Probably\n>        \"Creates a new empty branch at \"\n>\n> Even though \"empty\" may be a sloppy usage too....\n>\n\nYes, it's sloppy. There are no empty branches from Git point of view, so\nthis is not an option for proper documentation. Any branch has at least\none commit, the one the branch name is pointing at. It's entirely user\ninterpretation how many of the commits from the chain the Git branch has\nthey consider their branch \"contains\".\n\nOverall, if we aim at clear documentation, we need to define our\ndocumentation terms as precise as possible, and then use them\nconsistently.\n\nFor example:\n\n\"branch\": a chain of commits\n\n\"branch tip\": the most recent commit in a branch\n\n\"branch name\": specific type of symbolic reference pointing to a branch tip\n\nIt's then up to the user to learn a few simple basics required for\nproper understanding of documentation and behavior.\n\nThanks,\n\n-- \nSergey Organov\n"},{"id":"428938","messageId":"xmqqh7hersgp.fsf@gitster.g","threadId":"56027","inReplyTo":"b80bf908-0c31-2b3a-6d6c-1a3fba5b2334@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-07-01T14:58:46Z","receivedAt":"2021-07-01T14:58:50Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin writes:\n\n> Anyway, can we agree, that there are people who (mistakenly)\n> use/understand \"branch\" as including the objects?\n> Enough people to call it a \"common mistake\".\n> If so, then we should not ignore this.\n\nI do not think it is a mistake at all. In a history where the\nbranch B points at commit Z, we do say the branch contains commits Z\nand Y and we do say the branch does not contain commits X or W, for\nexample.\n\n W---X\n /\n ---o---V---Y---Z\n ^ we're here (branch B)\n\nThis is even true if the user is not yet familiar with the\n\"snapshots\" view of the world (which is based on \"the objects\"), but\nhas the \"changes\" view of the world. The branch has the change that\ntook Y to Z and the change that took V to Y, but it does not have\nthe change that took W to X or the change that took V to W.\n\n> With this use of \"branch\" in mind, (re-)creating an existing\n> branch on a new startpoint, does to the inexperienced user read\n> like a rebase. It recreates all the commits.\n\nIf I understand you correctly, the confusion your hypothetical\nnewbie would have is caused by the word \"start-point\" in \n\n\tgit branch -f \n\nThat is, if we repoint the branch that is currently at Z to point at\nX with \"git branch -f B X\", it is possible to imagine that we build\nmore history on top of \"X\" simply because \"X\" is called \"start-point\",\ni.e. we start at X and do something more.\n\nAnd _your_ particular hypothetical user would imagine that that\nsomething more is to replay Y and Z on top.\n\nBut I find two problems with the proposed solution to solve that\nconfusion.\n\n * Replaying Y and Z on top of X is not the only possible way to\n build \"more\" history on top of \"start-point\" that is X. It is,\n for example, entirely plausible to look at the remote-tracking\n branch of B and rebuild the history missing from there on top of\n X, just like your version of confusion rebuilt the history\n missing from the tip of old B on top of X. Saying \"Z and Y will\n not be replayed on top of X after resetting the tip of the branch\n to X\" may help _your_ version of confusion, but not other\n confusion.\n\n * In general, when an explanation in the documentation says that\n a command does A, it shouldn't have to say \"the command does A\n but does not do B or C on top of that\".\n\nI think the source of the confusion is the . It does\nnot change what the explanation wants to say at all if we changed\nit to . It is where the branch's tip ends up to be after\n\"git branch -f\" (or \"git switch -C\") finishes, so it might even be\ntechnically more correct.\n\nThe only reason why we use is purely historical. We\nused that phrase from the very beginning. The explanation did not\nconsider the use of \"gir branch -f\" is the *end* of the world. It\nintended the user to use \"gir branch [-f]\" to start or restart a\nbranch as the first step of many other things the user will do to\nbuild a history on the branch, and that is the reason why the word\n\"start\" is used.\n\nPerhaps along the lines of the attached patch would be an\nimprovement without adding \"we do not do B, we do not do C, we do\nnot do anything else we do not say we do in this documentation\".\n\nNote that the following is *not* meant to be a full illustration;\nthere are many leftover in these pages after this\npatch gets applied that need to be adjusted, if we were to go this\nroute.\n\n Documentation/git-branch.txt | 4 ++--\n Documentation/git-switch.txt | 14 +++++++-------\n 2 files changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git c/Documentation/git-branch.txt w/Documentation/git-branch.txt\nindex 94dc9a54f2..5e6a32da04 100644\n--- c/Documentation/git-branch.txt\n+++ w/Documentation/git-branch.txt\n@@ -16,7 +16,7 @@ SYNOPSIS\n \t[--points-at ] [--format=]\n \t[(-r | --remotes) | (-a | --all)]\n \t[--list] [...]\n-'git branch' [--track | --no-track] [-f] []\n+'git branch' [--track | --no-track] [-f] []\n 'git branch' (--set-upstream-to= | -u ) []\n 'git branch' --unset-upstream []\n 'git branch' (-m | -M) [] \n@@ -115,7 +115,7 @@ OPTIONS\n \n -f::\n --force::\n-\tReset to , even if exists\n+\tReset to , even if exists\n \talready. Without `-f`, 'git branch' refuses to change an existing branch.\n \tIn combination with `-d` (or `--delete`), allow deleting the\n \tbranch irrespective of its merged status. In combination with\ndiff --git c/Documentation/git-switch.txt w/Documentation/git-switch.txt\nindex 5c438cd505..c8ea86d385 100644\n--- c/Documentation/git-switch.txt\n+++ w/Documentation/git-switch.txt\n@@ -9,8 +9,8 @@ SYNOPSIS\n --------\n [verse]\n 'git switch' [] [--no-guess] \n-'git switch' [] --detach []\n-'git switch' [] (-c|-C) []\n+'git switch' [] --detach []\n+'git switch' [] (-c|-C) []\n 'git switch' [] --orphan \n \n DESCRIPTION\n@@ -39,9 +39,9 @@ OPTIONS\n ::\n \tName for the new branch.\n \n-::\n-\tThe starting point for the new branch. Specifying a\n-\t`` allows you to create a branch based on some\n+::\n+\tThe commit pointed at by the new branch. Specifying a\n+\t`` allows you to create a branch based on some\n \tother point in history than where HEAD currently points. (Or,\n \tin the case of `--detach`, allows you to inspect and detach\n \tfrom some other point.)\n@@ -59,7 +59,7 @@ out at most one of `A` and `B`, in which case it defaults to `HEAD`.\n -c ::\n --create ::\n \tCreate a new branch named `` starting at\n-\t`` before switching to the branch. This is a\n+\t`` before switching to the branch. This is a\n \tconvenient shortcut for:\n +\n ------------\n@@ -70,7 +70,7 @@ $ git switch \n -C ::\n --force-create ::\n \tSimilar to `--create` except that if `` already\n-\texists, it will be reset to ``. This is a\n+\texists, it will be reset to ``. This is a\n \tconvenient shortcut for:\n +\n ------------\n"},{"id":"428973","messageId":"167b8fe6-0586-b980-dfb9-9fa3a29d48bb@mfriebe.de","threadId":"56027","inReplyTo":"xmqqh7hersgp.fsf@gitster.g","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-01T17:29:06Z","receivedAt":"2021-07-01T17:29:12Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 01/07/2021 16:58, Junio C Hamano wrote:\n> If I understand you correctly, the confusion your hypothetical\n> newbie would have is caused by the word \"start-point\" in\n>\n> \tgit branch -f \n>\n> That is, if we repoint the branch that is currently at Z to point at\n> X with \"git branch -f B X\", it is possible to imagine that we build\n> more history on top of \"X\" simply because \"X\" is called \"start-point\",\n> i.e. we start at X and do something more.\nIt is probably more the use of the word \"branch\" than it is \"start point\"\n\nSergey made an excellent point:\n> On 01/07/2021 13:27, Sergey Organov wrote:\n>> For example:\n>>\n>> \"branch\": a chain of commits\n>>\n>> \"branch tip\": the most recent commit in a branch\n>>\n>> \"branch name\": specific type of symbolic reference pointing to a branch tip\n\nA lot of people think of the \"chain of commits\" when the word \"branch\" \nis used.\n\nIf we take the sentence from the current doc:\n    --force-create\n     Similar to |--create| except that if || already exists, \nit will be reset to ||\nand replace \"branch\" with \"chain of commits\"\n     Similar to |--create| except that if || \nalready exists, it will be reset to ||\n\nWhat would you expect to happen?\nI would think the \"chain of commits\" is created at the new \n\nWhat we want to say is\n     The \"branch name\" will point to a new \"branch tip\" at \n\nHowever, this still leaves the point, that new users need to understand \ncertain concepts and implications.\nSuch as moving a \"branch name\" abandons the old \"chain of commits\" (they \ndo not follow).\n\"branch name\" helps to remember that distinction, but it still needs to \nbe learned first.\n\"abandon\" => leave them to the reflog until expiry.\n\nThe point is, that those concepts (difference between branchname, and \ncommits in branch) may all be documented.\nBut the reader may still be learning all this.\nThen it will certainly help new users to learn , if the consequences of \nthose are mentioned in places like \"switch -C\".\n\n\n> But I find two problems with the proposed solution to solve that\n> confusion.\n> * In general, when an explanation in the documentation says that\n> a command does A, it shouldn't have to say \"the command does A\n> but does not do B or C on top of that\".\nOk, that make sense. In general \"negative\" statements are not helpful.\n\n\n\n> I think the source of the confusion is the . It does\n> not change what the explanation wants to say at all if we changed\n> it to .\nI don't actually see as the issue. But if it was then would mean\nthat your existing \"chain of commits\" would end there (as if it was a \nmerge).\n\n\n> It is where the branch's tip ends up to be after\n> \"git branch -f\" (or \"git switch -C\") finishes, so it might even be\n> technically more correct.\nBut it is also where new commits for that branch will start. (they start \nat the current end, but that is confusing...)\nThinking about the name would be more meaningful?\n\nIMHO, start is way better than end. But \"fork\" is good too.\n\nWhile going through the patch, I just noted\n\n\"git branch\" uses \n\"git switch\" uses \n\nIt would be (a tiny) improvement, if \"git switch\" also used \n1)  it does help to get away from  \"chain of commits\"\n2)  in case of -C the \"new\" part is actually wrong.\n\nUsing instead of is better too.\nNot so much for the above reasons.\n  described the function. But it did not tell you that you \nneed a \nNow you know you need a , and then you can check the function \nfrom the doc.\n\n\n> ------------\n> @@ -70,7 +70,7 @@ $ git switch \n> -C ::\n> --force-create ::\n> \tSimilar to `--create` except that if `` already\n> -\texists, it will be reset to ``. This is a\n> +\texists, it will be reset to ``. This is a\n> \tconvenient shortcut for:\n> +\n> ------------\n\nNow with that would be\n\n --force-create ::\n \tSimilar to `--create` except that if `` already\n\texists, it will be reset to [point to] ``. This is a\n \tconvenient shortcut for:\n\nAt least, there would no longer be a word, that can be read as \"chain of \ncommits\"\nSo would be a definite improvement too.\n\nNot sure if  [point to]  should be inserted?\n\n\nI would still think, users should be somehow reminded of the implicit \nconsequences.\nUsers reading that part of the doc may still be in the progress of \nlearning all the concepts.\nIf nothing else, then maybe\n       The branch previously at [pointed to by] will/may no \nlonger be reachable.\nThat is, it is obviously no longer reachable by . But it may \nnot be reachable by anything else either (reflog excluded).\n\nHowever, adding any such \"reminder\" may be part of a more general \ndiscussion how verbose the documentation should be.\nI.e. as you wrote in an earlier email, why for \"switch\" but not for others.\nThe argument that \"switch\" is one of the more essential commands, may \nnot be enough.\n\n"},{"id":"428976","messageId":"874kdeapw3.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"167b8fe6-0586-b980-dfb9-9fa3a29d48bb@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-01T17:46:20Z","receivedAt":"2021-07-01T17:46:26Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Martin writes:\n\n> On 01/07/2021 16:58, Junio C Hamano wrote:\n>> If I understand you correctly, the confusion your hypothetical\n>> newbie would have is caused by the word \"start-point\" in\n>>\n>> \tgit branch -f \n>>\n>> That is, if we repoint the branch that is currently at Z to point at\n>> X with \"git branch -f B X\", it is possible to imagine that we build\n>> more history on top of \"X\" simply because \"X\" is called \"start-point\",\n>> i.e. we start at X and do something more.\n> It is probably more the use of the word \"branch\" than it is \"start point\"\n>\n> Sergey made an excellent point:\n>> On 01/07/2021 13:27, Sergey Organov wrote:\n>>> For example:\n>>>\n>>> \"branch\": a chain of commits\n>>>\n>>> \"branch tip\": the most recent commit in a branch\n>>>\n>>> \"branch name\": specific type of symbolic reference pointing to a branch tip\n>\n> A lot of people think of the \"chain of commits\" when the word \"branch\" is used.\n>\n> If we take the sentence from the current doc:\n>    --force-create\n>     Similar to |--create| except that if || already\n> exists, it will be reset to ||\n> and replace \"branch\" with \"chain of commits\"\n>     Similar to |--create| except that if ||\n> already exists, it will be reset to ||\n>\n> What would you expect to happen?\n> I would think the \"chain of commits\" is created at the new\n> \n\nI find current \"git switch\" documentation utterly confusing, even for\nexperienced user, let alone for a novice. I'm only afraid that it's not\nonly documentation, but the design as well.\n\n>\n> What we want to say is\n>     The \"branch name\" will point to a new \"branch tip\" at \n>\n> However, this still leaves the point, that new users need to\n> understand certain concepts and implications.\n> Such as moving a \"branch name\" abandons the old \"chain of commits\" (they do not follow).\n> \"branch name\" helps to remember that distinction, but it still needs to be learned first.\n> \"abandon\" => leave them to the reflog until expiry.\n\nNot necessarily. There could be other references left to this exact\ncommit. User doesn't need to be aware of reflog at this point at all.\n\n>\n> The point is, that those concepts (difference between branchname, and\n> commits in branch) may all be documented.\n> But the reader may still be learning all this.\n\nThere is no way around. Either they are expected to understand basics,\nor documentation will lie to them trying to be helpful, that'd only\ncreate even more confusion.\n\nThanks,\n\n-- \nSergey Organov\n"},{"id":"429431","messageId":"60e5ef1c1118_30143720837@natae.notmuch","threadId":"56027","inReplyTo":"b80bf908-0c31-2b3a-6d6c-1a3fba5b2334@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-07T18:14:52Z","receivedAt":"2021-07-07T18:15:01Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> Let's take a step back. How exactly is the word \"branch\" actually \n> defined? Well it does not matter.\n> What matters is, how the word is used.\n> What does a person mean, when they speak of the branch?\n\nThat is a good point.\n\n> And the answer is, it's not always clear.\n\nIndeed.\n\n> In the above conversation, we use \"branch\" to speak of the \"pointer to a \n> single commit\".\n> We do not include any commits, when speaking of the \"branch\".\n> (And this is how it is used in the docs, as far as I can find)\n\nThis is how the term \"branch\" is used in git lingo.\n\n> However a lot of people use \"branch\" to refer to the commits within.\n> \"Push a branch to a remote\". That obviously means the objects (e.g. \n> commits) in the branch.\n> The doc says (and yes I am getting a bit picky here)\n> >>> Updates remote refs using local refs, while sending objects \n> necessary to complete the given refs.\n> \"complete the given ref\". The ref is given by the branch, and completing \n> means afaik \"to make something part of\"\n> Maybe a mistake made, because \"branch\" is (according to my observation) \n> so commonly (mis-)used to include the objects.\n\nYes.\n\n> Anyway, can we agree, that there are people who  (mistakenly) \n> use/understand \"branch\" as including the objects?\n> Enough people to call it a \"common mistake\".\n> If so, then we should not ignore this.\n\nI wouldn't even call it a mistake.\n\nOther SCMs, like Mercrual, do use this second meaning: the branch is the\nspecific commits that constitute that branch.\n\nCan we really say user thinking that way is a mistake? I'm sure\nMercurial users would say git using the first notion is the a mistake.\n\n\nIt is a bigger mental load to be thinking in the two meanings at the\nsame time while writing the documentation, but if we really want to\nreach the vast majority of users we do need to consider that the user\nmight be thinking in terms of the second notion.\n\n-- \nFelipe Contreras"},{"id":"429432","messageId":"60e5f3981de5f_301437208bc@natae.notmuch","threadId":"56027","inReplyTo":"87wnqaclz8.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-07T18:34:00Z","receivedAt":"2021-07-07T18:34:04Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Sergey Organov wrote:\n> Martin writes:\n> > On 01/07/2021 00:59, Junio C Hamano wrote:\n> >> Martin writes:\n> >>\n> >>> And yes, for the documentation, it *should* be clear that, removing a\n> >>> branch, removes the\n> >>> commits on it.\n> >>> But then it must be said, that the branch is first removed. That is\n> >>> not currently the case.\n> >> Sorry, but I still do not see how it makes any difference if the\n> >> branch is first removed and then made to point at somewhere else, or\n> >> the branch gets just moved without any explicit or impolicit\n> >> removal. A branch cannot point at two different commits at the same\n> >> time, so the end result is that the commit at the old tip is no\n> >> longer pointed at by the branch after the update.\n> >\n> > Well all very obvious, if you know git well.\n> >\n> > Let's take a step back. How exactly is the word \"branch\" actually defined? Well it does not matter.\n> > What matters is, how the word is used.\n> > What does a person mean, when they speak of the branch?\n> >\n> > And the answer is, it's not always clear.\n> \n> Yep. The \"branch\" may mean a \"chain of commits\" or a \"symbolic reference\n> to the tip of the branch\", or even both, depending on the context.\n> \n> It's somewhat similar to \"file\" vs \"file name\" in UNIX. You in fact\n> don't remove files in UNIX, you remove file names that refer to files\n> (entities on disk), yet \"remove file\" and \"rename file\" are often\n> used, even though they are not technically correct.\n\nIt's not even specific to computers, it's semantics of identifiers.\n\nYou can say John is not a person, \"John\" is the *name* of a person, the\nperson is constituted by cells and so on.\n\nMost of the time it's not particularly useful to think on those terms,\nbut sometimes it useful in the sense that we can confidently say\n\"master\" is not a branch, is the name of a branch.\n\nIn Mercurial branches are more like commit labels, so it's easy to see\nthe difference between a branch (a collection of commits), and a branch\nname. In Git it's trickier because the branch is a pointer, and it\ndoesn't make much sense to think of a pointer without a name, but\nstrickly speaking they are different.\n\n> > But true, my attempt on adding \"the old branch is removed\" does not either.\n> > So not sure which wording will do best.\n> > Probably\n> >        \"Creates a new empty branch at \"\n> >\n> > Even though \"empty\" may be a sloppy usage too....\n> >\n> \n> Yes, it's sloppy. There are no empty branches from Git point of view, so\n> this is not an option for proper documentation. Any branch has at least\n> one commit, the one the branch name is pointing at. It's entirely user\n> interpretation how many of the commits from the chain the Git branch has\n> they consider their branch \"contains\".\n> \n> Overall, if we aim at clear documentation, we need to define our\n> documentation terms as precise as possible, and then use them\n> consistently.\n> \n> For example:\n> \n> \"branch\": a chain of commits\n> \n> \"branch tip\": the most recent commit in a branch\n> \n> \"branch name\": specific type of symbolic reference pointing to a branch tip\n\nCompletely agree on all three (although I would call it \"branch head\",\nnot \"branch tip\").\n\nSometimes we can use a shortcut and say \"master\" is a branch, as we do\nin everyday language when we say \"John\" is a person, but when we are\nstrict we have to remember what's behind that shortcut.\n\n\nSlightly related although a little bit off-topic is the fact the *only*\nthing Mercurial can do that Git can't is to find the branching point of\na branch [1] (I have really tried, it's truly not possible).\n\nThe *only* way it would be possible is by introducing a new concept:\n\"branch tail\". I did implement patches for that (you could reference to\nit with master@{tail}).\n\nIt is related to this topic because if we had a branch head, and a\nbranch tail, then you could not automatically assume the branch is the\nbranch head.\n\nSo even though most of the documentation currently conflates the two\nconcept, that doesn't mean the user does as well.\n\n[1] https://stackoverflow.com/questions/1527234/finding-a-branch-point-with-git\n\n-- \nFelipe Contreras"},{"id":"429433","messageId":"60e5f6cd6afa9_3014372088c@natae.notmuch","threadId":"56027","inReplyTo":"xmqqh7hersgp.fsf@gitster.g","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-07T18:47:41Z","receivedAt":"2021-07-07T18:47:45Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Martin writes:\n> \n> > Anyway, can we agree, that there are people who (mistakenly)\n> > use/understand \"branch\" as including the objects?\n> > Enough people to call it a \"common mistake\".\n> > If so, then we should not ignore this.\n> \n> I do not think it is a mistake at all. In a history where the\n> branch B points at commit Z, we do say the branch contains commits Z\n> and Y and we do say the branch does not contain commits X or W, for\n> example.\n> \n> W---X\n> /\n> ---o---V---Y---Z\n> ^ we're here (branch B)\n> \n\nThere's a difference between saying the branch *is* commits A, B, ... Y,\nZ, and the branch *contains* commits ...\n\nIn Git only the latter is true, because technically the branch is a\npointer. But in Mercurial both are true.\n\n> I think the source of the confusion is the . It does\n> not change what the explanation wants to say at all if we changed\n> it to . It is where the branch's tip ends up to be after\n> \"git branch -f\" (or \"git switch -C\") finishes, so it might even be\n> technically more correct.\n\nIndeed.\n\nHowever, there's a better alternative than \"end point\": head. Sure, the\nunfortunate naming of the current branch as HEAD makes this slightly\nconfusing, but that's really what it is.\n\nIf you change the branch head *everyone* understands the the branch\nitself is changed, and the commits that are part of the branch are\ndifferent.\n\n-- \nFelipe Contreras\n"},{"id":"429434","messageId":"60e5f86d8f907_30143720844@natae.notmuch","threadId":"56027","inReplyTo":"167b8fe6-0586-b980-dfb9-9fa3a29d48bb@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-07T18:54:37Z","receivedAt":"2021-07-07T18:54:43Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> Sergey made an excellent point:\n> > On 01/07/2021 13:27, Sergey Organov wrote:\n> >> For example:\n> >>\n> >> \"branch\": a chain of commits\n> >>\n> >> \"branch tip\": the most recent commit in a branch\n> >>\n> >> \"branch name\": specific type of symbolic reference pointing to a branch tip\n> \n> A lot of people think of the \"chain of commits\" when the word \"branch\" \n> is used.\n> \n> If we take the sentence from the current doc:\n>    --force-create\n>     Similar to |--create| except that if || already exists, \n> it will be reset to ||\n> and replace \"branch\" with \"chain of commits\"\n>     Similar to |--create| except that if || \n> already exists, it will be reset to ||\n> \n> What would you expect to happen?\n> I would think the \"chain of commits\" is created at the new \n> \n> What we want to say is\n>     The \"branch name\" will point to a new \"branch tip\" at \n\nWouldn't this achieve everything we want?\n\n The branch head will now point the new \n\n-- \nFelipe Contreras"},{"id":"429446","messageId":"87bl7d3l8r.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"60e5f3981de5f_301437208bc@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-07T20:46:44Z","receivedAt":"2021-07-07T20:46:50Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Felipe Contreras writes:\n\n> Sergey Organov wrote:\n>> Martin writes:\n>> > On 01/07/2021 00:59, Junio C Hamano wrote:\n>> >> Martin writes:\n>> >>\n>> >>> And yes, for the documentation, it *should* be clear that, removing a\n>> >>> branch, removes the\n>> >>> commits on it.\n>> >>> But then it must be said, that the branch is first removed. That is\n>> >>> not currently the case.\n>> >> Sorry, but I still do not see how it makes any difference if the\n>> >> branch is first removed and then made to point at somewhere else, or\n>> >> the branch gets just moved without any explicit or impolicit\n>> >> removal. A branch cannot point at two different commits at the same\n>> >> time, so the end result is that the commit at the old tip is no\n>> >> longer pointed at by the branch after the update.\n>> >\n>> > Well all very obvious, if you know git well.\n>> >\n>> > Let's take a step back. How exactly is the word \"branch\" actually\n>> > defined? Well it does not matter.\n>> > What matters is, how the word is used.\n>> > What does a person mean, when they speak of the branch?\n>> >\n>> > And the answer is, it's not always clear.\n>> \n>> Yep. The \"branch\" may mean a \"chain of commits\" or a \"symbolic reference\n>> to the tip of the branch\", or even both, depending on the context.\n>> \n>> It's somewhat similar to \"file\" vs \"file name\" in UNIX. You in fact\n>> don't remove files in UNIX, you remove file names that refer to files\n>> (entities on disk), yet \"remove file\" and \"rename file\" are often\n>> used, even though they are not technically correct.\n>\n> It's not even specific to computers, it's semantics of identifiers.\n>\n> You can say John is not a person, \"John\" is the *name* of a person, the\n> person is constituted by cells and so on.\n>\n> Most of the time it's not particularly useful to think on those terms,\n> but sometimes it useful in the sense that we can confidently say\n> \"master\" is not a branch, is the name of a branch.\n>\n> In Mercurial branches are more like commit labels, so it's easy to see\n> the difference between a branch (a collection of commits), and a branch\n> name. In Git it's trickier because the branch is a pointer, and it\n> doesn't make much sense to think of a pointer without a name, but\n> strickly speaking they are different.\n>\n>> > But true, my attempt on adding \"the old branch is removed\" does not either.\n>> > So not sure which wording will do best.\n>> > Probably\n>> >        \"Creates a new empty branch at \"\n>> >\n>> > Even though \"empty\" may be a sloppy usage too....\n>> >\n>> \n>> Yes, it's sloppy. There are no empty branches from Git point of view, so\n>> this is not an option for proper documentation. Any branch has at least\n>> one commit, the one the branch name is pointing at. It's entirely user\n>> interpretation how many of the commits from the chain the Git branch has\n>> they consider their branch \"contains\".\n>> \n>> Overall, if we aim at clear documentation, we need to define our\n>> documentation terms as precise as possible, and then use them\n>> consistently.\n>> \n>> For example:\n>> \n>> \"branch\": a chain of commits\n>> \n>> \"branch tip\": the most recent commit in a branch\n>> \n>> \"branch name\": specific type of symbolic reference pointing to a branch tip\n>\n> Completely agree on all three (although I would call it \"branch head\",\n> not \"branch tip\").\n\nI see why \"branch head\", as you later introduce \"branch tail\", but a\nbranch (of a plant) has no \"head\" (nor \"tail\"), right? BTW, how the base\nof a plant branch is called in English, and how one finds \"branch tail\"\non a real tree anyway? I mean, there are probably a few of them, at\nevery fork. In Git it's even more vague, as a branch could logically\nbegin at any place, not necessarily at a fork point.\n\nOTOH, \"head\" and \"tail\" are obviously taken from CS \"list\" concept, and,\nprovided \"chain\" == \"list\", it does make sense. And then we have 'HEAD'\nthat points to the current branch tip anyway.\n\nDunno, in fact I don't have any preference among \"tip\" and \"head\".\n\nAs for branch tail, I do have convention of marking start of a\nlong-standing branch with corresponding tag, where branch \"foo\" has\ncorresponding \"foo-bp\" tag marking its \"branch point\". Recently I\nstarted to mark start of feature branch with yet another branch \"foo-bp\"\nrather than tag, \"foo\" being set to track \"foo-bp\", that allows to\nautomate rebasing of \"foo\" against correct base.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429447","messageId":"60e61bbd7a37d_3030aa2081a@natae.notmuch","threadId":"56027","inReplyTo":"87bl7d3l8r.fsf@osv.gnss.ru","subject":"What actually is a branch?","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-07T21:25:17Z","receivedAt":"2021-07-07T21:25:39Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Since this is not strictly related to the topic of `git switch` I\nrenamed the thread.\n\nSergey Organov wrote:\n> Felipe Contreras writes:\n> > Sergey Organov wrote:\n\n> >> Overall, if we aim at clear documentation, we need to define our\n> >> documentation terms as precise as possible, and then use them\n> >> consistently.\n> >> \n> >> For example:\n> >> \n> >> \"branch\": a chain of commits\n> >> \n> >> \"branch tip\": the most recent commit in a branch\n> >> \n> >> \"branch name\": specific type of symbolic reference pointing to a branch tip\n> >\n> > Completely agree on all three (although I would call it \"branch head\",\n> > not \"branch tip\").\n> \n> I see why \"branch head\", as you later introduce \"branch tail\", but a\n> branch (of a plant) has no \"head\" (nor \"tail\"), right? BTW, how the base\n> of a plant branch is called in English, and how one finds \"branch tail\"\n> on a real tree anyway? I mean, there are probably a few of them, at\n> every fork. In Git it's even more vague, as a branch could logically\n> begin at any place, not necessarily at a fork point.\n\nWe don't necessarily need a 1-to-1 mapping with common English (although\nthat would be nice). Anoher option could be \"base\" and \"tip\".\n\n> OTOH, \"head\" and \"tail\" are obviously taken from CS \"list\" concept, and,\n> provided \"chain\" == \"list\", it does make sense.\n\nI took it from Mercurial, where the tip of a branch is called \"head\",\nand in fact a branch can have multiple heads.\n\n> And then we have 'HEAD' that points to the current branch tip anyway.\n\nIt actually points to a branch, or rather references a branch, since it\nuses the branch name.\n\n> Dunno, in fact I don't have any preference among \"tip\" and \"head\".\n\nI don't either, but from different sources (non-git-specific) I've heard\n\"head\" more often.\n\n> As for branch tail, I do have convention of marking start of a\n> long-standing branch with corresponding tag, where branch \"foo\" has\n> corresponding \"foo-bp\" tag marking its \"branch point\". Recently I\n> started to mark start of feature branch with yet another branch \"foo-bp\"\n> rather than tag, \"foo\" being set to track \"foo-bp\", that allows to\n> automate rebasing of \"foo\" against correct base.\n\nSo foo-bp is the upstream of foo, and you do basically:\n\n git rebase foo@{upstream}\n\nThis is works if your base (or tail, or whatever) is static, but many\nbranches jump around, and that's where @{tail} comes in handy.\n\nYou can do this:\n\n git rebase --onto foo@{upstream} foo@{tail}\n\nThis will always rebase the right commits (no need to look into the\nreflog). So you can say that the branch is foo@{tail}..foo.\n\nAnother advantage of having this notion is that `git rebase`\nautomatically updates the tail (in this case to foo@{upstream}).\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"429450","messageId":"877di13hhe.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"60e61bbd7a37d_3030aa2081a@natae.notmuch","subject":"Re: What actually is a branch?","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-07T22:07:57Z","receivedAt":"2021-07-07T22:10:51Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Felipe Contreras writes:\n\n> Since this is not strictly related to the topic of `git switch` I\n> renamed the thread.\n>\n> Sergey Organov wrote:\n>> Felipe Contreras writes:\n>> > Sergey Organov wrote:\n>\n>> >> Overall, if we aim at clear documentation, we need to define our\n>> >> documentation terms as precise as possible, and then use them\n>> >> consistently.\n>> >> \n>> >> For example:\n>> >> \n>> >> \"branch\": a chain of commits\n>> >> \n>> >> \"branch tip\": the most recent commit in a branch\n>> >> \n>> >> \"branch name\": specific type of symbolic reference pointing to a\n>> >> branch tip\n>> >\n>> > Completely agree on all three (although I would call it \"branch head\",\n>> > not \"branch tip\").\n>> \n>> I see why \"branch head\", as you later introduce \"branch tail\", but a\n>> branch (of a plant) has no \"head\" (nor \"tail\"), right? BTW, how the base\n>> of a plant branch is called in English, and how one finds \"branch tail\"\n>> on a real tree anyway? I mean, there are probably a few of them, at\n>> every fork. In Git it's even more vague, as a branch could logically\n>> begin at any place, not necessarily at a fork point.\n>\n> We don't necessarily need a 1-to-1 mapping with common English (although\n> that would be nice). Anoher option could be \"base\" and \"tip\".\n>\n>> OTOH, \"head\" and \"tail\" are obviously taken from CS \"list\" concept, and,\n>> provided \"chain\" == \"list\", it does make sense.\n>\n> I took it from Mercurial, where the tip of a branch is called \"head\",\n> and in fact a branch can have multiple heads.\n>\n>> And then we have 'HEAD' that points to the current branch tip anyway.\n>\n> It actually points to a branch, or rather references a branch, since it\n> uses the branch name.\n\nYes, but it still points to the branch tip, indirectly, or even\ndirectly, when in \"detached head\" state, that, by the way, I'd vote to\nabandon, replacing it with more user-friendly \"unnamed branch\" or\nsomething like that.\n\n>\n>> Dunno, in fact I don't have any preference among \"tip\" and \"head\".\n>\n> I don't either, but from different sources (non-git-specific) I've heard\n> \"head\" more often.\n>\n>> As for branch tail, I do have convention of marking start of a\n>> long-standing branch with corresponding tag, where branch \"foo\" has\n>> corresponding \"foo-bp\" tag marking its \"branch point\". Recently I\n>> started to mark start of feature branch with yet another branch \"foo-bp\"\n>> rather than tag, \"foo\" being set to track \"foo-bp\", that allows to\n>> automate rebasing of \"foo\" against correct base.\n>\n> So foo-bp is the upstream of foo, and you do basically:\n>\n> git rebase foo@{upstream}\n\nYep, but essential feature to me is that I in fact use tools that simply\nrun bare\n\n git rebase\n\nand that \"just works\" (tm).\n\n>\n> This is works if your base (or tail, or whatever) is static, but many\n> branches jump around, and that's where @{tail} comes in handy.\n\nYeah, I see. When I need to make a branch jump around, I do need to\nmanually move my references, but that's fortunately very rare use-case\nfor me. Having direct support for that is still a win.\n\n>\n> You can do this:\n>\n> git rebase --onto foo@{upstream} foo@{tail}\n>\n> This will always rebase the right commits (no need to look into the\n> reflog). So you can say that the branch is foo@{tail}..foo.\n\nI see where and when it's useful, but for a feature branch 99% of times\nI don't want to rebase it onto some true upstream. I rather want to just\nfiddle with the branch in place, and I prefer to setup things the way\nthat ensures that bare \"git rebase\" does \"the right thing\".\n\nProbably that could be solved by a branch-local configuration that makes\n\"git rebase\" become \"git rebase @{tail}\" for the branch instead of \"git\nrebase @{upstream}\"\n\n>\n> Another advantage of having this notion is that `git rebase`\n> automatically updates the tail (in this case to foo@{upstream}).\n\nYep, looks useful. Is it all local to given repo, or else?\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429453","messageId":"c740a4f0-011f-762e-4f49-f85d1b3abc99@mfriebe.de","threadId":"56027","inReplyTo":"877di13hhe.fsf@osv.gnss.ru","subject":"Re: What actually is a branch?","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-07T22:35:51Z","receivedAt":"2021-07-07T22:35:57Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 08/07/2021 00:07, Sergey Organov wrote:\n> Felipe Contreras writes:\n>>\n>> This is works if your base (or tail, or whatever) is static, but many\n>> branches jump around, and that's where @{tail} comes in handy.\n> \n> Yeah, I see. When I need to make a branch jump around, I do need to\n> manually move my references, but that's fortunately very rare use-case\n> for me. Having direct support for that is still a win.\n> \n>>\n>> You can do this:\n>>\n>> git rebase --onto foo@{upstream} foo@{tail}\n>>\n>> This will always rebase the right commits (no need to look into the\n>> reflog). So you can say that the branch is foo@{tail}..foo.\n> \n\nMaybe I am missing something, is tail for tracking branches only, or for \njust any branch?\n\nIf for any branch, looking at\n\n A => B => C => D master\n |\n \\ / => G => H branch_1\n => E => F\n \\ => I => J branch_2\n\nWhere is the base of branch_1 and branch_2?\n(and does it matter if they have an upstream)\n\nMaybe branch_1 diverged from Master, and then branch_2 from branch_1?\n\nMaybe the other way round.\n\nMaybe there was a branch_0 (that got removed),\nand branch_0 diverged from master, and branch_1 and branch_2 both from \nbranch_0?\n\n---\nAlso base may be misleading.\n\nIf head is the one end of the commit chains, then base should be the other.\nBut all branches contain commits A (and B). So the base would be A.\n\n\"fork\" would be more descriptive IMHO?\n\nAlso, if that is to save the user from looking up fork points, maybe \nextend the syntax\n branch_1@{fork:branch_2}\n branch_1@{fork:master}\n\nDepending on some of the answers to the above\n branch_1@{fork}\nnearest fork, or upstream fork?\n"},{"id":"429469","messageId":"60e66d28c0cb3_306ac120813@natae.notmuch","threadId":"56027","inReplyTo":"877di13hhe.fsf@osv.gnss.ru","subject":"Re: What actually is a branch?","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-08T03:12:40Z","receivedAt":"2021-07-08T03:12:46Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Sergey Organov wrote:\n> Felipe Contreras writes:\n> \n> > Since this is not strictly related to the topic of `git switch` I\n> > renamed the thread.\n> >\n> > Sergey Organov wrote:\n> >> Felipe Contreras writes:\n> >> > Sergey Organov wrote:\n> >\n> >> >> Overall, if we aim at clear documentation, we need to define our\n> >> >> documentation terms as precise as possible, and then use them\n> >> >> consistently.\n> >> >> \n> >> >> For example:\n> >> >> \n> >> >> \"branch\": a chain of commits\n> >> >> \n> >> >> \"branch tip\": the most recent commit in a branch\n> >> >> \n> >> >> \"branch name\": specific type of symbolic reference pointing to a\n> >> >> branch tip\n> >> >\n> >> > Completely agree on all three (although I would call it \"branch head\",\n> >> > not \"branch tip\").\n> >> \n> >> I see why \"branch head\", as you later introduce \"branch tail\", but a\n> >> branch (of a plant) has no \"head\" (nor \"tail\"), right? BTW, how the base\n> >> of a plant branch is called in English, and how one finds \"branch tail\"\n> >> on a real tree anyway? I mean, there are probably a few of them, at\n> >> every fork. In Git it's even more vague, as a branch could logically\n> >> begin at any place, not necessarily at a fork point.\n> >\n> > We don't necessarily need a 1-to-1 mapping with common English (although\n> > that would be nice). Anoher option could be \"base\" and \"tip\".\n> >\n> >> OTOH, \"head\" and \"tail\" are obviously taken from CS \"list\" concept, and,\n> >> provided \"chain\" == \"list\", it does make sense.\n> >\n> > I took it from Mercurial, where the tip of a branch is called \"head\",\n> > and in fact a branch can have multiple heads.\n> >\n> >> And then we have 'HEAD' that points to the current branch tip anyway.\n> >\n> > It actually points to a branch, or rather references a branch, since it\n> > uses the branch name.\n> \n> Yes, but it still points to the branch tip, indirectly, or even\n> directly, when in \"detached head\" state, that, by the way, I'd vote to\n> abandon, replacing it with more user-friendly \"unnamed branch\" or\n> something like that.\n\nYes, but most of the time it's indirectly.\n\n> >> Dunno, in fact I don't have any preference among \"tip\" and \"head\".\n> >\n> > I don't either, but from different sources (non-git-specific) I've heard\n> > \"head\" more often.\n> >\n> >> As for branch tail, I do have convention of marking start of a\n> >> long-standing branch with corresponding tag, where branch \"foo\" has\n> >> corresponding \"foo-bp\" tag marking its \"branch point\". Recently I\n> >> started to mark start of feature branch with yet another branch \"foo-bp\"\n> >> rather than tag, \"foo\" being set to track \"foo-bp\", that allows to\n> >> automate rebasing of \"foo\" against correct base.\n> >\n> > So foo-bp is the upstream of foo, and you do basically:\n> >\n> > git rebase foo@{upstream}\n> \n> Yep, but essential feature to me is that I in fact use tools that simply\n> run bare\n> \n> git rebase\n> \n> and that \"just works\" (tm).\n\nI typed the revision explicitly, but `git rebase` would work just fine.\n\n> > This is works if your base (or tail, or whatever) is static, but many\n> > branches jump around, and that's where @{tail} comes in handy.\n> \n> Yeah, I see. When I need to make a branch jump around, I do need to\n> manually move my references, but that's fortunately very rare use-case\n> for me. Having direct support for that is still a win.\n> \n> >\n> > You can do this:\n> >\n> > git rebase --onto foo@{upstream} foo@{tail}\n> >\n> > This will always rebase the right commits (no need to look into the\n> > reflog). So you can say that the branch is foo@{tail}..foo.\n> \n> I see where and when it's useful, but for a feature branch 99% of times\n> I don't want to rebase it onto some true upstream. I rather want to just\n> fiddle with the branch in place, and I prefer to setup things the way\n> that ensures that bare \"git rebase\" does \"the right thing\".\n\nBut that's precisely the point: when you do `git rebase` you don't have\nto type the base or --onto anymore. It's done automatically.\n\nNot just for your long-standing branches, but for *any* branch.\n\n> Probably that could be solved by a branch-local configuration that makes\n> \"git rebase\" become \"git rebase @{tail}\" for the branch instead of \"git\n> rebase @{upstream}\"\n\nNo. @{upstream} is where you want to rebase *to*, @{tail} is where you\nwant to rebase *from*.\n\nWhen you do:\n\n git rebase foo@{upstream}\n\nThis is basically the same as:\n\n git checkout foo@{upstream}^0\n git cherry-pick --right-only foo@{upstream}...foo\n\ngit is smart enough to figure out what commits are already part of\nfoo@{upstream}, and those are skipped, but at no point was any \"base\"\ncalculated (at least not from `git rebase`).\n\nMost of the time `git rebase` works fine, because there aren't too many\ncommits to figure out where they should go, but it's definitely not\nefficient, and there's many corner-cases (see a Linux kernel maintaner\nbaffled by what the hell `git rebase` is doing [1]).\n\n> > Another advantage of having this notion is that `git rebase`\n> > automatically updates the tail (in this case to foo@{upstream}).\n> \n> Yep, looks useful. Is it all local to given repo, or else?\n\nI implented it as 'refs/tails' (as opposed to 'refs/heads'), so it's\nlocal to a given repo, but could easily be exported.\n\n[1] https://lore.kernel.org/git/60b272ff6bfa4_265861208d6@natae.notmuch/\n\n-- \nFelipe Contreras\n"},{"id":"429470","messageId":"60e67389a4adc_306ac1208fd@natae.notmuch","threadId":"56027","inReplyTo":"c740a4f0-011f-762e-4f49-f85d1b3abc99@mfriebe.de","subject":"Re: What actually is a branch?","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-08T03:39:53Z","receivedAt":"2021-07-08T03:39:59Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 08/07/2021 00:07, Sergey Organov wrote:\n> > Felipe Contreras writes:\n> >>\n> >> This is works if your base (or tail, or whatever) is static, but many\n> >> branches jump around, and that's where @{tail} comes in handy.\n> > \n> > Yeah, I see. When I need to make a branch jump around, I do need to\n> > manually move my references, but that's fortunately very rare use-case\n> > for me. Having direct support for that is still a win.\n> > \n> >>\n> >> You can do this:\n> >>\n> >> git rebase --onto foo@{upstream} foo@{tail}\n> >>\n> >> This will always rebase the right commits (no need to look into the\n> >> reflog). So you can say that the branch is foo@{tail}..foo.\n> > \n> \n> Maybe I am missing something, is tail for tracking branches only, or for \n> just any branch?\n\nAny branch.\n\n> If for any branch, looking at\n> \n> A => B => C => D master\n> |\n> \\ / => G => H branch_1\n> => E => F\n> \\ => I => J branch_2\n> \n> Where is the base of branch_1 and branch_2?\n\nIt depends where the corresponding `git switch --create` command was\nissued.\n\nIf you did `git switch --create branch_1 B`, then @{tail} is B.\nIf you did `git switch --create branch_1 F`, then @{tail} is F.\n\n> (and does it matter if they have an upstream)\n\nNo. That's completely independent.\n\n> Maybe branch_1 diverged from Master, and then branch_2 from branch_1?\n> \n> Maybe the other way round.\n> \n> Maybe there was a branch_0 (that got removed),\n> and branch_0 diverged from master, and branch_1 and branch_2 both from \n> branch_0?\n\nYeap, the tails of branch_1 and branch_2 could be literally anywhere.\n\nThat information is not recoverable from the current data structures of\ngit, thus the proposal to add a new one.\n\n> ---\n> Also base may be misleading.\n> \n> If head is the one end of the commit chains, then base should be the other.\n> But all branches contain commits A (and B). So the base would be A.\n\nAll branches contain A, but only one branch could have A as a\nbase/tail (under normal operations), and likely none do.\n\nSuppose branch_2 was created this way:\n\n git switch --create branch_2 A\n\nThen commit B was created under branch_2. Then master was fast-forwarded\nto branch_2, so you have:\n\n A => B master\n ^ ^\n tail/branch_2 -+ +- head/branch_2\n\nBoth branches have A, but only branch_2 has A as tail.\n\nAs both branches move forward they diverge, and the \"fork-point\" is B,\nbut B is not the tail of *any* branch.\n\nNaturally then branch_1 would be created with F as a starting point, so\nthat would be the tail of branch_1.\n\nAnd once again, even though F is part of both branch_1 and branch_2,\nit's the tail of branch_1 *only*.\n\n\nThis is a convoluted way of saying: the tail of a branch is the point\nwhere that branch was created.\n\n> \"fork\" would be more descriptive IMHO?\n\nAs you can see from the example above, the tail doesn't necessarily have\nto be a fork-point.\n\nNot to mention that there can be multiple forks after the tail (e.g. B\nand F).\n\n> Also, if that is to save the user from looking up fork points, maybe \n> extend the syntax\n> branch_1@{fork:branch_2}\n> branch_1@{fork:master}\n> \n> Depending on some of the answers to the above\n> branch_1@{fork}\n> nearest fork, or upstream fork?\n\nExcept it's not necessarily a fork, nor the nearest, nor related to\nupstream...\n\nSo it's not a fork.\n\nIt can be literally any commit.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"429481","messageId":"4057b3ac-a77c-0d5f-d3f4-ad781754aae4@mfriebe.de","threadId":"56027","inReplyTo":"60e67389a4adc_306ac1208fd@natae.notmuch","subject":"Re: What actually is a branch?","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-08T10:15:10Z","receivedAt":"2021-07-08T10:15:15Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 08/07/2021 05:39, Felipe Contreras wrote:\n> \n> Yeap, the tails of branch_1 and branch_2 could be literally anywhere.\n> \n> That information is not recoverable from the current data structures of\n> git, thus the proposal to add a new one.\n\nOk, thanks for the all the explanation.\n\nA word on the name \"tail\". IMHO really confusing. I get where it is \ncoming from.\nBut a lot of people will know head and tail utilities from their shell. \nAnd \"tail\" is the one that shows lines on the end of the file to which \nnew data is added. Which is \"head\" in git.\n\nAlso a tail is something that follows, but (except for rebase), the base \npoint is fixed.\n\n\nI think (despite my earlier comment) \"base\" is a better word.\nIt also goes along with \"git rebase\" which acts on the \"base\".\n\n\nHowever wording around that topic probably still needs to be very careful.\n\"base\" must be clearly distinguished from \"start\". Because \"start\" might \nimply that only commits from here on forward are contained, but that \ncontradicts --contains which reports root to head.\n\n\n\n > Suppose branch_2 was created this way:\n >\n > git switch --create branch_2 A\n >\n > Then commit B was created under branch_2. Then master was fast-forwarded\n > to branch_2, so you have:\n >\n > A => B master\n > ^ ^\n > tail/branch_2 -+ +- head/branch_2\n >\n > Both branches have A, but only branch_2 has A as tail.\n\n\nSo base (tail) is the shared commit \"A\" on which branch_2 was created. \n(rather than the first commit made in branch_2 which is \"B\")\n\nI can see how that is needed for \"git rebase\" so @{base} can be used for \n.\n\n\n\nWhat happens if branch_2 is rebased?\nWill the base be set to the commit onto which the branch was rebased?\n\nA => B => C => D => E master\n \\ => F => G foo (base = B)\n\nfoo was created on B, then fast forwarded to C, then diverged.\n\n\n git rebase --onto A foo@{base} foo\n\nNow that foo diverges before B, having B as base for foo seems odd. \n(Also A will have C' as child, So the base really is A now)\n\n git rebase --onto E foo@{base} foo\n\nIn this case C is already contained in master, so it will be skipped.\nIf the base is moved, then foo@{base}..foo will no longer contain C. \nIMHO that is correct, because rebase skipped it.\n\nThe alternative if base = C would be kept, then foo@{base}..foo would \ncontain D and E. And that seems wrong?\n\n\n\n\nWill there be a way to manually repoint the base?\n\nA => B => C => D master\n \\ => E => F foo\n \\ => G => H bar (base = F)\n\n\nIf I do\n\n git rebase --onto master bar@{base} bar\n\nthen the commits E and F will not be part of the rebase.\nThat is fine. I must handle them before.\n\nBut if I deleted foo (or for other reasons decide E and F should be \nhandled if I rebase bar) can I make them to be included?\nSomething like\n\n git base --repoint B bar\n\n"},{"id":"429487","messageId":"87im1l3vj2.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"60e66d28c0cb3_306ac120813@natae.notmuch","subject":"Re: What actually is a branch?","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-08T11:16:49Z","receivedAt":"2021-07-08T11:16:56Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Felipe Contreras writes:\n\n> Sergey Organov wrote:\n>> Felipe Contreras writes:\n>> \n>> > Since this is not strictly related to the topic of `git switch` I\n>> > renamed the thread.\n>> >\n>> > Sergey Organov wrote:\n>> >> Felipe Contreras writes:\n>> >> > Sergey Organov wrote:\n\n[...]\n\n>> >> As for branch tail, I do have convention of marking start of a\n>> >> long-standing branch with corresponding tag, where branch \"foo\" has\n>> >> corresponding \"foo-bp\" tag marking its \"branch point\". Recently I\n>> >> started to mark start of feature branch with yet another branch \"foo-bp\"\n>> >> rather than tag, \"foo\" being set to track \"foo-bp\", that allows to\n>> >> automate rebasing of \"foo\" against correct base.\n>> >\n>> > So foo-bp is the upstream of foo, and you do basically:\n>> >\n>> > git rebase foo@{upstream}\n>> \n>> Yep, but essential feature to me is that I in fact use tools that simply\n>> run bare\n>> \n>> git rebase\n>> \n>> and that \"just works\" (tm).\n>\n> I typed the revision explicitly, but `git rebase` would work just\n> fine.\n\nSorry, I don't follow. Did you change semantic of `git rebase`? With\ncurrent mainstream Git, as far as I can tell,\n\n git rebase\n\nessentially is:\n\n git rebase --fork-point @{upstream}\n\nHow introduction of @{tail} changes this, exactly?\n\n>\n>> > This is works if your base (or tail, or whatever) is static, but many\n>> > branches jump around, and that's where @{tail} comes in handy.\n>> \n>> Yeah, I see. When I need to make a branch jump around, I do need to\n>> manually move my references, but that's fortunately very rare use-case\n>> for me. Having direct support for that is still a win.\n>> \n>> >\n>> > You can do this:\n>> >\n>> > git rebase --onto foo@{upstream} foo@{tail}\n>> >\n>> > This will always rebase the right commits (no need to look into the\n>> > reflog). So you can say that the branch is foo@{tail}..foo.\n>> \n>> I see where and when it's useful, but for a feature branch 99% of times\n>> I don't want to rebase it onto some true upstream. I rather want to just\n>> fiddle with the branch in place, and I prefer to setup things the way\n>> that ensures that bare \"git rebase\" does \"the right thing\".\n>\n> But that's precisely the point: when you do `git rebase` you don't have\n> to type the base or --onto anymore. It's done automatically.\n>\n> Not just for your long-standing branches, but for *any* branch.\n>\n>> Probably that could be solved by a branch-local configuration that makes\n>> \"git rebase\" become \"git rebase @{tail}\" for the branch instead of \"git\n>> rebase @{upstream}\"\n>\n> No. @{upstream} is where you want to rebase *to*, @{tail} is where you\n> want to rebase *from*.\n\nMy point is that for feature branch I rather want to rebase from @{tail}\nto @{tail} 99% of times.\n\n>\n> When you do:\n>\n> git rebase foo@{upstream}\n>\n> This is basically the same as:\n>\n> git checkout foo@{upstream}^0\n> git cherry-pick --right-only foo@{upstream}...foo\n\nYes, but you probably meant foo@{upstream}..foo (2 dots, not 3) here.\n\n> git is smart enough to figure out what commits are already part of\n> foo@{upstream}, and those are skipped, but at no point was any \"base\"\n> calculated (at least not from `git rebase`).\n>\n> Most of the time `git rebase` works fine, because there aren't too many\n> commits to figure out where they should go, but it's definitely not\n> efficient, and there's many corner-cases (see a Linux kernel maintaner\n> baffled by what the hell `git rebase` is doing [1]).\n\nOnce again, how exactly the foo@{tail} fits in this picture?\n\n>\n>> > Another advantage of having this notion is that `git rebase`\n>> > automatically updates the tail (in this case to foo@{upstream}).\n>> \n>> Yep, looks useful. Is it all local to given repo, or else?\n>\n> I implented it as 'refs/tails' (as opposed to 'refs/heads'), so it's\n> local to a given repo, but could easily be exported.\n\nDo I get it right that now `git switch br1; git rebase --onto br2` will\nlikely have different outcome in the repository where \"br1\" has been\ncreated compared to any other repository, as \"br1@{tail}\" will only\nexist in that exact repo?\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429502","messageId":"60e736e72da68_30939020850@natae.notmuch","threadId":"56027","inReplyTo":"4057b3ac-a77c-0d5f-d3f4-ad781754aae4@mfriebe.de","subject":"Re: What actually is a branch?","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-08T17:33:27Z","receivedAt":"2021-07-08T17:33:30Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 08/07/2021 05:39, Felipe Contreras wrote:\n> > \n> > Yeap, the tails of branch_1 and branch_2 could be literally anywhere.\n> > \n> > That information is not recoverable from the current data structures of\n> > git, thus the proposal to add a new one.\n> \n> Ok, thanks for the all the explanation.\n> \n> A word on the name \"tail\". IMHO really confusing. I get where it is \n> coming from.\n> But a lot of people will know head and tail utilities from their shell. \n> And \"tail\" is the one that shows lines on the end of the file to which \n> new data is added. Which is \"head\" in git.\n> \n> Also a tail is something that follows, but (except for rebase), the base \n> point is fixed.\n> \n> \n> I think (despite my earlier comment) \"base\" is a better word.\n> It also goes along with \"git rebase\" which acts on the \"base\".\n> \n> \n> However wording around that topic probably still needs to be very careful.\n> \"base\" must be clearly distinguished from \"start\". Because \"start\" might \n> imply that only commits from here on forward are contained, but that \n> contradicts --contains which reports root to head.\n\nI'm not really proposing such feature at this point. I did it on 2013\njust to have a solution to this problem, but I didn't push for it back\nthen.\n\nIf I ever work on that feature again I will consider the name \"base\",\nsure, but the only reason I mentioned this @{tail} concept is to try to\ndefine in a more accurate way what a branch actually is.\n\n> > Suppose branch_2 was created this way:\n> >\n> > git switch --create branch_2 A\n> >\n> > Then commit B was created under branch_2. Then master was fast-forwarded\n> > to branch_2, so you have:\n> >\n> > A => B master\n> > ^ ^\n> > tail/branch_2 -+ +- head/branch_2\n> >\n> > Both branches have A, but only branch_2 has A as tail.\n> \n> \n> So base (tail) is the shared commit \"A\" on which branch_2 was created. \n> (rather than the first commit made in branch_2 which is \"B\")\n> \n> I can see how that is needed for \"git rebase\" so @{base} can be used for \n> .\n\nYes and no. is where branch is rebased *to*, not where it's\nrebased *from*:\n\n git rebase --onto foo@{upstream} foo@{base} foo\n\nThis command rebases all the commits foo@{base}..foo on top of\nfoo@{upstream}.\n\nAnother way to think of it is that you'll cherry-pick foo@{base}..foo on\ntop of foo@{upstream}.\n\n> What happens if branch_2 is rebased?\n> Will the base be set to the commit onto which the branch was rebased?\n> \n> A => B => C => D => E master\n> \\ => F => G foo (base = B)\n> \n> foo was created on B, then fast forwarded to C, then diverged.\n> \n> \n> git rebase --onto A foo@{base} foo\n> \n> Now that foo diverges before B, having B as base for foo seems odd. \n> (Also A will have C' as child, So the base really is A now)\n\nYes, A is the new base.\n\n> git rebase --onto E foo@{base} foo\n> \n> In this case C is already contained in master, so it will be skipped.\n> If the base is moved, then foo@{base}..foo will no longer contain C. \n> IMHO that is correct, because rebase skipped it.\n\nThe new base is E.\n\nIt's not complicated, the base is whatever --onto is.\n\n> Will there be a way to manually repoint the base?\n> \n> A => B => C => D master\n> \\ => E => F foo\n> \\ => G => H bar (base = F)\n> \n> \n> If I do\n> \n> git rebase --onto master bar@{base} bar\n> \n> then the commits E and F will not be part of the rebase.\n> That is fine. I must handle them before.\n> \n> But if I deleted foo (or for other reasons decide E and F should be \n> handled if I rebase bar) can I make them to be included?\n> Something like\n> \n> git base --repoint B bar\n> \n\nI did not code that, but it's something people probably would need at\nsome point. I would do `git branch --set-base` though.\n\n\nAnyway, it seems I wasn't very clear, I'm not really proposing this\nfeature. Although I think it's something that git is missing, it would\nbe a pain in the ass to attempt to get it merged, I have much more\nimportant features I want to get done, and those don't have much chance\nof being merged either.\n\nThe only reason I mentioned @{tail} (or @{base}) is to have a better\nmental model of what a branch is.\n\n 1. A branch is whatever is inside `branch@{base}..branch`\n 2. `branch` is the branch head (`branch@{head}`), but it's not the\n branch itself\n\nFor all intents and purposes on the git documentation the branch, the\nbranch name, and the branch head are used interchangeably, but\nsemantically speaking they are not the same thing.\n\nWhen you change the branch head you are effectively changing the branch.\nIf @{base} existed, then changing the base would also change the branch\n(although that would be a much less dangerous operation).\n\nDoes that make sense?\n\n-- \nFelipe Contreras\n"},{"id":"429503","messageId":"60e73e5ebd069_309390208a@natae.notmuch","threadId":"56027","inReplyTo":"87im1l3vj2.fsf@osv.gnss.ru","subject":"Re: What actually is a branch?","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-08T18:05:18Z","receivedAt":"2021-07-08T18:05:25Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Sergey Organov wrote:\n> Felipe Contreras writes:\n> \n> > Sergey Organov wrote:\n> >> Felipe Contreras writes:\n> >> \n> >> > Since this is not strictly related to the topic of `git switch` I\n> >> > renamed the thread.\n> >> >\n> >> > Sergey Organov wrote:\n> >> >> Felipe Contreras writes:\n> >> >> > Sergey Organov wrote:\n> \n> [...]\n> \n> >> >> As for branch tail, I do have convention of marking start of a\n> >> >> long-standing branch with corresponding tag, where branch \"foo\" has\n> >> >> corresponding \"foo-bp\" tag marking its \"branch point\". Recently I\n> >> >> started to mark start of feature branch with yet another branch \"foo-bp\"\n> >> >> rather than tag, \"foo\" being set to track \"foo-bp\", that allows to\n> >> >> automate rebasing of \"foo\" against correct base.\n> >> >\n> >> > So foo-bp is the upstream of foo, and you do basically:\n> >> >\n> >> > git rebase foo@{upstream}\n> >> \n> >> Yep, but essential feature to me is that I in fact use tools that simply\n> >> run bare\n> >> \n> >> git rebase\n> >> \n> >> and that \"just works\" (tm).\n> >\n> > I typed the revision explicitly, but `git rebase` would work just\n> > fine.\n> \n> Sorry, I don't follow. Did you change semantic of `git rebase`? With\n> current mainstream Git, as far as I can tell,\n> \n> git rebase\n> \n> essentially is:\n> \n> git rebase --fork-point @{upstream}\n\nMore explicitly, it's\n\n git rebase --onto @{upstream} --fork-point @{upstream}\n\n> How introduction of @{tail} changes this, exactly?\n\nNow --fork-point is not necessary:\n\n git rebase --onto @{upstream} @{tail}\n\n> >> > This is works if your base (or tail, or whatever) is static, but many\n> >> > branches jump around, and that's where @{tail} comes in handy.\n> >> \n> >> Yeah, I see. When I need to make a branch jump around, I do need to\n> >> manually move my references, but that's fortunately very rare use-case\n> >> for me. Having direct support for that is still a win.\n> >> \n> >> >\n> >> > You can do this:\n> >> >\n> >> > git rebase --onto foo@{upstream} foo@{tail}\n> >> >\n> >> > This will always rebase the right commits (no need to look into the\n> >> > reflog). So you can say that the branch is foo@{tail}..foo.\n> >> \n> >> I see where and when it's useful, but for a feature branch 99% of times\n> >> I don't want to rebase it onto some true upstream. I rather want to just\n> >> fiddle with the branch in place, and I prefer to setup things the way\n> >> that ensures that bare \"git rebase\" does \"the right thing\".\n> >\n> > But that's precisely the point: when you do `git rebase` you don't have\n> > to type the base or --onto anymore. It's done automatically.\n> >\n> > Not just for your long-standing branches, but for *any* branch.\n> >\n> >> Probably that could be solved by a branch-local configuration that makes\n> >> \"git rebase\" become \"git rebase @{tail}\" for the branch instead of \"git\n> >> rebase @{upstream}\"\n> >\n> > No. @{upstream} is where you want to rebase *to*, @{tail} is where you\n> > want to rebase *from*.\n> \n> My point is that for feature branch I rather want to rebase from @{tail}\n> to @{tail} 99% of times.\n\nJust make @{upstream} = @{tail}, then you get your desired result.\n\n> > When you do:\n> >\n> > git rebase foo@{upstream}\n> >\n> > This is basically the same as:\n> >\n> > git checkout foo@{upstream}^0\n> > git cherry-pick --right-only foo@{upstream}...foo\n> \n> Yes, but you probably meant foo@{upstream}..foo (2 dots, not 3) here.\n\nI think if you do foo@{upstream}..foo then that --right-only doesn't do\nthe same thing.\n\n`--right-only foo@{upstream}...foo` will drop commits that already part of\nupstream. Another way you can find commits already part of upstream is\nwith `git cherry foo@{upstream}`.\n\n> > git is smart enough to figure out what commits are already part of\n> > foo@{upstream}, and those are skipped, but at no point was any \"base\"\n> > calculated (at least not from `git rebase`).\n> >\n> > Most of the time `git rebase` works fine, because there aren't too many\n> > commits to figure out where they should go, but it's definitely not\n> > efficient, and there's many corner-cases (see a Linux kernel maintaner\n> > baffled by what the hell `git rebase` is doing [1]).\n> \n> Once again, how exactly the foo@{tail} fits in this picture?\n\nIt sets so no --fork-point is necessary.\n\n> >> > Another advantage of having this notion is that `git rebase`\n> >> > automatically updates the tail (in this case to foo@{upstream}).\n> >> \n> >> Yep, looks useful. Is it all local to given repo, or else?\n> >\n> > I implented it as 'refs/tails' (as opposed to 'refs/heads'), so it's\n> > local to a given repo, but could easily be exported.\n> \n> Do I get it right that now `git switch br1; git rebase --onto br2` will\n> likely have different outcome in the repository where \"br1\" has been\n> created compared to any other repository, as \"br1@{tail}\" will only\n> exist in that exact repo?\n\nIt very well could, if `--fork-point @{upstream}` finds a different base\nthan `@{tail}`.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"429507","messageId":"155308af-42ad-b044-fb37-676251a9b7e1@mfriebe.de","threadId":"56027","inReplyTo":"60e736e72da68_30939020850@natae.notmuch","subject":"Re: What actually is a branch?","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-08T19:21:53Z","receivedAt":"2021-07-08T19:22:00Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 08/07/2021 19:33, Felipe Contreras wrote:\n> The only reason I mentioned @{tail} (or @{base}) is to have a better\n> mental model of what a branch is.\n> \n> 1. A branch is whatever is inside `branch@{base}..branch`\n\nFor this part \"branch\" = some series of commits.\n\nThen this is what I would say is a common misunderstanding.\n\nYet that may be the difference between what people want the branch to \nbe, and what it (afaik) technically is.\n\nPeople indeed tend to thing, I branched at X, so anything before is not \npart of the branch.\n\"--contains\" says otherwise.\n\n\nThinking of it.\n\nIf I look at a feature branch, then my feature starts where I created \nthe branch. I want my feature branch to represent this.\n\nBut if I look at my local master branch (or any tracking branch), I like \nto believe that it contains the same as the remote branch.\nAnd well, if we just set the base for the local tracking branch to be \nthe same as the base for the remote branch that would be fine.\nBut if (after diverging, due to changes pulled from remote) then, I run\n git rebase @{base} @{remote}\nthen rebase has to skip all the shared commits.\n\nAnd since rebase also repoints the \"base\", my local branch then no \nlonger contains the same as the remote.\n\nSo limiting the branch to branch@{base}..branch only works for feature \nbranches.\n\n\nSo yes, what is a branch? More exactly what does it contain.\nTwo examples, that to me suggest two answers.\n\n\nAlso if branch@{base}..branch then there is a problem.\n- branch@{base} is then correctly not part of the branch\n- So immediately after \"git switch -c branch\" the branch is empty => ok\nBut if so, then what is the branch head at that time?\nThe Pointer would point the @{base}, but @base is outside the branch. So \nthe pointer of the branch points outside the branch?\n\n\n\n> 2. `branch` is the branch head (`branch@{head}`), but it's not the\n> branch itself\nWell technically \"branch\" is the \"pointer\" to the head.\nAssuming we want \"head\" to be a commit?\nOr do we want head, to be the \"branch end\" after the last commit? But \nthen still \"branch is the pointer\"\n\nThe only problem is:\nbranch is too often used for \"the commits contained in the branch\". That \nis way to common to even try to stop it.\n\nYet, if branch is used for the content, then we do not have a good term \nfor the pointer.\n\n\n\n\n> \n> For all intents and purposes on the git documentation the branch, the\n> branch name, and the branch head are used interchangeably, but\n> semantically speaking they are not the same thing.\n\nI have not proof read all the docs for this....\nBut I think that \"branch name\" and \"branch head\" should or could be used \nin a clear single meaning fashion each...\n\n> \n> When you change the branch head you are effectively changing the branch.\nWell if branch is the pointer, then you change the branch, and head is \nbeing changed.\nIf branch is the content, then you change the head, and yes the content \nchanges.\n\n\n"},{"id":"429508","messageId":"60e762243aab1_30a7b02089@natae.notmuch","threadId":"56027","inReplyTo":"155308af-42ad-b044-fb37-676251a9b7e1@mfriebe.de","subject":"Re: What actually is a branch?","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-08T20:37:56Z","receivedAt":"2021-07-08T20:38:01Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 08/07/2021 19:33, Felipe Contreras wrote:\n> > The only reason I mentioned @{tail} (or @{base}) is to have a better\n> > mental model of what a branch is.\n> > \n> > 1. A branch is whatever is inside `branch@{base}..branch`\n> \n> For this part \"branch\" = some series of commits.\n> \n> Then this is what I would say is a common misunderstanding.\n> \n> Yet that may be the difference between what people want the branch to \n> be, and what it (afaik) technically is.\n\nI'm not talking about what a branch technically is, I'm talking about\nwhat it is semantically.\n\nTechnically a branch is a file with an object id in it. That doesn't\ngive the user any useful information.\n\nWhat is important is the *meaning* of that file.\n\n> People indeed tend to thing, I branched at X, so anything before is not \n> part of the branch.\n> \"--contains\" says otherwise.\n\nYes, that is the status quo, but the fact that X is the case doesn't\nmean it *should* be the case.\n\nThe ideal user interface doesn't need to be explained. The more you need\nto explain a concept the less intuitive it is, and the more you should\nlook for another concept that is perhaps more intuitive.\n\nA branch that you hold, or point to, is a concete concept easy to\nunderand. When I say: \"me, my sister, and my father are one tiny branch\nof the Contreras family\", people understand what that means inuitively.\n\nOn the other hand saying \"Felipe contains his great-great-grandfather\"\nwould stop anyone on their tracks.\n\n> Thinking of it.\n> \n> If I look at a feature branch, then my feature starts where I created \n> the branch. I want my feature branch to represent this.\n> \n> But if I look at my local master branch (or any tracking branch), I like \n> to believe that it contains the same as the remote branch.\n> And well, if we just set the base for the local tracking branch to be \n> the same as the base for the remote branch that would be fine.\n> But if (after diverging, due to changes pulled from remote) then, I run\n> git rebase @{base} @{remote}\n> then rebase has to skip all the shared commits.\n> \n> And since rebase also repoints the \"base\", my local branch then no \n> longer contains the same as the remote.\n\nThat is a *very* interesting case that exemplifies the lack of our\ncurrent semantic arsenal.\n\nEvery time you do a rebase you are in effect creating a new branch with\nnew commits, a new head, and a new base. The only thing that remains\nthe same is the name.\n\nIt is no longer the same as the remote branch, or an outgrowth; it's\na new branch.\n\nIf you send a pull request for your 'master' branch, which then gets\nmerged to 'origin/master', then you can do `git merge --ff-only` to\nadvance the head pointer of the 'master' branch to the remote branch so\nboth are in sync... Except the base won't be the same.\n\nWith the current semantics this recreated 'master' is now exactly the\nsame as the remote 'origin/master'. But not with the @{base} semantics;\nsince both branches have a different base, they are strictly speaking\ndifferent branchs.\n\nBut if you do `git reset --hard origin/master`, you are saying: drop\neverything about this branch, and make it the same 'origin/master'.\n*Now* we have a reason to distinguish `git merge --ff-only` from `git\nreset --hard`.\n\n> So limiting the branch to branch@{base}..branch only works for feature \n> branches.\n> \n> \n> So yes, what is a branch? More exactly what does it contain.\n> Two examples, that to me suggest two answers.\n\nNot necessarily. See above.\n\n> Also if branch@{base}..branch then there is a problem.\n> - branch@{base} is then correctly not part of the branch\n> - So immediately after \"git switch -c branch\" the branch is empty => ok\n> But if so, then what is the branch head at that time?\n> The Pointer would point the @{base}, but @base is outside the branch. So \n> the pointer of the branch points outside the branch?\n\nYes, the base pointer doesn't include the branch. When you do\n`branch@{base}..branch` that's the same as `^branch@{base} branch` so that\nexcludes all the commits rechable from branch@{base} *including* that\ncommit iself.\n\n> > 2. `branch` is the branch head (`branch@{head}`), but it's not the\n> > branch itself\n> Well technically \"branch\" is the \"pointer\" to the head.\n> Assuming we want \"head\" to be a commit?\n\nNo, the branch head is a reference: 'refs/heads/master'. The reference\npoints to a commit, but it's not the commit itself.\n\nSo it's a pointer to a pointer.\n\n> The only problem is:\n> branch is too often used for \"the commits contained in the branch\". That \n> is way to common to even try to stop it.\n\nWe don't need to stop it, we can sidestep it.\n\nInstead of talking about the branch, talk about the branch head:\n\"the brach head is moved to X\".\n\nOr if you want to use the branch, don't assume any specifics:\n\"the branch is recreated to be the same as X\".\n\n> > When you change the branch head you are effectively changing the branch.\n> Well if branch is the pointer, then you change the branch, and head is \n> being changed.\n> If branch is the content, then you change the head, and yes the content \n> changes.\n\nExactly, so regardless of which semantics you choose, everyone\nunderstands that the branch is not the same anymore.\n\n-- \nFelipe Contreras\n"},{"id":"429514","messageId":"2b85a7eb-d0be-65e7-ecbb-1750abf53e53@mfriebe.de","threadId":"56027","inReplyTo":"60e762243aab1_30a7b02089@natae.notmuch","subject":"Re: What actually is a branch?","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-08T23:11:58Z","receivedAt":"2021-07-08T23:12:23Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 08/07/2021 22:37, Felipe Contreras wrote:\n> Technically a branch is a file with an object id in it. That doesn't\n> give the user any useful information.\n> \n> What is important is the *meaning* of that file.\n> \n>> People indeed tend to thing, I branched at X, so anything before is not\n>> part of the branch.\n>> \"--contains\" says otherwise.\n> \n> Yes, that is the status quo, but the fact that X is the case doesn't\n> mean it *should* be the case.\n\nWell yes. So lets start over.\n\nA branch is a container for commits. Those commits have a start (root or \nbase / not sure), and an end (head).\nThe commits are continuous, in that they have no gaps.\n\nThe big question is the start point of the branch.\n\nAnd there is a further consequence:\nIf a branch \"starts\" at \"base\" then\n --contains needs to be changed\n --reachable needs to be added (for what contains does now)\n\nThis also complicates it, because now there are 3 types of relation \nbetween commits and a branch\n- unrelated (outside / not reachable)\n- inside (base..head)\n- reachable (base and all its parents) // better word needed\n\nThe last is important:\n\nA => B => C master\n \\ => D foo\n\nIf I delete master, without the concept of reachable, I would expect \ncommit A to be dropped. Technically B should drop too, but it takes some \ninsight to expect that.\nSo then with only the branch foo left, I would also have only the commit \nD (well maybe B too, if the system is lenient)\n\nOne might even go an say if master is deleted, then the base of foo is \ndeleted. since foo must have a base, and it no longer has, foo can not \nexist any longer.\n\nThe problem here is that git permits to change history.\nIf branches could not be rewritten or deleted, then the \"base\" would be \na simple concept.\nNo branch would ever have to look what was before its base.\nBut as it stands, branches must reach to what was before their base.\n\n\n> \n> A branch that you hold, or point to, is a concete concept easy to\n> underand. When I say: \"me, my sister, and my father are one tiny branch\n> of the Contreras family\", people understand what that means inuitively.\n> \n> On the other hand saying \"Felipe contains his great-great-grandfather\"\n> would stop anyone on their tracks.\n\nThe Chicago branch of your family contains Al Capone.\nThat works.\n\nContains is also nice, because we have 2 boundaries (base/head) to \nenclose the selection.\n\n\n> But if you do `git reset --hard origin/master`, you are saying: drop\n> everything about this branch, and make it the same 'origin/master'.\n> *Now* we have a reason to distinguish `git merge --ff-only` from `git\n> reset --hard`.\n\nNo you don't. IMHO not.\n\"reset --hard\" resets the branch to a commit. You can specify that \ncommit by giving a branch-name (that then will be resolved). But it \ncould be any commit, even a detached one.\n\nSo \"reset --hard\" has to set the base and the head to the same commit. \nEffectively creating an empty branch based at that commit.\n\nBut local tracking branches still are counter intuitive.\n\nIMHO local tracking branches should follow one of the following \nscenarios. (And ideally that should be the same for all local tracking \nbranches, for any user.)\n\n1) Always have the same base as their remote branch.\nTherefore always have the same content as the remote branch, up to where \nthey diverge, if they diverge.\n\n2) Not include the remote branches content. Just hold my local commits, \nuntil they will be pushed to the remote.\n\nBut neither works:\n\nSay I have a local commit, and you pushed new changes to the remote.\n git pull --rebase\nMy branch is rebased.\nSo my local tracking branch has its base at the head of the remote. It \nhas only local commits => case 1.\n\nSay I have no local commits, and you pushed new changes to the remote.\n git pull --ff-only\nIf I understand correct the --ff-only move the head of my local branch, \nbut leaves the base where it is.\nNow I have some shared commits with the remote branch.\n=> either case 2, or worse none of the 2 cases.\n\nSo, how should local tracking branches behave?\n\n\n> If you send a pull request for your 'master' branch, which then gets\n> merged to 'origin/master', then you can do `git merge --ff-only` to\n> advance the head pointer of the 'master' branch to the remote branch so\n> both are in sync... Except the base won't be the same.\n\nThere may be something I missed. ff should not touch the base?\nSo the 2 base will still be the same or not the same, depending on if \nthey were equal before the ff?\n\n\n>>\n>> So yes, what is a branch? More exactly what does it contain.\n>> Two examples, that to me suggest two answers.\n> \n> Not necessarily. See above.\n\nI feel we must have some understandingly on the part how base and local \nbranches would interact.\n\nYou agree: rebase changes the base (it creates a new branch on to --onto)\n\nYou pointed out there also is fast-forward. But see my above example.\nI am not even doing a pull request. I simply go for you and I both can \npush to the same remote. So we both commit to master and pull/push it.\n\n\n\n> \n>> Also if branch@{base}..branch then there is a problem.\n>> - branch@{base} is then correctly not part of the branch\n>> - So immediately after \"git switch -c branch\" the branch is empty => ok\n>> But if so, then what is the branch head at that time?\n>> The Pointer would point the @{base}, but @base is outside the branch. So\n>> the pointer of the branch points outside the branch?\n> \n> Yes, the base pointer doesn't include the branch. When you do\n> `branch@{base}..branch` that's the same as `^branch@{base} branch` so that\n> excludes all the commits rechable from branch@{base} *including* that\n> commit iself.\n\nMy question is, where you see the branch head pointing to?\nIf the branch is empty, i.e. if it has no commit at all, then to what \ncommit does the branch head point?\n\n\n\n>> The only problem is:\n>> branch is too often used for \"the commits contained in the branch\". That\n>> is way to common to even try to stop it.\n> \n> We don't need to stop it, we can sidestep it.\n> \n> Instead of talking about the branch, talk about the branch head:\n> \"the brach head is moved to X\".\n\nYes well, we need to be very concise, if we speak about anything that is \nnot the \"commits in the branch\".\n\n\n>>> When you change the branch head you are effectively changing the branch.\n>> Well if branch is the pointer, then you change the branch, and head is\n>> being changed.\n>> If branch is the content, then you change the head, and yes the content\n>> changes.\n> \n> Exactly, so regardless of which semantics you choose, everyone\n> understands that the branch is not the same anymore.\n> \n\nYour original text was\n> When you change the branch head you are effectively changing the branch.\n> If @{base} existed, then changing the base would also change the branch\n> (although that would be a much less dangerous operation).\n> \n> Does that make sense?\n\nAnd yes, if either boundary changes, the branch changed.\n\n\n"},{"id":"429516","messageId":"60e79c31aaa72_30b8a4208c1@natae.notmuch","threadId":"56027","inReplyTo":"2b85a7eb-d0be-65e7-ecbb-1750abf53e53@mfriebe.de","subject":"Re: What actually is a branch?","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-09T00:45:37Z","receivedAt":"2021-07-09T00:45:41Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 08/07/2021 22:37, Felipe Contreras wrote:\n> > Technically a branch is a file with an object id in it. That doesn't\n> > give the user any useful information.\n> > \n> > What is important is the *meaning* of that file.\n> > \n> >> People indeed tend to thing, I branched at X, so anything before is not\n> >> part of the branch.\n> >> \"--contains\" says otherwise.\n> > \n> > Yes, that is the status quo, but the fact that X is the case doesn't\n> > mean it *should* be the case.\n> \n> Well yes. So lets start over.\n> \n> A branch is a container for commits. Those commits have a start (root or \n> base / not sure), and an end (head).\n> The commits are continuous, in that they have no gaps.\n> \n> The big question is the start point of the branch.\n> \n> And there is a further consequence:\n> If a branch \"starts\" at \"base\" then\n> --contains needs to be changed\n> --reachable needs to be added (for what contains does now)\n\nIndeed, but as of this moment @{base} is not being considered, it's just\na mental model tool.\n\n> This also complicates it, because now there are 3 types of relation \n> between commits and a branch\n> - unrelated (outside / not reachable)\n> - inside (base..head)\n> - reachable (base and all its parents) // better word needed\n\nI think that has always been the case. The fact that the git\ndocumentation doesn't talk about that doesn't mean the concept doesn't\nexist.\n\n> The last is important:\n> \n> A => B => C master\n> \\ => D foo\n> \n> If I delete master, without the concept of reachable, I would expect \n> commit A to be dropped. Technically B should drop too, but it takes some \n> insight to expect that.\n> So then with only the branch foo left, I would also have only the commit \n> D (well maybe B too, if the system is lenient)\n\nCommits don't need a branch to exist. B could have a tag 0.3.7 and no\nbranch pointing to it. There could be other refs pointing to that\ncommit.\n\n> One might even go an say if master is deleted, then the base of foo is \n> deleted. since foo must have a base, and it no longer has, foo can not \n> exist any longer.\n\nOf course it can. The base of a branch doesn't necessarily need to be\npart of any other branch.\n\nOr another way to think of it is that B is part of an unnamed branch.\n\n> > A branch that you hold, or point to, is a concete concept easy to\n> > underand. When I say: \"me, my sister, and my father are one tiny branch\n> > of the Contreras family\", people understand what that means inuitively.\n> > \n> > On the other hand saying \"Felipe contains his great-great-grandfather\"\n> > would stop anyone on their tracks.\n> \n> The Chicago branch of your family contains Al Capone.\n> That works.\n\nSure, if you start from a certain grandparent, not if you start from my\ngrandfather.\n\nMost humans have issue with more than 7 items. A branch containing\nmillions of members reaching as far back as a fish is a notion an\nevolutionary biologist might not have any problem with, but most people\nwould struggle.\n\nFor most people a branch must start from somewhere.\n\n> > But if you do `git reset --hard origin/master`, you are saying: drop\n> > everything about this branch, and make it the same 'origin/master'.\n> > *Now* we have a reason to distinguish `git merge --ff-only` from `git\n> > reset --hard`.\n> \n> No you don't. IMHO not.\n> \"reset --hard\" resets the branch to a commit. You can specify that \n> commit by giving a branch-name (that then will be resolved). But it \n> could be any commit, even a detached one.\n\nOK. Sure. It could be repurposed to say what I explained, but we might\nbe overloading that command in that case.\n\nHow about `gt branch --reset `?\n\n> So \"reset --hard\" has to set the base and the head to the same commit. \n> Effectively creating an empty branch based at that commit.\n\nMaybe. Or maybe the base remains the same. Fortunately that's not\nsomething we need concern ourselves with at this moment.\n\n> But local tracking branches still are counter intuitive.\n> \n> IMHO local tracking branches should follow one of the following \n> scenarios. (And ideally that should be the same for all local tracking \n> branches, for any user.)\n> \n> 1) Always have the same base as their remote branch.\n> Therefore always have the same content as the remote branch, up to where \n> they diverge, if they diverge.\n> \n> 2) Not include the remote branches content. Just hold my local commits, \n> until they will be pushed to the remote.\n> \n> But neither works:\n> \n> Say I have a local commit, and you pushed new changes to the remote.\n> git pull --rebase\n> My branch is rebased.\n> So my local tracking branch has its base at the head of the remote. It \n> has only local commits => case 1.\n> \n> Say I have no local commits, and you pushed new changes to the remote.\n> git pull --ff-only\n> If I understand correct the --ff-only move the head of my local branch, \n> but leaves the base where it is.\n> Now I have some shared commits with the remote branch.\n> => either case 2, or worse none of the 2 cases.\n\nThere's no need for --ff-only, do `git pull --rebase` on both cases, and\nthe base will constantly be reset to the remote head.\n\nHowever, at least I never do this. My 'master' branch doesn't contain\nany commits and I always do the equivalent of `git pull --ff-only`, so\nthe base would never change.\n\n> > If you send a pull request for your 'master' branch, which then gets\n> > merged to 'origin/master', then you can do `git merge --ff-only` to\n> > advance the head pointer of the 'master' branch to the remote branch so\n> > both are in sync... Except the base won't be the same.\n> \n> There may be something I missed. ff should not touch the base?\n> So the 2 base will still be the same or not the same, depending on if \n> they were equal before the ff?\n\nThat's right. Before the fast-forward the base was different (because of\nthe rebase), so after the fast-forward the base remains different.\n\n> >> So yes, what is a branch? More exactly what does it contain.\n> >> Two examples, that to me suggest two answers.\n> > \n> > Not necessarily. See above.\n> \n> I feel we must have some understandingly on the part how base and local \n> branches would interact.\n> \n> You agree: rebase changes the base (it creates a new branch on to --onto)\n> \n> You pointed out there also is fast-forward. But see my above example.\n> I am not even doing a pull request. I simply go for you and I both can \n> push to the same remote. So we both commit to master and pull/push it.\n\nIt doesn't matter who does the merge:\n\n git merge origin/master\n git push\n\nIt would be the same as a pull request followed by a fast-forward\n(except with the parents reversed).\n\nThe base remains unmoved.\n\n> >> Also if branch@{base}..branch then there is a problem.\n> >> - branch@{base} is then correctly not part of the branch\n> >> - So immediately after \"git switch -c branch\" the branch is empty => ok\n> >> But if so, then what is the branch head at that time?\n> >> The Pointer would point the @{base}, but @base is outside the branch. So\n> >> the pointer of the branch points outside the branch?\n> > \n> > Yes, the base pointer doesn't include the branch. When you do\n> > `branch@{base}..branch` that's the same as `^branch@{base} branch` so that\n> > excludes all the commits rechable from branch@{base} *including* that\n> > commit iself.\n> \n> My question is, where you see the branch head pointing to?\n> If the branch is empty, i.e. if it has no commit at all, then to what \n> commit does the branch head point?\n\nTo the same commit as the base: master..master contains zero commits.\n\n> >> The only problem is:\n> >> branch is too often used for \"the commits contained in the branch\". That\n> >> is way to common to even try to stop it.\n> > \n> > We don't need to stop it, we can sidestep it.\n> > \n> > Instead of talking about the branch, talk about the branch head:\n> > \"the brach head is moved to X\".\n> \n> Yes well, we need to be very concise, if we speak about anything that is \n> not the \"commits in the branch\".\n> \n> \n> >>> When you change the branch head you are effectively changing the branch.\n> >> Well if branch is the pointer, then you change the branch, and head is\n> >> being changed.\n> >> If branch is the content, then you change the head, and yes the content\n> >> changes.\n> > \n> > Exactly, so regardless of which semantics you choose, everyone\n> > understands that the branch is not the same anymore.\n> > \n> \n> Your original text was\n> > When you change the branch head you are effectively changing the branch.\n> > If @{base} existed, then changing the base would also change the branch\n> > (although that would be a much less dangerous operation).\n> > \n> > Does that make sense?\n> \n> And yes, if either boundary changes, the branch changed.\n\nBut our immediate concern is to improve the documentation of\n`git switch -C`, and perhaps improve the interface while we are at it.\n\nI believe we have all the semantic tools needed to write something that\nis understandable by most people regardless of their conception of what a\nbranch is.\n\nNo?\n\n-- \nFelipe Contreras\n"},{"id":"429541","messageId":"084a355e-95cd-5c84-2fa5-a901da3e0e49@mfriebe.de","threadId":"56027","inReplyTo":"60e79c31aaa72_30b8a4208c1@natae.notmuch","subject":"Re: What actually is a branch?","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-09T13:24:23Z","receivedAt":"2021-07-09T13:24:29Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"\nOn 09/07/2021 02:45, Felipe Contreras wrote:\n> I believe we have all the semantic tools needed to write something that\n> is understandable by most people regardless of their conception of what a\n> branch is.\n\n\n\nWhile writing a mail on the origin topic (improve docs), I noticed that \nthe word \"branch-ish\" is still free.\n\nWhich would be anything that resolves to a \"branch reference\".\n\nCurrently this only is\n- branch name.\n- branchname@{upstream}\n\nBtw, if branch-foo is tracking a local branch then\n git checkout branch-foo@{upstream}\nwill switch the the tracked local branch.\n\n\n* \"branch-ish\" could be defined as:\nAnything that can be resolved to a branch-name.\nA branch-name is a reference to the boundary that marks the end of a \nbranch.\nA branch-ish can be given where a commit-ish is expected. In that case \nit can be resolved to the last commit in the branch.\n\n\nThere may be further need to distinguish between local and remote.\n\nFor example\n git checkout []\n> When the argument is a branch name, the --detach option can be used to detach HEAD at the tip of the branch (git checkout would check out that branch without detaching HEAD).\n\nDoes not mention that it will also detach, if is the a remote \nbranch name\n git checkout origin/master\n"},{"id":"429544","messageId":"65362688-b65b-661c-20c1-94d7dc2118c7@mfriebe.de","threadId":"56027","inReplyTo":"60e79c31aaa72_30b8a4208c1@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-09T14:29:46Z","receivedAt":"2021-07-09T14:29:52Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 09/07/2021 02:45, Felipe Contreras wrote:\n> I believe we have all the semantic tools needed to write something that\n> is understandable by most people regardless of their conception of what a\n> branch is.\n> \n\nSo returning to the original topic.\n\n\nWhile writing this, I thought maybe there is a need for a\n\"Guideline on writing documentation\" ?\n\n\n\nOn 01/07/2021 16:58, Junio C Hamano proposed a patch that had an \ninteresting point.\nThe patch was for the docs of \"git switch\" and \"git branch\"\n\n1)\n\n versus \n\nI am not sure that this will help much with the original issue, which is \nmy concern that a (new) user will be aware of why \"switch -C\" is a force \n(i.e. what the dangers are).\nBut it is an interesting point.\n\n From the synopsis of various commands (just a sample, I did not check all).\n git switch (-c|-C) []\n git branch []\n git checkout [--detach] \n git checkout [[-b|-B|--orphan] ] []\n git reset [--soft | --mixed | --hard ] []\n\nWith the exception for \"git reset\" they all use when it \ncomes to branches.\n\nThe general question here is, should the synopsis say\na) this parameter should be a \"commit\".\nAnd then the doc explains the commit will be used as startpoint\nb) this parameter should be a \"start point\"\nAnd then the doc explains the startpoint has to be given as commit.\n\nIn terms of checkout, this is especially interesting.\nThe 2nd form does create a new branch.\nBut both forms check-out the commit.\nIMHO it is somewhat strange that you \"check out a start-point to your \nworktree\".\n\nSo probably (or even ) may indeed be the better option.\nThis is however an issue that goes well beyond \"git switch\".\n\nThis may also affect other words used in synopsises. So this is a \ngeneral rule that needs to be decided for all of the documentation.\nThe issue is, that some commands take several commits.\n git rebase [--onto ] [ []]\nIn that case some distinguishing is needed.\n\nThere also is the option of \"\".\nThis tells the user that a commit-ish is needed. But distinguishes it \nfrom other that may be given as argument.\nThis may lead to rather long names (e.g. in rebase).\nThough in checkout, I would use only in both variants, as \nthe main action is to check out that commit.\n\n\n2)\n\n versus \n\n git switch [--no-guess] \n git switch (-c|-C) []\n git branch []\n git checkout [[-b|-B|--orphan] ] []\n git rebase [--onto ] [ []]\n\nFirst of all \"git rebase\" is simply wrong. I can give a commit for all 3 \narguments. So the last one does not have to be a branch. (or )\n\nThen I think (or /see other mail) should be \npreferred over .\n\nAs for \"git switch -C\"\nThis should IMHO change to (the 2nd arg, actually depends on the point \n\"1\" above)\n git switch (-c|-C) []\n\nI suggest to not call it \"new-branch-name\" because, it might be an \nexisting name.\n\n\n3)\n\n newbbranch versus new-branch versus new_branch\n\nThat is something that just needs to be decided.\n\"new_branch\" is in git checkout.\n\n\n4)\n\n Extend of explanation for why a command is classified as \"force\".\n\nThis one is the one I still lobby for support.\nThis is also on issue across all docs. (or most)\n\nCurrently \"git switch -C\" is simply stated to be --force-create.\n\n- There is no mention what is \"forced\". All it says is:\n> if already exists, it will be reset to .\nI guess this is the English verb reset. Because, if the user goes to \n\"git reset\" then the user would not know what kind of reset.\nSo the term \"reset\" is ambiguous, as it could be the verb, or the command.\n\nOf course the \"git branch\" doc has the same\n> Reset to , even if exists already. \n\n\nThere is also no word, that this does not include overwriting a dirty \nwork tree.\n\n git switch --force -c unused-name origin/branch\nmeans \"forcefully overwrite a dirty work tree\"\n\n git switch --force-create unused-name origin/branch\nfails on the dirty work tree.\n\n\nBtw similar on \"git checkout\"\n git checkout -B unused-name origin/branch\nOnly difference, -B has no misleading long option.\n\n\nBut my point is less, the not applying danger.\nMy point is what danger is there, so that this was made a force command?\n\nLook at\n git checkout --force\n> --force\n> When switching branches, proceed even if the index or the working tree differs from HEAD. This is used to throw away local changes.\n\n git switch --force\n> --force\n> An alias for --discard-changes.\nand then eventually\n> This is used to throw away local changes.\n\nSo --force clearly says: You will loose local changes (if you have any).\n\nThe same clarity is missing for \"force create branch\".\n\nYes, sure any commits that where in the branch, may be hold by other \nbranches or the ref-log.\nBut neither is guaranteed. A branch does not need to have a reflog.\n\nEven if we say a user must know about certain concepts (such as a \nbranchname is a reference, and non referenced objects may be lost), even \nthen the user is left to connect the dots themself.\n\nI think it should be included in the docs (git switch/checkout/branch \nand reset)\n\nThe current wording\n Reset to , even if\n exists already.\n\nshould be amended\nAvoid \"reset\"\n Create a new branch at with the name\n , even if is already used.\n\nAdd clarity\n Create a new branch at with the name\n .\n If already existed, then the old branch\n will be removed.\n\nIf the user perceives \"the old branch\" as container for a \"chain of \ncommits\", then it is still up to the user to know, that any of those \ncommits can be part of other branches. And that \"removing the branch\", \nmay or may not include removing the commits.\n\nHowever, a user not yet knowing what exactly \"removing a branch\" means, \ndoes at least have the word \"remove\" to make him wary that they should \nlook up more details.\n\n\n"},{"id":"429551","messageId":"60e8666c8707f_2153208c0@natae.notmuch","threadId":"56027","inReplyTo":"084a355e-95cd-5c84-2fa5-a901da3e0e49@mfriebe.de","subject":"Re: What actually is a branch?","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-09T15:08:28Z","receivedAt":"2021-07-09T15:08:39Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n\n> While writing a mail on the origin topic (improve docs), I noticed that \n> the word \"branch-ish\" is still free.\n> \n> Which would be anything that resolves to a \"branch reference\".\n> \n> Currently this only is\n> - branch name.\n> - branchname@{upstream}\n\nActually @ and HEAD too.\n\nI don't particularly see much value in that definition since I always\nuse a committish when I write a branch name, and the fact that\n`git switch` expects branches is one of the things that bothers me about\nit.\n\nEither way I don't think it makes much sense to do\n`git switch branchnae@{upstream}`, and even less `git switch @`.\n\n-- \nFelipe Contreras\n"},{"id":"429553","messageId":"57f316cb-850d-706a-592b-4376f240e032@mfriebe.de","threadId":"56027","inReplyTo":"60e8666c8707f_2153208c0@natae.notmuch","subject":"switch requires --detach [[Re: What actually is a branch]]","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-09T15:23:23Z","receivedAt":"2021-07-09T15:23:30Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"\nOn 09/07/2021 17:08, Felipe Contreras wrote:\n> and the fact that\n> `git switch` expects branches is one of the things that bothers me about\n> it.\n\nAh, good point.\n\nI would word it differently though.\n\"git switch forces the use of --detach if switching to a non branch\"\n\nBit of a twist.\nIt's a nice safety for beginners. I remember when I started, I kept \nending up detached. And I had no idea what to do next.\n\n\nBut once you are a bit more experienced the need to add that option can \nbe bothersome.\nIt's not common in my workflow, but I can see that it can be an issue.\n\nSo how to remedy?\n\n- Drop the option / Make it default?\n- add --allow-detach and git config switch.detach allow ?\n\nI don't really have a preference.\n\nI think its a nice protection, but even without it, the warning on \nentering detached HEAD state is pretty good.\n\n\nThere is also a curious side effect.\n\nIf you went into detached, you can go back to attached using\n git switch -\n\nbut not back to detached by again doing\n git switch -\n\nEven though you had been there, and that means you had used --detached, \nand therefore known what you did.\n"},{"id":"429561","messageId":"60e874e1c6845_215320861@natae.notmuch","threadId":"56027","inReplyTo":"65362688-b65b-661c-20c1-94d7dc2118c7@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-09T16:10:09Z","receivedAt":"2021-07-09T16:10:14Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 09/07/2021 02:45, Felipe Contreras wrote:\n> > I believe we have all the semantic tools needed to write something that\n> > is understandable by most people regardless of their conception of what a\n> > branch is.\n\n> On 01/07/2021 16:58, Junio C Hamano proposed a patch that had an \n> interesting point.\n> The patch was for the docs of \"git switch\" and \"git branch\"\n> \n> 1)\n> \n> versus \n> \n> I am not sure that this will help much with the original issue, which is \n> my concern that a (new) user will be aware of why \"switch -C\" is a force \n> (i.e. what the dangers are).\n> But it is an interesting point.\n\nI don't think it's an improvement. What is that used for?\nThat's what the user wants to know, not to mention that not any commit\nworks.\n\n> From the synopsis of various commands (just a sample, I did not check all).\n> git switch (-c|-C) []\n> git branch []\n> git checkout [--detach] \n> git checkout [[-b|-B|--orphan] ] []\n> git reset [--soft | --mixed | --hard ] []\n> \n> With the exception for \"git reset\" they all use when it \n> comes to branches.\n> \n> The general question here is, should the synopsis say\n> a) this parameter should be a \"commit\".\n> And then the doc explains the commit will be used as startpoint\n\nI'd say no. I think it's pretty obvious what these commands accept as\ninput, what isn't clear is what that input is for.\n\n> b) this parameter should be a \"start point\"\n> And then the doc explains the startpoint has to be given as commit.\n\nI don't see much value in explaining that has to be given as a commit.\nHow else would it be given as?\n\n> In terms of checkout, this is especially interesting.\n> The 2nd form does create a new branch.\n\nYou could say both forms create a new branch, except in the first form\nthe branch doesn't have a name.\n\n> But both forms check-out the commit.\n> IMHO it is somewhat strange that you \"check out a start-point to your \n> worktree\".\n> \n> So probably (or even ) may indeed be the better option.\n\nBut we don't need all the commands to say the same thing, what we need\nis something that's easy for the user to understand, and it's accurate.\n\n> This is however an issue that goes well beyond \"git switch\".\n\nIndeed, but if history is an indication nothing will change (changes in\ngit's UI rarely do happen), so its better to minimize the possibility\nthat the patch will be ignored, or straight up rejected.\n\nSo it's better to stick with the experimental command and fix that\nfirst.\n\n> This may also affect other words used in synopsises. So this is a \n> general rule that needs to be decided for all of the documentation.\n> The issue is, that some commands take several commits.\n> git rebase [--onto ] [ []]\n> In that case some distinguishing is needed.\n\nI'd say it shouldn't matter if it recevies one or several, what that\ncommit is used for is what matters.\n\n> 2)\n> \n> versus \n> \n> git switch [--no-guess] \n> git switch (-c|-C) []\n> git branch []\n> git checkout [[-b|-B|--orphan] ] []\n> git rebase [--onto ] [ []]\n> \n> First of all \"git rebase\" is simply wrong. I can give a commit for all 3 \n> arguments. So the last one does not have to be a branch. (or )\n\nTrue. Although in most cases the last one would be a branch.\n\n> Then I think (or /see other mail) should be \n> preferred over .\n\nI don't think it makes a difference. A branch name is how you refer to a\nbranch (what else would be there?).\n\nDifferentiating the difference between a branch and a branch name was\ndone to write better sentences in the description of what the commands\ndo, but in the synopsis I don't see what we gain.\n\n> As for \"git switch -C\"\n> This should IMHO change to (the 2nd arg, actually depends on the point \n> \"1\" above)\n> git switch (-c|-C) []\n> \n> I suggest to not call it \"new-branch-name\" because, it might be an \n> existing name.\n\nI think the name is all wrong. As Ævar pointed out --new (-n) is much\nbetter. Also it doesn't make much sense to use \"create\" or \"new\" for\nsomething that already exists.\n\nI think you saw a correct issue: `git switch -C` might be used\nincorrectly, but changing to the documentation would have limited value\n(and only for the ones that read it).\n\nI think if the branch already exists, the user has to be explicit to\nwhat he wants to do and use `git switch --reset `\n\n> 3)\n> \n> newbbranch versus new-branch versus new_branch\n> \n> That is something that just needs to be decided.\n> \"new_branch\" is in git checkout.\n\nI'd rather have , but as I already said, the more ground you try\nto cover the more impossible it will be to actually land the changes.\n\n> 4)\n> \n> Extend of explanation for why a command is classified as \"force\".\n> \n> This one is the one I still lobby for support.\n> This is also on issue across all docs. (or most)\n> \n> Currently \"git switch -C\" is simply stated to be --force-create.\n> \n> - There is no mention what is \"forced\". All it says is:\n> > if already exists, it will be reset to .\n> I guess this is the English verb reset. Because, if the user goes to \n> \"git reset\" then the user would not know what kind of reset.\n> So the term \"reset\" is ambiguous, as it could be the verb, or the command.\n> \n> Of course the \"git branch\" doc has the same\n> > Reset to , even if exists already. \n> \n> \n> There is also no word, that this does not include overwriting a dirty \n> work tree.\n> \n> git switch --force -c unused-name origin/branch\n> means \"forcefully overwrite a dirty work tree\"\n> \n> git switch --force-create unused-name origin/branch\n> fails on the dirty work tree.\n> \n> \n> Btw similar on \"git checkout\"\n> git checkout -B unused-name origin/branch\n> Only difference, -B has no misleading long option.\n> \n> \n> But my point is less, the not applying danger.\n> My point is what danger is there, so that this was made a force command?\n> \n> Look at\n> git checkout --force\n> > --force\n> > When switching branches, proceed even if the index or the working tree differs from HEAD. This is used to throw away local changes.\n> \n> git switch --force\n> > --force\n> > An alias for --discard-changes.\n> and then eventually\n> > This is used to throw away local changes.\n> \n> So --force clearly says: You will loose local changes (if you have any).\n> \n> The same clarity is missing for \"force create branch\".\n> \n> Yes, sure any commits that where in the branch, may be hold by other \n> branches or the ref-log.\n> But neither is guaranteed. A branch does not need to have a reflog.\n> \n> Even if we say a user must know about certain concepts (such as a \n> branchname is a reference, and non referenced objects may be lost), even \n> then the user is left to connect the dots themself.\n> \n> I think it should be included in the docs (git switch/checkout/branch \n> and reset)\n> \n> The current wording\n> Reset to , even if\n> exists already.\n> \n> should be amended\n> Avoid \"reset\"\n> Create a new branch at with the name\n> , even if is already used.\n> \n> Add clarity\n> Create a new branch at with the name\n> .\n> If already existed, then the old branch\n> will be removed.\n> \n> If the user perceives \"the old branch\" as container for a \"chain of \n> commits\", then it is still up to the user to know, that any of those \n> commits can be part of other branches. And that \"removing the branch\", \n> may or may not include removing the commits.\n> \n> However, a user not yet knowing what exactly \"removing a branch\" means, \n> does at least have the word \"remove\" to make him wary that they should \n> look up more details.\n\nAll these issues go away if we have:\n\n git switch --reset \n\nAnd instead of -C, we have:\n\n git switch --new --reset \n\nThis creates a new branch if it doesn't exist, or if it exists resets\nit.\n\nNow the documentation writes itself.\n\nCheers.\n\n-- \nFelipe Contreras"},{"id":"429562","messageId":"60e8776cdc455_215320852@natae.notmuch","threadId":"56027","inReplyTo":"57f316cb-850d-706a-592b-4376f240e032@mfriebe.de","subject":"RE: switch requires --detach [[Re: What actually is a branch]]","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-09T16:21:00Z","receivedAt":"2021-07-09T16:21:09Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> \n> On 09/07/2021 17:08, Felipe Contreras wrote:\n> > and the fact that\n> > `git switch` expects branches is one of the things that bothers me about\n> > it.\n> \n> Ah, good point.\n> \n> I would word it differently though.\n> \"git switch forces the use of --detach if switching to a non branch\"\n> \n> Bit of a twist.\n> It's a nice safety for beginners. I remember when I started, I kept \n> ending up detached. And I had no idea what to do next.\n\nYes, and that's a good thing, but there's no need to cripple advaned\nusers.\n\n> But once you are a bit more experienced the need to add that option can \n> be bothersome.\n> It's not common in my workflow, but I can see that it can be an issue.\n> \n> So how to remedy?\n> \n> - Drop the option / Make it default?\n\nNo. As you noted it has value for beginners.\n\n> - add --allow-detach and git config switch.detach allow ?\n\nThat's a good option, but another one would be to have a core.advanced\nmode, you turn it on if you are an advanced user.\n\n> I don't really have a preference.\n> \n> I think its a nice protection, but even without it, the warning on \n> entering detached HEAD state is pretty good.\n\nThat warning olny appears with `git checkout`, not with\n`git switch --detach`.\n\n> There is also a curious side effect.\n> \n> If you went into detached, you can go back to attached using\n> git switch -\n> \n> but not back to detached by again doing\n> git switch -\n> \n> Even though you had been there, and that means you had used --detached, \n> and therefore known what you did.\n\nThat's definitely a bug.\n\n-- \nFelipe Contreras\n"},{"id":"429563","messageId":"008701d774e0$d3220f40$79662dc0$@nexbridge.com","threadId":"56027","inReplyTo":"60e8776cdc455_215320852@natae.notmuch","subject":"RE: switch requires --detach [[Re: What actually is a branch]]","fromName":"Randall S. Becker","fromEmail":"rsbecker@nexbridge.com","sentAt":"2021-07-09T16:38:13Z","receivedAt":"2021-07-09T16:38:26Z","isPatch":false,"sender":{"key":"randall.becker@nexbridge.ca","avatar":"https://avatars.githubusercontent.com/u/28956764?v=4"},"body":"On July 9, 2021 12:21 PM, Felipe Contreras wrote:\n>Martin wrote:\n>>\n>> On 09/07/2021 17:08, Felipe Contreras wrote:\n>> > and the fact that\n>> > `git switch` expects branches is one of the things that bothers me\n>> > about it.\n>>\n>> Ah, good point.\n>>\n>> I would word it differently though.\n>> \"git switch forces the use of --detach if switching to a non branch\"\n>>\n>> Bit of a twist.\n>> It's a nice safety for beginners. I remember when I started, I kept\n>> ending up detached. And I had no idea what to do next.\n>\n>Yes, and that's a good thing, but there's no need to cripple advaned users.\n>\n>> But once you are a bit more experienced the need to add that option\n>> can be bothersome.\n>> It's not common in my workflow, but I can see that it can be an issue.\n>>\n>> So how to remedy?\n>>\n>> - Drop the option / Make it default?\n>\n>No. As you noted it has value for beginners.\n>\n>> - add --allow-detach and git config switch.detach allow ?\n>\n>That's a good option, but another one would be to have a core.advanced mode, you turn it on if you are an advanced user.\n>\n>> I don't really have a preference.\n>>\n>> I think its a nice protection, but even without it, the warning on\n>> entering detached HEAD state is pretty good.\n>\n>That warning olny appears with `git checkout`, not with `git switch --detach`.\n>\n>> There is also a curious side effect.\n>>\n>> If you went into detached, you can go back to attached using\n>> git switch -\n>>\n>> but not back to detached by again doing\n>> git switch -\n>>\n>> Even though you had been there, and that means you had used\n>> --detached, and therefore known what you did.\n>\n>That's definitely a bug.\n\nIn all of this discussion, please be aware that many CI/CD systems use sparse checkout and detached heads as a matter of efficiency and certainty. Please ensure that you are not changing the semantics of existing capabilities when restricting what `git switch` will do. I am concerned about the 280,342 (as of this minute) current Jenkins users who depend on this.\n\nThanks,\nRandall\n\n\n\n"},{"id":"429564","messageId":"dbfa96f0-558e-ccaf-6e34-6d95c43848b5@mfriebe.de","threadId":"56027","inReplyTo":"60e874e1c6845_215320861@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-09T16:51:12Z","receivedAt":"2021-07-09T16:51:18Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 09/07/2021 18:10, Felipe Contreras wrote:\n> Martin wrote:\n>> As for \"git switch -C\"\n>> This should IMHO change to (the 2nd arg, actually depends on the point\n>> \"1\" above)\n>> git switch (-c|-C) []\n>>\n>> I suggest to not call it \"new-branch-name\" because, it might be an\n>> existing name.\n> \n> I think the name is all wrong. As Ævar pointed out --new (-n) is much\n> better. Also it doesn't make much sense to use \"create\" or \"new\" for\n> something that already exists.\n\nThe n versus c issue is IMHO separate. Maybe tiny overlaps.\n\nI see it mostly in the light of -c should be for \"copy\".\n\nOn \"git checkout\" it is \"-b\" for branch. That works, if you perceive \n\"branch\" as a verb. \"The action of branching creates a new branch\".\n\nIf needs must, that would work as \"git switch -b\" to.\n\nActually, \"new\" or \"create\" would make sense in \"git branch\". But in git \nswitch, they actually raise the question \"create what?\" / \"new what?\".\n\n\n> \n> I think you saw a correct issue: `git switch -C` might be used\n> incorrectly, but changing to the documentation would have limited value\n> (and only for the ones that read it).\n> \n> I think if the branch already exists, the user has to be explicit to\n> what he wants to do and use `git switch --reset `\n\nWell, that is the question as what the action is perceived.\nI think the example is wrong, rather than the command.\n\n-c / -C /-n / -N always *c*reate an *n*ew branch. (create and new really \nare the same thing here)\n\nBut if the branch name Foo, is already used?\nWell, it will still be a *new* branch being *created*.\nTo do that it has to remove the name from the old branch. (effectively \nremoving the old branch).\n\n\n>> 3)\n>>\n>> newbbranch versus new-branch versus new_branch\n>>\n>> That is something that just needs to be decided.\n>> \"new_branch\" is in git checkout.\n> \n> I'd rather have , but as I already said, the more ground you try\n> to cover the more impossible it will be to actually land the changes.\n\nWell ok, if you shorten it to one word that solves it too.\nBut for anything that for some reason needs two words, IMHO there should \nbe one style. \"one word\", \"-\" or \"_\".\nCurrently different styles are mixed.\n\n\n>>\n>> Look at\n>> git checkout --force\n>>> --force\n>>> When switching branches, proceed even if the index or the working tree differs from HEAD. This is used to throw away local changes.\n>>\n> \n> All these issues go away if we have:\n> \n> git switch --reset \n> \n> And instead of -C, we have:\n> \n> git switch --new --reset \n> \n> This creates a new branch if it doesn't exist, or if it exists resets\n> it.\n\nNope it does not go away.\n\nAll this has done, is that it no longer is a \"force\" command.\nSo the last bit of warning has just gone.\n\nAnd it still needs to be documented inside the \"git switch\" doc, rather \nthan forwarding the user do yet another doc.\n\nAlso making the user read the \"git reset\" doc does not help, unless we \npoint out that this is a --hard reset, rather than \"modifying the index\".\n\nI would on that account argue that \"git reset --hard/mixed/soft\" should \nbe \"force\" commands.\n\nAnd the \"git reset\" documentation, as well as \"git branch -f\" / git \ncheckout -B\", also miss the information why they are \"force\".\nIt is true, this information can be derived, if one\n- knows the concepts (which one should do)\n- and actually connects the dots (humans do have a tendency to overlook \nthings, especially if they are only indirectly referred to)\n\nSo, I still ask:\n- If \"--force\" to overwrite the work tree can clearly state that change \nto files will be \"thrown away\".\n- Then why can \"force\" re-using an existing branch name not do the same?\n\nAnd that is the same, never mind if we call it -C, -B or --reset.\n\n\n\n\n\n"},{"id":"429565","messageId":"7cb0e152-2ef2-a226-2dbb-f32d19378792@mfriebe.de","threadId":"56027","inReplyTo":"60e8776cdc455_215320852@natae.notmuch","subject":"Re: switch requires --detach [[Re: What actually is a branch]]","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-09T16:54:04Z","receivedAt":"2021-07-09T16:54:09Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 09/07/2021 18:21, Felipe Contreras wrote:\n> Martin wrote:\n>> - add --allow-detach and git config switch.detach allow ?\n> \n> That's a good option, but another one would be to have a core.advanced\n> mode, you turn it on if you are an advanced user.\n\n+1\n\n"},{"id":"429566","messageId":"60e8830b2f6ed_16bcb20836@natae.notmuch","threadId":"56027","inReplyTo":"008701d774e0$d3220f40$79662dc0$@nexbridge.com","subject":"RE: switch requires --detach [[Re: What actually is a branch]]","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-09T17:10:35Z","receivedAt":"2021-07-09T17:10:39Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Randall S. Becker wrote:\n> In all of this discussion, please be aware that many CI/CD systems use\n> sparse checkout and detached heads as a matter of efficiency and\n> certainty. Please ensure that you are not changing the semantics of\n> existing capabilities when restricting what `git switch` will do. I am\n> concerned about the 280,342 (as of this minute) current Jenkins users\n> who depend on this.\n\nI doubt 280,342 Jenkins users depend on `git switch`.\n\nAnd `git help switch`:\n\n THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n\n-- \nFelipe Contreras\n"},{"id":"429570","messageId":"60e88a4b8592f_16bcb2082b@natae.notmuch","threadId":"56027","inReplyTo":"dbfa96f0-558e-ccaf-6e34-6d95c43848b5@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-09T17:41:31Z","receivedAt":"2021-07-09T17:41:35Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 09/07/2021 18:10, Felipe Contreras wrote:\n> > Martin wrote:\n> >> As for \"git switch -C\"\n> >> This should IMHO change to (the 2nd arg, actually depends on the point\n> >> \"1\" above)\n> >> git switch (-c|-C) []\n> >>\n> >> I suggest to not call it \"new-branch-name\" because, it might be an\n> >> existing name.\n> > \n> > I think the name is all wrong. As Ævar pointed out --new (-n) is much\n> > better. Also it doesn't make much sense to use \"create\" or \"new\" for\n> > something that already exists.\n> \n> The n versus c issue is IMHO separate. Maybe tiny overlaps.\n> \n> I see it mostly in the light of -c should be for \"copy\".\n> \n> On \"git checkout\" it is \"-b\" for branch. That works, if you perceive \n> \"branch\" as a verb. \"The action of branching creates a new branch\".\n\nI generally view git commands as verbs. In this case \"checkout\" is the\nverb, and \"branch\" is the direct object.\n\n> Actually, \"new\" or \"create\" would make sense in \"git branch\". But in git \n> switch, they actually raise the question \"create what?\" / \"new what?\".\n\n`git switch` doesn't switch anything other branches. I don't think\n`git switch-branch` would make the command somehow more understendale.\n\n> > I think you saw a correct issue: `git switch -C` might be used\n> > incorrectly, but changing to the documentation would have limited value\n> > (and only for the ones that read it).\n> > \n> > I think if the branch already exists, the user has to be explicit to\n> > what he wants to do and use `git switch --reset `\n> \n> Well, that is the question as what the action is perceived.\n> I think the example is wrong, rather than the command.\n> \n> -c / -C /-n / -N always *c*reate an *n*ew branch. (create and new really \n> are the same thing here)\n> \n> But if the branch name Foo, is already used?\n> Well, it will still be a *new* branch being *created*.\n> To do that it has to remove the name from the old branch. (effectively \n> removing the old branch).\n\nBut it's not removing the name, it's merely changing the head.\n\nI don't particularly mind having -C or -N, I just would not use them\nbecause I like to be explicit. I don't use --new for something that\nalready exists.\n\n> >> 3)\n> >>\n> >> newbbranch versus new-branch versus new_branch\n> >>\n> >> That is something that just needs to be decided.\n> >> \"new_branch\" is in git checkout.\n> > \n> > I'd rather have , but as I already said, the more ground you try\n> > to cover the more impossible it will be to actually land the changes.\n> \n> Well ok, if you shorten it to one word that solves it too.\n> But for anything that for some reason needs two words, IMHO there should \n> be one style. \"one word\", \"-\" or \"_\".\n> Currently different styles are mixed.\n\nI don't see the need for that, would do the trick, no need\nfor hyphens or underscores.\n\n> >> Look at\n> >> git checkout --force\n> >>> --force\n> >>> When switching branches, proceed even if the index or the working tree differs from HEAD. This is used to throw away local changes.\n> >>\n> > \n> > All these issues go away if we have:\n> > \n> > git switch --reset \n> > \n> > And instead of -C, we have:\n> > \n> > git switch --new --reset \n> > \n> > This creates a new branch if it doesn't exist, or if it exists resets\n> > it.\n> \n> Nope it does not go away.\n> \n> All this has done, is that it no longer is a \"force\" command.\n> So the last bit of warning has just gone.\n> \n> And it still needs to be documented inside the \"git switch\" doc, rather \n> than forwarding the user do yet another doc.\n\nYes, but as I said: the documentation writes itself.\n\n -n , --new \n\n Creates a new branch.\n\n --reset \n\n Resets the branch to .\n\n> Also making the user read the \"git reset\" doc does not help, unless we \n> point out that this is a --hard reset, rather than \"modifying the index\".\n\nNobody is suggesting that. --reset refers to the English word \"reset\",\nnot `get reset`.\n\n> So, I still ask:\n> - If \"--force\" to overwrite the work tree can clearly state that change \n> to files will be \"thrown away\".\n> - Then why can \"force\" re-using an existing branch name not do the same?\n\nBecause we would be forcing two things now. I'd rather not overload\nconcepts.\n\nCheers.\n\n-- \nFelipe Contreras"},{"id":"429575","messageId":"ad58bd54-a9dd-59a9-4fce-f90be469cd60@mfriebe.de","threadId":"56027","inReplyTo":"60e88a4b8592f_16bcb2082b@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-09T18:23:54Z","receivedAt":"2021-07-09T18:23:59Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 09/07/2021 19:41, Felipe Contreras wrote:\n> Martin wrote:\n>> Well, that is the question as what the action is perceived.\n>> I think the example is wrong, rather than the command.\n>>\n>> -c / -C /-n / -N always *c*reate an *n*ew branch. (create and new really\n>> are the same thing here)\n>>\n>> But if the branch name Foo, is already used?\n>> Well, it will still be a *new* branch being *created*.\n>> To do that it has to remove the name from the old branch. (effectively\n>> removing the old branch).\n> \n> But it's not removing the name, it's merely changing the head.\n> \n> I don't particularly mind having -C or -N, I just would not use them\n> because I like to be explicit. I don't use --new for something that\n> already exists.\n\nBut that comes down to the \"what is a branch\" discussion.\n\nIt is not creating a new branchname. But it is creating a new branch. \nAnd then the branchname refers to that new branch.\n\nIt changes head, base, and the entire content. That effectively makes it \nnew.\n\nIf you have a 10 year old car that you nicknamed \"speedy\", and I come \nalong and I replace every part (every screw, every whatever...) with a \nbrand new part, would you still call the result a 10 year old car (even \nif (or just because) you still use the nickname) ?\n\n\nUsing \"reset\", it's similar. Except that human language is slopy.\nIf I play WOW, and I reset the game. Actually that is already wrong. I \ndo not reset the game. It is still the same code, the same images.... I \ndo reset my session or status. And after that, I will be in a new \nsession, or have a new status.\n\n- \"creating\" the branch is \"setting (up) the branch\"\n- \"re-setting\" is doing doing this (creation) again.\n\n\n>> Nope it does not go away.\n>>\n>> All this has done, is that it no longer is a \"force\" command.\n>> So the last bit of warning has just gone.\n>>\n>> And it still needs to be documented inside the \"git switch\" doc, rather\n>> than forwarding the user do yet another doc.\n> \n> Yes, but as I said: the documentation writes itself.\n> \n> -n , --new \n> \n> Creates a new branch.\n> \n> --reset \n> \n> Resets the branch to .\n\nAnd that still leaves it to the user to connect the dots, and come to \nthe conclusion that the old branch is no longer holding his valued commits.\n\nWe don't ask the user to go make this sort of \"connecting the dots\", \nwhen he uses force to override changes in his worktree.\n\nWhy?\n\n\n\n>> So, I still ask:\n>> - If \"--force\" to overwrite the work tree can clearly state that change\n>> to files will be \"thrown away\".\n>> - Then why can \"force\" re-using an existing branch name not do the same?\n> \n> Because we would be forcing two things now. \n\nWhich 2 things?\n\nThe worktree overwriting is *not* forced by -C\n\n git switch -C b1 b2\n git checkout -B b1 b2\n\nboth give an error if the worktree has changed files.\n\nThis is only about what happens to the branch.\n\nI.e we force the branchname to point to our new branch.\nAnd that means the branchname no longe points to the old branch, and the \nold branch therefore is removed.\n\n\n\n> I'd rather not overload\n> concepts.\n> \nSorry the concepts are there by whatever the implementation does.\n\nDocumenting them does not overload concepts. If they indeed already are \noverloaded, then documentation does not change that.\n\nBtw, not sure what is overloaded here?\n\n\n\n\n\n"},{"id":"429607","messageId":"87h7h2mqgm.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"57f316cb-850d-706a-592b-4376f240e032@mfriebe.de","subject":"Re: switch requires --detach [[Re: What actually is a branch]]","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-10T10:08:09Z","receivedAt":"2021-07-10T10:08:15Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Martin writes:\n\n> On 09/07/2021 17:08, Felipe Contreras wrote:\n>> and the fact that\n>> `git switch` expects branches is one of the things that bothers me about\n>> it.\n>\n> Ah, good point.\n>\n> I would word it differently though.\n> \"git switch forces the use of --detach if switching to a non branch\"\n>\n> Bit of a twist.\n> It's a nice safety for beginners. I remember when I started, I kept\n> ending up detached. And I had no idea what to do next.\n\nI think it's more because of too technical and thus confusing name for\nit rather than the state itself. In fact this could be described as\n\"being on unnamed branch\", as if HEAD points to a branch with empty\nname, and is not detached in any sense.\n\nIt's nice that once you are on unnamed branch, nothing actually changes,\nso no any mental shift is needed to get out of this \"state\". BTW,\nunnamed branch could probably even start to have entries in the reflog.\n\nOverall, I think Git needs to move into direction of getting rid of\n\"detached head\" in favor of \"unnamed branch\" at least at the UI level.\n\nGetting back to \"git switch\", if the above sounds reasonable, \"--detach\"\nis a bad choice for the option name in the first place.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429608","messageId":"87im1ieaba.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"dbfa96f0-558e-ccaf-6e34-6d95c43848b5@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-10T10:24:09Z","receivedAt":"2021-07-10T10:24:15Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Martin writes:\n\n> On 09/07/2021 18:10, Felipe Contreras wrote:\n>> Martin wrote:\n>>> As for \"git switch -C\"\n>>> This should IMHO change to (the 2nd arg, actually depends on the point\n>>> \"1\" above)\n>>> git switch (-c|-C) []\n>>>\n>>> I suggest to not call it \"new-branch-name\" because, it might be an\n>>> existing name.\n>> I think the name is all wrong. As Ævar pointed out --new (-n) is much\n>> better. Also it doesn't make much sense to use \"create\" or \"new\" for\n>> something that already exists.\n>\n> The n versus c issue is IMHO separate. Maybe tiny overlaps.\n>\n> I see it mostly in the light of -c should be for \"copy\".\n>\n> On \"git checkout\" it is \"-b\" for branch. That works, if you perceive\n> \"branch\" as a verb. \"The action of branching creates a new branch\".\n>\n> If needs must, that would work as \"git switch -b\" to.\n>\n> Actually, \"new\" or \"create\" would make sense in \"git branch\". But in\n> git switch, they actually raise the question \"create what?\" / \"new\n> what?\".\n\nI believe that's because \"git switch\" tries to do too much. \"git switch\"\nshould rather switch between existing branches, and do nothing else. As\nI said once in this discussion already: trouble writing good\ndocumentation is often indication of some flaws in the design.\n\nCreating (a branch) is fundamentally different operation than switching\nto (a branch), and that's why the former doesn't fit into \"git switch\".\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429609","messageId":"3dbe1f6f-1e9d-3bcc-a7b1-4d9cde56bcde@gmail.com","threadId":"56027","inReplyTo":"87im1ieaba.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-07-10T10:37:24Z","receivedAt":"2021-07-10T10:37:31Z","isPatch":false,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 10/07/21 17.24, Sergey Organov wrote:\n> I believe that's because \"git switch\" tries to do too much. \"git switch\"\n> should rather switch between existing branches, and do nothing else. As\n> I said once in this discussion already: trouble writing good\n> documentation is often indication of some flaws in the design.\n> \n> Creating (a branch) is fundamentally different operation than switching\n> to (a branch), and that's why the former doesn't fit into \"git switch\".\n> \n\nSo I prefer your suggestion. Also make `git switch` also switches tags \nor random commits (like `git checkout ` and `git checkout `).\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"429610","messageId":"1bd36aa2-ac90-f7d4-9d48-1aa39159b263@mfriebe.de","threadId":"56027","inReplyTo":"87im1ieaba.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-10T11:05:54Z","receivedAt":"2021-07-10T11:06:06Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 10/07/2021 12:24, Sergey Organov wrote:\n> Martin writes:\n>> Actually, \"new\" or \"create\" would make sense in \"git branch\". But in\n>> git switch, they actually raise the question \"create what?\" / \"new\n>> what?\".\n> \n> I believe that's because \"git switch\" tries to do too much. \"git switch\"\n> should rather switch between existing branches, and do nothing else. As\n> I said once in this discussion already: trouble writing good\n> documentation is often indication of some flaws in the design.\n> \n> Creating (a branch) is fundamentally different operation than switching\n> to (a branch), and that's why the former doesn't fit into \"git switch\".\n> \n\nRight, yes. But creating a branch is often followed by switching to it.\n\nSo this is A shortcuts, that I actually think to be fine.\nIt does add value, as it does speed up a common operation.\n\nOf course you could have\n git create-switch\nor\n git branch-switch\n\nI am not sure, that is really an improvement.\n\n\n\nThere is even discussion to add \"-c\" for \"copy branch + switch\" to git \nswitch.\nWhich I have no personal objection. Only find it regrettable that it \nmeans an incompatible change to -c. (Never mind that git switch is still \n\"experimental\". It has been so for a long time, for many people out \nthere long enough to forget the \"experimental\")\n\nAnd there is even discussion to add \"-m\" move/rename, to git switch.\nOnly that for the latter, most people would not even perceive a rename \nas doing a switch/checkout (technically the branchname in HEAD is \nupdated, I guess).\nSo technically\n git branch -m newname\nshould change the branchname, but NOT update HEAD (detach)?\n(Not sure what it does / not tested)\nIf git branch actually updates HEAD in that case, then \"git switch -m\" \nwould be an identical copy, adding no value, therefore not required.\n"},{"id":"429635","messageId":"87a6mudt9b.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"1bd36aa2-ac90-f7d4-9d48-1aa39159b263@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-10T16:32:32Z","receivedAt":"2021-07-10T16:32:40Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Martin writes:\n\n> On 10/07/2021 12:24, Sergey Organov wrote:\n>> Martin writes:\n>>> Actually, \"new\" or \"create\" would make sense in \"git branch\". But in\n>>> git switch, they actually raise the question \"create what?\" / \"new\n>>> what?\".\n>> I believe that's because \"git switch\" tries to do too much. \"git switch\"\n>> should rather switch between existing branches, and do nothing else. As\n>> I said once in this discussion already: trouble writing good\n>> documentation is often indication of some flaws in the design.\n>> Creating (a branch) is fundamentally different operation than switching\n>> to (a branch), and that's why the former doesn't fit into \"git switch\".\n>> \n>\n> Right, yes. But creating a branch is often followed by switching to it.\n\nYep, but here the creation is the primary operation, not switching, so\nputting this into \"git switch\" looks like design flaw. These 2 actions\nare fine to co-exist in \"git branch\" = \"whatever you want to do to\nbranches\", but not in \"git switch\" == \"wherever you want to switch\".\n\nLogically, there could be something like \"git new\" that does create a\nbranch and then switches there by default, or something like that, say:\n\n git new feature3 --at origin/rc-2 --track\n \nAnd while we are at it, do you guys notice how 2 concepts are mixed in\nGit commands? I mean, the interface seems to mix object-oriented and\naction-oriented commands, most of commands being action-oriented with\nonly a few unfortunate exceptions.\n\nLet me try a short survey:\n\n1. In\n\n git branch ...\n\nis \"branch\" a noun or a verb?\n\n2. In\n\n git merge ...\n\nis \"merge\" a noun or a verb?\n\nTo me, while the latter is obvious, it's verb and specifies the action\nto be performed, the former looks more like \"whatever you want to do\nwith branches\", and thus the \"branch\" is a noun there and the command\nthus is object-oriented.\n\nFrom this POV, to me specifically these 3 commands:\n\n git branch\n git tag\n git sparse-checkout\n\nlook like exceptions which should be eventually obsoleted after their\nfeatures are moved elsewhere, provided Git community is interested in\nregularizing Git interfaces.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429638","messageId":"60e9f28885c5a_7ef2081e@natae.notmuch","threadId":"56027","inReplyTo":"87h7h2mqgm.fsf@osv.gnss.ru","subject":"Re: switch requires --detach [[Re: What actually is a branch]]","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-10T19:18:32Z","receivedAt":"2021-07-10T19:18:48Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Sergey Organov wrote:\n> Martin writes:\n> \n> > On 09/07/2021 17:08, Felipe Contreras wrote:\n> >> and the fact that\n> >> `git switch` expects branches is one of the things that bothers me about\n> >> it.\n> >\n> > Ah, good point.\n> >\n> > I would word it differently though.\n> > \"git switch forces the use of --detach if switching to a non branch\"\n> >\n> > Bit of a twist.\n> > It's a nice safety for beginners. I remember when I started, I kept\n> > ending up detached. And I had no idea what to do next.\n> \n> I think it's more because of too technical and thus confusing name for\n> it rather than the state itself. In fact this could be described as\n> \"being on unnamed branch\", as if HEAD points to a branch with empty\n> name, and is not detached in any sense.\n> \n> It's nice that once you are on unnamed branch, nothing actually changes,\n> so no any mental shift is needed to get out of this \"state\". BTW,\n> unnamed branch could probably even start to have entries in the reflog.\n> \n> Overall, I think Git needs to move into direction of getting rid of\n> \"detached head\" in favor of \"unnamed branch\" at least at the UI level.\n\nI agree. But UI changes in git are pretty much impossible (although not\n100%).\n\n> Getting back to \"git switch\", if the above sounds reasonable, \"--detach\"\n> is a bad choice for the option name in the first place.\n\nTrue. Maybe --unamed.\n\n-- \nFelipe Contreras\n"},{"id":"429639","messageId":"60e9f8d462bd9_7ef20898@natae.notmuch","threadId":"56027","inReplyTo":"ad58bd54-a9dd-59a9-4fce-f90be469cd60@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-10T19:45:24Z","receivedAt":"2021-07-10T19:45:28Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 09/07/2021 19:41, Felipe Contreras wrote:\n> > Martin wrote:\n> >> Well, that is the question as what the action is perceived.\n> >> I think the example is wrong, rather than the command.\n> >>\n> >> -c / -C /-n / -N always *c*reate an *n*ew branch. (create and new really\n> >> are the same thing here)\n> >>\n> >> But if the branch name Foo, is already used?\n> >> Well, it will still be a *new* branch being *created*.\n> >> To do that it has to remove the name from the old branch. (effectively\n> >> removing the old branch).\n> > \n> > But it's not removing the name, it's merely changing the head.\n> > \n> > I don't particularly mind having -C or -N, I just would not use them\n> > because I like to be explicit. I don't use --new for something that\n> > already exists.\n> \n> But that comes down to the \"what is a branch\" discussion.\n> \n> It is not creating a new branchname. But it is creating a new branch. \n> And then the branchname refers to that new branch.\n> \n> It changes head, base, and the entire content. That effectively makes it \n> new.\n\nYes, it is a new branch, but the name doesn't change.\n\n> If you have a 10 year old car that you nicknamed \"speedy\", and I come \n> along and I replace every part (every screw, every whatever...) with a \n> brand new part, would you still call the result a 10 year old car (even \n> if (or just because) you still use the nickname) ?\n\nYeah but you are entering into metaphysics of identity, see the Ship of\nTheseus [1]. By that same logic why are you still called Martin if every\ncell in your body wasn't there when you were originally born?\n\nThese thought experiments are interesting, but philosphers have discused\nabout this for thousands of years and the conclussion is still\nundecided, so I don't think we'll come to a conclussion here.\n\nMoreover, I don't even think it's relevant. We agree that the branch is\na different branch, we agree that the name doesn't change, and we agree\nthat the user doesn't want the name to change. We don't need to enter\ninto a philosophical discussion to see if the name *should* change.\n\n> Using \"reset\", it's similar. Except that human language is slopy.\n> If I play WOW, and I reset the game. Actually that is already wrong. I \n> do not reset the game. It is still the same code, the same images.... I \n> do reset my session or status. And after that, I will be in a new \n> session, or have a new status.\n\nWords mean whatever humans using those words intend them to mean. If\nmost people use the word \"reset\" in a certin way, that's what the word\nmeans. Even if you have a good ontological reason why reset shouldn't be\nused like that, it's used like that.\n\n> - \"creating\" the branch is \"setting (up) the branch\"\n> - \"re-setting\" is doing doing this (creation) again.\n\nResetting is not necesarilly creating again, it can mean setting up\nagain.\n\n> >> Nope it does not go away.\n> >>\n> >> All this has done, is that it no longer is a \"force\" command.\n> >> So the last bit of warning has just gone.\n> >>\n> >> And it still needs to be documented inside the \"git switch\" doc, rather\n> >> than forwarding the user do yet another doc.\n> > \n> > Yes, but as I said: the documentation writes itself.\n> > \n> > -n , --new \n> > \n> > Creates a new branch.\n> > \n> > --reset \n> > \n> > Resets the branch to .\n> \n> And that still leaves it to the user to connect the dots, and come to \n> the conclusion that the old branch is no longer holding his valued commits.\n\nNo. You can add all the explanation you want after \"Resets the branch to\n.\", but most of that explanation would be redundant, because as we\nalready agreed, there's no way to reset the head of a branch without\nchanging the branch.\n\n> >> So, I still ask:\n> >> - If \"--force\" to overwrite the work tree can clearly state that change\n> >> to files will be \"thrown away\".\n> >> - Then why can \"force\" re-using an existing branch name not do the same?\n> > \n> > Because we would be forcing two things now. \n> \n> Which 2 things?\n> \n> The worktree overwriting is *not* forced by -C\n> \n> git switch -C b1 b2\n> git checkout -B b1 b2\n> \n> both give an error if the worktree has changed files.\n> \n> This is only about what happens to the branch.\n> \n> I.e we force the branchname to point to our new branch.\n> And that means the branchname no longe points to the old branch, and the \n> old branch therefore is removed.\n\nIt seems your proposal is to make `git switch -c --force b1 b2` be the same as\n`git switch -C b1 b2`, but that would also make it the same as\n`git switch -C --force b1 b2`. Therefore it would be forcing two things.\n\nOr is your proposal something else?\n\n[1] https://en.wikipedia.org/wiki/Ship_of_Theseus\n\n-- \nFelipe Contreras\n"},{"id":"429640","messageId":"60e9fa5132e14_7ef20849@natae.notmuch","threadId":"56027","inReplyTo":"87im1ieaba.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-10T19:51:45Z","receivedAt":"2021-07-10T19:52:00Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Sergey Organov wrote:\n> Martin writes:\n> \n> > On 09/07/2021 18:10, Felipe Contreras wrote:\n> >> Martin wrote:\n> >>> As for \"git switch -C\"\n> >>> This should IMHO change to (the 2nd arg, actually depends on the point\n> >>> \"1\" above)\n> >>> git switch (-c|-C) []\n> >>>\n> >>> I suggest to not call it \"new-branch-name\" because, it might be an\n> >>> existing name.\n> >> I think the name is all wrong. As Ævar pointed out --new (-n) is much\n> >> better. Also it doesn't make much sense to use \"create\" or \"new\" for\n> >> something that already exists.\n> >\n> > The n versus c issue is IMHO separate. Maybe tiny overlaps.\n> >\n> > I see it mostly in the light of -c should be for \"copy\".\n> >\n> > On \"git checkout\" it is \"-b\" for branch. That works, if you perceive\n> > \"branch\" as a verb. \"The action of branching creates a new branch\".\n> >\n> > If needs must, that would work as \"git switch -b\" to.\n> >\n> > Actually, \"new\" or \"create\" would make sense in \"git branch\". But in\n> > git switch, they actually raise the question \"create what?\" / \"new\n> > what?\".\n> \n> I believe that's because \"git switch\" tries to do too much. \"git switch\"\n> should rather switch between existing branches, and do nothing else.\n\nI don't know if it's trying to do too much. I know `git checkout` is\ntrying to do too much, and I've been trying to use `git switch` instead\nfor a while. I often create branches and switch to them using\n`git switch -c` (which I think should be `git switch -n`).\n\nIn my mind it's \"switch to a new branch\".\n\nSo, how would I do this operation (create a new branch and switch to\nit), without using `git checkout` or `git switch -c`?\n\n> As I said once in this discussion already: trouble writing good\n> documentation is often indication of some flaws in the design.\n\nCompletely agree. But I believe the difficulty is in the semantics of\nwhat a branch means in git, not anything to do with `git switch` per se.\n\n> Creating (a branch) is fundamentally different operation than switching\n> to (a branch), and that's why the former doesn't fit into \"git switch\".\n\nNot in my mind. Instead of switching to an existing branch, I'm switching\nto a new branch, which is easily understood by\n`git switch --new branch`.\n\n-- \nFelipe Contreras"},{"id":"429641","messageId":"60e9fc5b83c2a_7ef20880@natae.notmuch","threadId":"56027","inReplyTo":"1bd36aa2-ac90-f7d4-9d48-1aa39159b263@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-10T20:00:27Z","receivedAt":"2021-07-10T20:00:35Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> There is even discussion to add \"-c\" for \"copy branch + switch\" to git \n> switch.\n> Which I have no personal objection. Only find it regrettable that it \n> means an incompatible change to -c. (Never mind that git switch is still \n> \"experimental\". It has been so for a long time, for many people out \n> there long enough to forget the \"experimental\")\n\nThis is relative.\n\n`git switch` has existed for 1.9 years. I've been using git for about 15\nyears, so that's 13% of the time (although I've been using it even less\ntime than that). I understand that for more recent users this might seem\nlike a long time, but it isn't.\n\nGit UI development is dead slow.\n\n-- \nFelipe Contreras\n"},{"id":"429642","messageId":"6f43b36b-abe1-41f2-6138-e820c974b1bd@mfriebe.de","threadId":"56027","inReplyTo":"60e9f8d462bd9_7ef20898@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-10T20:07:41Z","receivedAt":"2021-07-10T20:07:47Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 10/07/2021 21:45, Felipe Contreras wrote:\n> Martin wrote:\n> No. You can add all the explanation you want after \"Resets the branch to\n> .\", but most of that explanation would be redundant, because as we\n> already agreed, there's no way to reset the head of a branch without\n> changing the branch.\n\nBy that logic a lot of explanations are redundant, because on some \nlever, if every user thinks far enough lots of things can be concluded.\n\n From the docs (and similar on git checkout)\n> --force\n> \n> An alias for --discard-changes.\n> --discard-changes\n> \n> Proceed even if the index or the working tree differs from HEAD.\n> Both the index and working tree are restored to match the switching \n> target. If --recurse-submodules is specified, submodule content is \n> also restored to match the switching target. This is used to throw\n> away local changes.\n\nIf the working tree is made to match the target, then it can not retain \nlocal changes. That can be concluded.\nYet, it is explicitly mentioned.\n\nDoes it really hurt to mention it?\nPeople overlook details that to others are blaring obvious.\nI agree, we can not mention every potential possibility. But as a \ngeneral rule, if data could be lost, then a mention (an explicit \nmention) should be made.\n\nYes, commits may be hold by the reflog. Except the reflog is optional. \nAnd more to the point, the reflog is unknown to plenty of people (never \nmind if they should know it, they do not) So the possibility of loss is \nrather real.\n\nBut anyway.\nI brought forward my idea. I explained my reasoning.\nIf it (this part) is downvoted/rejected then that it how it is.\n\n\nThere still is the idea to replace the word \"branch\" by \"branch name\" in \nsome parts of the git switch documentation.\n\n\n\n>>>> So, I still ask:\n>>>> - If \"--force\" to overwrite the work tree can clearly state that change\n>>>> to files will be \"thrown away\".\n>>>> - Then why can \"force\" re-using an existing branch name not do the same?\n>>>\n>>> Because we would be forcing two things now.\n>>\n>> Which 2 things?\n>>\n>> The worktree overwriting is *not* forced by -C\n>>\n>> git switch -C b1 b2\n>> git checkout -B b1 b2\n>>\n>> both give an error if the worktree has changed files.\n>>\n>> This is only about what happens to the branch.\n>>\n>> I.e we force the branchname to point to our new branch.\n>> And that means the branchname no longe points to the old branch, and the\n>> old branch therefore is removed.\n> \n> It seems your proposal is to make `git switch -c --force b1 b2` be the same as\n> `git switch -C b1 b2`, but that would also make it the same as\n> `git switch -C --force b1 b2`. Therefore it would be forcing two things.\n> \n> Or is your proposal something else?\n> \n\nNo. I definitely want to keep those 2 apart from each other.\n\nFor each force-needing action, you should have to specify it's own force \nflag.\n\nI do not want to change the behaviour on that part.\n\nI only compared the\n- doc of \"-f\" for worktree overwrites\nwith the\n- doc -C for branch overwrites.\n\nAnd I found that the former makes explicit mention of what can be lost, \nthe latter leaves it to be concluded.\n\n"},{"id":"429643","messageId":"60e9ff4430c57_7ef20815@natae.notmuch","threadId":"56027","inReplyTo":"87a6mudt9b.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-10T20:12:52Z","receivedAt":"2021-07-10T20:12:56Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Sergey Organov wrote:\n> Martin writes:\n> \n> > On 10/07/2021 12:24, Sergey Organov wrote:\n> >> Martin writes:\n> >>> Actually, \"new\" or \"create\" would make sense in \"git branch\". But in\n> >>> git switch, they actually raise the question \"create what?\" / \"new\n> >>> what?\".\n> >> I believe that's because \"git switch\" tries to do too much. \"git switch\"\n> >> should rather switch between existing branches, and do nothing else. As\n> >> I said once in this discussion already: trouble writing good\n> >> documentation is often indication of some flaws in the design.\n> >> Creating (a branch) is fundamentally different operation than switching\n> >> to (a branch), and that's why the former doesn't fit into \"git switch\".\n> >> \n> >\n> > Right, yes. But creating a branch is often followed by switching to it.\n> \n> Yep, but here the creation is the primary operation, not switching, so\n> putting this into \"git switch\" looks like design flaw. These 2 actions\n> are fine to co-exist in \"git branch\" = \"whatever you want to do to\n> branches\", but not in \"git switch\" == \"wherever you want to switch\".\n\nI don't see the logic in here.\n\n git branch topic # here 'branch' is the verb\n git switch topic # here 'switch' is the verb\n\nNow, if you want to do both at the same time the logical options are:\n\n git branch --switch topic # here '--switch' is an adverb\n git switch --new topic # here '--new' is an adverb\n\nThe former reads like gibberish to me: \"git, branch off in a 'switch'\nway\".\n\nThe latter makes perfect sense: \"git, switch to a branch in a 'new' way\".\n\n> Logically, there could be something like \"git new\" that does create a\n> branch and then switches there by default, or something like that, say:\n> \n> git new feature3 --at origin/rc-2 --track\n\nHere the the verb is clear, but not the direct object, a \"new\" what?\nCouldn't it be a tag? Or a commit? Or a remote? Or a worktree? Or a\nbisect? Or a submodule?\n\nIt's too ambigous.\n\n> And while we are at it, do you guys notice how 2 concepts are mixed in\n> Git commands? I mean, the interface seems to mix object-oriented and\n> action-oriented commands, most of commands being action-oriented with\n> only a few unfortunate exceptions.\n> \n> Let me try a short survey:\n> \n> 1. In\n> \n> git branch ...\n> \n> is \"branch\" a noun or a verb?\n\nBoth.\n\n> 2. In\n> \n> git merge ...\n> \n> is \"merge\" a noun or a verb?\n\nVerb.\n\n> To me, while the latter is obvious, it's verb and specifies the action\n> to be performed, the former looks more like \"whatever you want to do\n> with branches\", and thus the \"branch\" is a noun there and the command\n> thus is object-oriented.\n\nI agree, and I did have indeed noticed the inconsistency. But there's\nanother category of commands that receive subcommands, like:\n\n git remote $subcommand\n git worktree $subcommand\n git bisect $subcommand\n\nIn my opinion `git branch` fits more these subcommand commands, and it\nwas a mistake to make the subcommands options, it should be:\n\n git branch list\n git branch new\n git branch set-upstream\n git branch move\n ...\n\nNow the verb is crystal-clear.\n\n-- \nFelipe Contreras\n"},{"id":"429645","messageId":"60ea07e3495e8_7ef2081d@natae.notmuch","threadId":"56027","inReplyTo":"6f43b36b-abe1-41f2-6138-e820c974b1bd@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-10T20:49:39Z","receivedAt":"2021-07-10T20:49:47Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 10/07/2021 21:45, Felipe Contreras wrote:\n> > Martin wrote:\n> > No. You can add all the explanation you want after \"Resets the branch to\n> > .\", but most of that explanation would be redundant, because as we\n> > already agreed, there's no way to reset the head of a branch without\n> > changing the branch.\n> \n> By that logic a lot of explanations are redundant, because on some \n> lever, if every user thinks far enough lots of things can be concluded.\n\nYes. And that's what a good writer aims for: to minimize the number of\nwords needed for the vast majority of readers to understand the point.\n\nThe more work you as a writer put into a sentence, the less work\nhundreds or thousands of readers have to do while reading that sentence.\n\nRendundancy is only good when you are trying to reach a certain\nword count for a university essay.\n\n> From the docs (and similar on git checkout)\n> > --force\n> > \n> > An alias for --discard-changes.\n> > --discard-changes\n> > \n> > Proceed even if the index or the working tree differs from HEAD.\n> > Both the index and working tree are restored to match the switching \n> > target. If --recurse-submodules is specified, submodule content is \n> > also restored to match the switching target. This is used to throw\n> > away local changes.\n\nThere's no adjective I can use for the official git documentation that\nisn't crass, so let's just say that I find it extremelly lacking.\n\nThat paragraph above is a great example: it's a) hard to read, b)\nunecessarily verbose, c) is wrongly ordered, d) redundant, and e) not\neven correct.\n\n> If the working tree is made to match the target, then it can not retain \n> local changes. That can be concluded.\n> Yet, it is explicitly mentioned.\n> \n> Does it really hurt to mention it?\n\nYes it does.\n\nTime is the most precious resource we all have. We should not waste the\nmost precious resource of our readers.\n\n Throw away local changes.\n\nThat does a much better job.\n\nIf you want to be more explicit, you can add a bit more information:\n\n Throw away local changes either in the staging area or the working\n tree.\n\nWhy does the user have to know what HEAD is? And why does it matter that\nthe staging area is held in a file called \"index\"?\n\nThe current explanation is just bad.\n\n\nBut as I said, if you want to replicate the current style of the\ndocumentation, go ahead, but it would be pretty much a bloated version\nof \"resets the branch to \".\n\n> But anyway.\n> I brought forward my idea. I explained my reasoning.\n> If it (this part) is downvoted/rejected then that it how it is.\n\nIt's not a matter of consensus. There are proposals where literally\neveryone is in favor, and yet they are never merged.\n\nThere's only one person you need to convince.\n\nSo, what I suggest you to do is take into consideration all we have\ndiscussed and send another patch, because that's ultimately all that\nmatters. Moreover, it usually happens to me that while I write the patch\nis when finally the previously-discussed ideas start to click.\n\n> >>>> So, I still ask:\n> >>>> - If \"--force\" to overwrite the work tree can clearly state that change\n> >>>> to files will be \"thrown away\".\n> >>>> - Then why can \"force\" re-using an existing branch name not do the same?\n> >>>\n> >>> Because we would be forcing two things now.\n> >>\n> >> Which 2 things?\n> >>\n> >> The worktree overwriting is *not* forced by -C\n> >>\n> >> git switch -C b1 b2\n> >> git checkout -B b1 b2\n> >>\n> >> both give an error if the worktree has changed files.\n> >>\n> >> This is only about what happens to the branch.\n> >>\n> >> I.e we force the branchname to point to our new branch.\n> >> And that means the branchname no longe points to the old branch, and the\n> >> old branch therefore is removed.\n> > \n> > It seems your proposal is to make `git switch -c --force b1 b2` be the same as\n> > `git switch -C b1 b2`, but that would also make it the same as\n> > `git switch -C --force b1 b2`. Therefore it would be forcing two things.\n> > \n> > Or is your proposal something else?\n> > \n> \n> No. I definitely want to keep those 2 apart from each other.\n> \n> For each force-needing action, you should have to specify it's own force \n> flag.\n\nOK, but I don't see the concrete proposal. What would be the flag that\nmakes -c \"forceful\"?\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"429647","messageId":"43b8d0bb-67f3-11dd-ec31-e102ce8e3b31@mfriebe.de","threadId":"56027","inReplyTo":"60ea07e3495e8_7ef2081d@natae.notmuch","subject":"Naming the --forec option [[Re: PATCH: improve git switch documentation]]","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-10T22:13:40Z","receivedAt":"2021-07-10T22:13:47Z","isPatch":true,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 10/07/2021 22:49, Felipe Contreras wrote:\n> Martin wrote:\n>> For each force-needing action, you should have to specify it's own force \n>> flag. >\n > OK, but I don't see the concrete proposal. What would be the\n > flag that\n > makes -c \"forceful\"?\n >\n\nWell that starts yet another topic.\n\nAt the moment, it is\n --force-create which is absorbing the flag into the option.\n\nAnd by (apparent) convention it also is the uppercasing of the option\n -C\nsame as the uppercasing of the -B in checkout.\n\nI am not really sure if the uppercasing is the best idea.\nIf your suggestion \"core.advanced \" were to come, I would vote that \nuppercase single letter force options should be restricted to advanced.\n\n\nIf -n is introduced, we can think about what to do about -N.\nShould the --force-* style be kept?\n --force-new\n -N\n\nOr the (unfortunate? / see below ) \"--discard-changes\" style:\n --discard-existing-branch -n \n\nI am against using --reset instead of --force-new.\nAt least I can say, if I use \"-N\", I want a *new* branch. I don't care \nabout any old branch under that name.\n\nAlso \"--reset\" does not have the same alerting properties to me, as \n\"force\" or \"discard\" have.\nThis may be my English, but to me \"reset\" does not have the same \nalerting property.\n\n\n\n\nThe general problem is, if there is more than one force-needing action, \nthen which one does -f act on?\n\nAny force-needing action, that only applies with another option (such as \n-N) can have a --force-*. So the plain -f is not used for it.\n\nBut, what if more than one force-needing event can happen (not just \nswitch, but any command), even without any extra options? (May not yet \nbe the case / not checked).\n\ngit switch has attempted to solve that.\nThe result IMHO is a disaster.\n\"-f\" / \"--force\" is made an alias in favour for\n --discard-changes\nWhat changes?\n\n\n\n"},{"id":"429648","messageId":"30e4c874-6b87-b03d-fa33-fde5b7e50b2a@mfriebe.de","threadId":"56027","inReplyTo":"60ea07e3495e8_7ef2081d@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-10T22:13:38Z","receivedAt":"2021-07-10T22:13:47Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 10/07/2021 22:49, Felipe Contreras wrote:\n> Martin wrote:\n>> From the docs (and similar on git checkout)\n>>> --force\n>>>\n>>> An alias for --discard-changes.\n>>> --discard-changes\n>>>\n>>> Proceed even if the index or the working tree differs from HEAD.\n>>> Both the index and working tree are restored to match the switching\n>>> target. If --recurse-submodules is specified, submodule content is\n>>> also restored to match the switching target. This is used to throw\n>>> away local changes.\n....\n\n>> If the working tree is made to match the target, then it can not retain\n>> local changes. That can be concluded.\n>> Yet, it is explicitly mentioned.\n>>\n>> Does it really hurt to mention it?\n> \n> Yes it does.\n> \n> Time is the most precious resource we all have. We should not waste the\n> most precious resource of our readers.\n> \n> Throw away local changes.\n> \n> That does a much better job.\n> \n> If you want to be more explicit, you can add a bit more information:\n> \n> Throw away local changes either in the staging area or the working\n> tree.\n> \n> Why does the user have to know what HEAD is? And why does it matter that\n> the staging area is held in a file called \"index\"?\n> \n> The current explanation is just bad.\n\nTime is precious, but to really save on it, you have to invest some of it.\n\nAbout the HEAD/index stuff => that was not at all related to the point I \nwas making.\nBut I agree that bit can be shortened\n\nThe thing that I was pointing out, is the last sentence only.\n > This is used to throw away local changes.\n\nBut even that can be reduced to your proposal\n > Throw away local changes.\n\nIt still supports my point. It does state explicitly that data is (or \ncan be) thrown away.\n\n\nNow, if that can be stated on this option, then all I ask is to add a \nsimilar statement (as short as possible) to \"-C\".\nIt should indicate that *commit* may be *dropped\".\nFind a better word for dropped: lost, unreachable, removed.....\n\nCurrently only the branch is mentioned.\nCurrently nothing does explicitly say that *commits* can be affected.\n\nAt the end of the current or rewritten \"-C\" doc, add:\n > This can drop commits\n\n4 words. All that is needed.\n\n\n\n> There's only one person you need to convince.\n> \n> So, what I suggest you to do is take into consideration all we have\n> discussed and send another patch, because that's ultimately all that\n> matters. Moreover, it usually happens to me that while I write the patch\n> is when finally the previously-discussed ideas start to click.\n\nWell, I will see to make some time and put something together.\nMight be a bit before I get to it, but that gives some time to think about.\n\n"},{"id":"429649","messageId":"60ea2ad64878_2a692084e@natae.notmuch","threadId":"56027","inReplyTo":"43b8d0bb-67f3-11dd-ec31-e102ce8e3b31@mfriebe.de","subject":"RE: Naming the --forec option [[Re: PATCH: improve git switch documentation]]","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-10T23:18:46Z","receivedAt":"2021-07-10T23:18:52Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 10/07/2021 22:49, Felipe Contreras wrote:\n> > Martin wrote:\n> >> For each force-needing action, you should have to specify it's own force \n> >> flag. >\n> > OK, but I don't see the concrete proposal. What would be the\n> > flag that\n> > makes -c \"forceful\"?\n> >\n> \n> Well that starts yet another topic.\n> \n> At the moment, it is\n> --force-create which is absorbing the flag into the option.\n> \n> And by (apparent) convention it also is the uppercasing of the option\n> -C\n> same as the uppercasing of the -B in checkout.\n> \n> I am not really sure if the uppercasing is the best idea.\n\nMe neither, and it's not something I generally use.\n\n> If your suggestion \"core.advanced \" were to come, I would vote that \n> uppercase single letter force options should be restricted to advanced.\n\nI would not count on it. I suggested core.mode back in 2013 [1], so...\n\n> If -n is introduced, we can think about what to do about -N.\n> Should the --force-* style be kept?\n> --force-new\n> -N\n> \n> Or the (unfortunate? / see below ) \"--discard-changes\" style:\n> --discard-existing-branch -n \n> \n> I am against using --reset instead of --force-new.\n\nThat's OK, and in fact I can see how '--reset --new' is clunky, I'm just\nsaying it is a possibility. But the main point is that something like\n`git switch --reset` is missing, although `git switch --move` would\nprobably do the trick.\n\n> At least I can say, if I use \"-N\", I want a *new* branch. I don't care \n> about any old branch under that name.\n\nRight, I would as well, but in fact I would expect the same from -n\n(although I can see how a newbie might not).\n\n> Also \"--reset\" does not have the same alerting properties to me, as \n> \"force\" or \"discard\" have.\n> This may be my English, but to me \"reset\" does not have the same \n> alerting property.\n\nOK, maybe it's a language issue. I'm not a native English speaker, my\nmother tongue is Spanish, but I'm pretty sure my understanding of\n\"reset\" is what most people understand: set again.\n\nUsing Merriam Webster [2]:\n\n 1: to set again or anew\n 2: to change the reading of often to zero\n\nAnd there's plenty of corroboration; reorder: order again (whatever\norder you had is lost), reassign: assign again (whatever assignment you\nhad is gone), replay: play again (whatever you were playing is gone),\nand so on.\n\n> The general problem is, if there is more than one force-needing action, \n> then which one does -f act on?\n> \n> Any force-needing action, that only applies with another option (such as \n> -N) can have a --force-*. So the plain -f is not used for it.\n> \n> But, what if more than one force-needing event can happen (not just \n> switch, but any command), even without any extra options? (May not yet \n> be the case / not checked).\n> \n> git switch has attempted to solve that.\n> The result IMHO is a disaster.\n> \"-f\" / \"--force\" is made an alias in favour for\n> --discard-changes\n> What changes?\n\nI see.\n\nSo *if* --force was not an alias for --discard-changes, then this would\nmake sense:\n\n git switch --new --force topic\n\nIt would _force_ the creation of a _new_ branch called \"topic\".\n\nIs this close to what you are thinking?\n\n[1] https://lore.kernel.org/git/1379426871-6823-1-git-send-email-felipe.contreras@gmail.com/\n[2] https://www.merriam-webster.com/dictionary/reset\n\n-- \nFelipe Contreras\n"},{"id":"429651","messageId":"60ea2eb562f26_2a69208e8@natae.notmuch","threadId":"56027","inReplyTo":"30e4c874-6b87-b03d-fa33-fde5b7e50b2a@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-10T23:35:17Z","receivedAt":"2021-07-10T23:35:24Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 10/07/2021 22:49, Felipe Contreras wrote:\n> > Martin wrote:\n> >> From the docs (and similar on git checkout)\n> >>> --force\n> >>>\n> >>> An alias for --discard-changes.\n> >>> --discard-changes\n> >>>\n> >>> Proceed even if the index or the working tree differs from HEAD.\n> >>> Both the index and working tree are restored to match the switching\n> >>> target. If --recurse-submodules is specified, submodule content is\n> >>> also restored to match the switching target. This is used to throw\n> >>> away local changes.\n> ....\n> \n> >> If the working tree is made to match the target, then it can not retain\n> >> local changes. That can be concluded.\n> >> Yet, it is explicitly mentioned.\n> >>\n> >> Does it really hurt to mention it?\n> > \n> > Yes it does.\n> > \n> > Time is the most precious resource we all have. We should not waste the\n> > most precious resource of our readers.\n> > \n> > Throw away local changes.\n> > \n> > That does a much better job.\n> > \n> > If you want to be more explicit, you can add a bit more information:\n> > \n> > Throw away local changes either in the staging area or the working\n> > tree.\n> > \n> > Why does the user have to know what HEAD is? And why does it matter that\n> > the staging area is held in a file called \"index\"?\n> > \n> > The current explanation is just bad.\n> \n> Time is precious, but to really save on it, you have to invest some of it.\n\nSure.\n\n> About the HEAD/index stuff => that was not at all related to the point I \n> was making.\n> But I agree that bit can be shortened\n> \n> The thing that I was pointing out, is the last sentence only.\n> > This is used to throw away local changes.\n> \n> But even that can be reduced to your proposal\n> > Throw away local changes.\n> \n> It still supports my point. It does state explicitly that data is (or \n> can be) thrown away.\n\nOK, yeah, it does state explicitly that data is thrown away, but it's\nthe *last* sentence, when it should be the first, and everything else is\nredundant.\n\n> Now, if that can be stated on this option, then all I ask is to add a \n> similar statement (as short as possible) to \"-C\".\n> It should indicate that *commit* may be *dropped\".\n> Find a better word for dropped: lost, unreachable, removed.....\n> \n> Currently only the branch is mentioned.\n> Currently nothing does explicitly say that *commits* can be affected.\n> \n> At the end of the current or rewritten \"-C\" doc, add:\n> > This can drop commits\n> \n> 4 words. All that is needed.\n\nOK. I'm not opposed to that, that would definitely be an improvement\nfrom the current text.\n\nWhat I'm saying is that if we are trying to improve the text, it would\nbehoove us to consider all other options, and instead if adding a note\nat the end (which is correct), reconsider the whole thing to *start*\nwith what's important:\n\nInstead of this:\n\n -C ::\n --force-create ::\n Similar to `--create` except that if `` already\n exists, it will be reset to ``. This is a\n convenient shortcut for:\n +\n ------------\n $ git branch -f \n $ git switch \n ------------\n\nDo this:\n\n -N ::\n Create a new branch like '--new', but if it already exists reset it\n like '--reset'.\n\nI don't know how is that unclear in any way.\n\n> > There's only one person you need to convince.\n> > \n> > So, what I suggest you to do is take into consideration all we have\n> > discussed and send another patch, because that's ultimately all that\n> > matters. Moreover, it usually happens to me that while I write the patch\n> > is when finally the previously-discussed ideas start to click.\n> \n> Well, I will see to make some time and put something together.\n> Might be a bit before I get to it, but that gives some time to think about.\n\nTake your time. One of the good things about open source is that there's\nno rush.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"429660","messageId":"e9c2b9cd-edfb-cbed-9638-382a6b0da59b@mfriebe.de","threadId":"56027","inReplyTo":"60ea2ad64878_2a692084e@natae.notmuch","subject":"Re: Naming the --forec option [[Re: PATCH: improve git switch documentation]]","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-11T00:39:38Z","receivedAt":"2021-07-11T00:39:43Z","isPatch":true,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 11/07/2021 01:18, Felipe Contreras wrote:\n\n> That's OK, and in fact I can see how '--reset --new' is clunky, I'm just\n> saying it is a possibility. But the main point is that something like\n> `git switch --reset` is missing, although `git switch --move` would\n> probably do the trick.\n\nHow would \"git switch --reset\" be different from \"git switch -N\" ?\n\n\"--move\" is problematic.\n- it reminds me of moving the commits. I.e. rebase.\n- it actually stands for \"rename\" (in git branch -m).\n\nThe apparent idea: \"move the branch under a new name\"\nBut the branch (base..head) itself stays where it is.\n\"rename\" would be so much more intuitive to me.\n\n\n\n>> At least I can say, if I use \"-N\", I want a *new* branch. I don't care\n>> about any old branch under that name.\n> \n> Right, I would as well, but in fact I would expect the same from -n\n> (although I can see how a newbie might not).\n> \nThat's why we have to keep in mind that -N is really --force-new.\n\n A non-force option should not lead to data loss.\n\nOr if something can be lost, then \"force\" needs to be used.\nIf the branch-name already points to a branch then of that branch, you \nstand to loose:\n- the branch boundaries (base..head)\n- in some cases, (some of) the commits hold by it.\n\nSo by convention a simple \"-n\" is protecting me from that.\nIMHO that should be expected.\n\n\n>> Also \"--reset\" does not have the same alerting properties to me, as\n>> \"force\" or \"discard\" have.\n>> This may be my English, but to me \"reset\" does not have the same\n>> alerting property.\n> \n> OK, maybe it's a language issue. I'm not a native English speaker, my\n> mother tongue is Spanish, but I'm pretty sure my understanding of\n> \"reset\" is what most people understand: set again.\n\nI am German. And yes \"set again\" (sometimes \"restart\", but that does not \nmatter here)\n\nIf a branch is set, as base and head. Then \"reset\" means to set those \ntwo again.\n\n \"set again\" => They will still be there.\n (changed indeed, but there)\n\nThe commits hold by that branch, are not \"set again\".\nThey may become unreachable.\n\nThe word \"reset\" gives no indication on knock on effects.\nHowever, I prefer if those effects are made clear.\n\n > meriam webster\nQuite some of the examples are \"put back into working order\"\n(broken leg / circuit breaker => reset does not loose anything)\n\nOthers are restart (at zero) \"reset an odometer\".\nTo me personally the emphasis is the \"start again\", the loss of the \nprevious value is a side effect.\n\nMaybe others will take see \"loss\" part as more prominent.\nThe question then is, how many might not be that wary of the potential loss?\n\n\n> \n> So *if* --force was not an alias for --discard-changes, then this would\n> make sense:\n> \n> git switch --new --force topic\n> \n> It would _force_ the creation of a _new_ branch called \"topic\".\n> \n> Is this close to what you are thinking?\n\nNo, again no. I said \"I want them to be separate force flags\"\n\nAs long as we have the unspecific \"--force\" this must be limited to \nevent *not* triggered by added options.\n\nThat is\n git switch foo\n\nis not forceful, therefore not allowed to destroy data.\nHence it can not overwrite local changes.\nSo --force applies to that.\n\nNow if you were currently detached, and made new commits while detached, \nthen\n git switch foo\nwould loose those commits.\nHypothetical, that could require force.\n\nAnd like the first example it is part of the default behaviour. No \noptions are given.\n\nBut then using the same --force to force something else would be bad.\nSo then we need --force-discard-local-changed and \n--force-unlink-detached-commit\n\n\ngit -n newbranch commit\nis not default behaviour. It is triggered by the -n option.\nIf this endangers any data (other than what is covered by default \ncases), then this always needs its own force.\nAnd it has --force-new\n\n\nIt is possible, but I dislike it very much to define that\n--force affects the next option that follows.\n\nSo that, thin is -N\n git switch --force --new\n\nBut those are not\n git switch --new --force\n git switch --force - --new // the single dash separates the force\n\nI do not like that idea...\n"},{"id":"429670","messageId":"878s2dgu4d.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"30e4c874-6b87-b03d-fa33-fde5b7e50b2a@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-11T07:57:54Z","receivedAt":"2021-07-11T07:59:37Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Martin writes:\n\n\n[...]\n\n> Currently only the branch is mentioned.\n> Currently nothing does explicitly say that *commits* can be affected.\n\nCommits cannot be immediately affected. One of the most essential\nfeatures of Git is that commits could only be affected (deleted) by\ngarbage collection. That's what makes Git so nicely safe in operation.\n\nIt'd be unfortunate to have statements in the manual pages that\ncontradict this.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429671","messageId":"874kd1gr0q.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"60e9ff4430c57_7ef20815@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-11T09:04:53Z","receivedAt":"2021-07-11T09:05:00Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Felipe Contreras writes:\n\n> Sergey Organov wrote:\n>> Martin writes:\n>> \n>> > On 10/07/2021 12:24, Sergey Organov wrote:\n>> >> Martin writes:\n>> >>> Actually, \"new\" or \"create\" would make sense in \"git branch\". But in\n>> >>> git switch, they actually raise the question \"create what?\" / \"new\n>> >>> what?\".\n>> >> I believe that's because \"git switch\" tries to do too much. \"git switch\"\n>> >> should rather switch between existing branches, and do nothing else. As\n>> >> I said once in this discussion already: trouble writing good\n>> >> documentation is often indication of some flaws in the design.\n>> >> Creating (a branch) is fundamentally different operation than switching\n>> >> to (a branch), and that's why the former doesn't fit into \"git switch\".\n>> >> \n>> >\n>> > Right, yes. But creating a branch is often followed by switching to it.\n>> \n>> Yep, but here the creation is the primary operation, not switching, so\n>> putting this into \"git switch\" looks like design flaw. These 2 actions\n>> are fine to co-exist in \"git branch\" = \"whatever you want to do to\n>> branches\", but not in \"git switch\" == \"wherever you want to switch\".\n>\n> I don't see the logic in here.\n>\n> git branch topic # here 'branch' is the verb\n\nNot to me. I assumed the \"branch\" is always a noun in \"git branch\", and\nthe actual meaning of this command is:\n\n git branch [create|new] topic\n\nI.e., creation just being the default action taken on the branch.\n\n> git switch topic # here 'switch' is the verb\n\nYep.\n\n>\n> Now, if you want to do both at the same time the logical options are:\n>\n> git branch --switch topic # here '--switch' is an adverb\n> git switch --new topic # here '--new' is an adverb\n\nYes, we can (and do) shove it into the \"git switch\", but \"git new\" would\nbe better design.\n\n>\n> The former reads like gibberish to me: \"git, branch off in a 'switch'\n> way\".\n>\n> The latter makes perfect sense: \"git, switch to a branch in a 'new' way\".\n>\n>> Logically, there could be something like \"git new\" that does create a\n>> branch and then switches there by default, or something like that, say:\n>> \n>> git new feature3 --at origin/rc-2 --track\n>\n> Here the the verb is clear, but not the direct object, a \"new\" what?\n> Couldn't it be a tag? Or a commit? Or a remote? Or a worktree? Or a\n> bisect? Or a submodule?\n\nYes, it could be anything. The above is written in an assumption that\ndefault object for \"git new\" is branch.\n\n>\n> It's too ambigous.\n\nYep. The explicit mode should have been:\n\n git new branch feature3 --at origin/rc-2 --track\n\n\n>\n>> And while we are at it, do you guys notice how 2 concepts are mixed in\n>> Git commands? I mean, the interface seems to mix object-oriented and\n>> action-oriented commands, most of commands being action-oriented with\n>> only a few unfortunate exceptions.\n>> \n>> Let me try a short survey:\n>> \n>> 1. In\n>> \n>> git branch ...\n>> \n>> is \"branch\" a noun or a verb?\n>\n> Both.\n\nNo, it's rather noun plus lacking subcommand, sometimes making it look\nlike verb :)\n\n>\n>> 2. In\n>> \n>> git merge ...\n>> \n>> is \"merge\" a noun or a verb?\n>\n> Verb.\n>\n>> To me, while the latter is obvious, it's verb and specifies the action\n>> to be performed, the former looks more like \"whatever you want to do\n>> with branches\", and thus the \"branch\" is a noun there and the command\n>> thus is object-oriented.\n>\n> I agree, and I did have indeed noticed the inconsistency. But there's\n> another category of commands that receive subcommands, like:\n>\n> git remote $subcommand\n> git worktree $subcommand\n> git bisect $subcommand\n>\n> In my opinion `git branch` fits more these subcommand commands, and it\n> was a mistake to make the subcommands options, it should be:\n>\n> git branch list\n> git branch new\n> git branch set-upstream\n> git branch move\n> ...\n>\n> Now the verb is crystal-clear.\n\nYes, lacking (assumed) subcommands is yet another dimension of\ninconsistencies.\n\nI mean what I'm after is inconsistency of the first argument to \"git\".\nIt's being the verb more often is where we currently are, at least when\nconsidering \"primary\" commands that \"git help\" outputs. \n\nI mean, consider:\n\n git branch new nice-feature\n\nvs\n\n git new branch nice-feature\n\nIt should have been the latter, when in fact it's currently the\n[reduced] former.\n\nI.e., I'm in favor of universal:\n\n git ...\n\nsyntax to Git commands where specifies an action. [Why things\ntend to drift to Lisp all the time, I wonder?]\n\nFrom that POV, for the commands you mentioned, \"git bisect\" is probably\nfine, whereas \"git worktree\", and \"git remote\" should better be split to\noperations on them, e.g.:\n\n git new remote\n git new worktree\n\nOnce that is regularized, we may as well consider allowing for inverse\norder of the first 2 arguments, by making\n\n git new remote\n git remote new\n\nthe synonyms.\n\nIt doesn't mean we need to rewrite everything. Having an end-goal\nspecified though, we may design new features accordingly, and add\ncommands in preferred syntax for existing features, so that they\neventually obsolete the current status quo.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429672","messageId":"1e18c4ed-6975-5041-4b4f-75c4d3d21860@mfriebe.de","threadId":"56027","inReplyTo":"60ea2eb562f26_2a69208e8@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-11T09:10:08Z","receivedAt":"2021-07-11T09:10:18Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 11/07/2021 01:35, Felipe Contreras wrote:\n> Martin wrote:\n>> At the end of the current or rewritten \"-C\" doc, add:\n>> > This can drop commits\n>>\n>> 4 words. All that is needed.\n> \n> OK. I'm not opposed to that, that would definitely be an improvement\n> from the current text.\n> \n> What I'm saying is that if we are trying to improve the text, it would\n> behoove us to consider all other options, and instead if adding a note\n> at the end (which is correct), reconsider the whole thing to *start*\n> with what's important:\n\nAh, ok. So we have been missing each others point.\n\n\n> Instead of this:\n> \n> -C ::\n> --force-create ::\n> Similar to `--create` except that if `` already\n> exists, it will be reset to ``. This is a\n> convenient shortcut for:\n> +\n> ------------\n> $ git branch -f \n> $ git switch \n> ------------\n> \n> Do this:\n> \n> -N ::\n> Create a new branch like '--new', but if it already exists reset it\n> like '--reset'.\n\nAs I said, I try to avoid reset, and also there is no \"--reset\" to \nmatch. Only a \"reset\" command, and it does a wide range of diff things\n\n -force-new \n -N \n See the --new option.\n Allows to [re-]use the name of an existing branch.\n This may drop commits of that branch.\n\nOr\n See the --new option.\n Can use the name of an existing branch.\n Removing that branch may drop commits.\nIf needs must\n \"Removing\" => \"Resetting\"\n\n\nOr even shorter\n See the --new option.\n Allows to re-use a branch-name and may drop commits\n [resetting it].\n\n"},{"id":"429673","messageId":"0d7190ae-e64e-d1fa-2367-29f302c2ff7e@mfriebe.de","threadId":"56027","inReplyTo":"878s2dgu4d.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-11T09:27:03Z","receivedAt":"2021-07-11T09:27:12Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 11/07/2021 09:57, Sergey Organov wrote:\n> Martin writes:\n> \n> \n> [...]\n> \n>> Currently only the branch is mentioned.\n>> Currently nothing does explicitly say that *commits* can be affected.\n> \n> Commits cannot be immediately affected. One of the most essential\n> features of Git is that commits could only be affected (deleted) by\n> garbage collection. That's what makes Git so nicely safe in operation.\n> \n> It'd be unfortunate to have statements in the manual pages that\n> contradict this.\n> \n\nTell that a new user, who never heard of \"dangling commits\" or the reflog.\n\nFor ages, I wondered what git fsck meant by \"dangling commits\" and why \nmy repro always had \"that problem\".\nAnd what I might do with that hash it gave me.\n\nFor a new user, a commit that is not in any branch listed by\n\"git branch --all\" or \"git stash\"\nis effectively not existent.\n\nFor a new user, it is also \"no help\" (and the doc should help) to avoid \nsaying it, and instead refer to something else from which it could be \nconcluded.\n\"reset the branch\" talks about the branch, and not the commit.\nA new user, even if he read about it before, may very well not make the \nconclusion.\nSo \"reset the branch\" does nothing for a new user. And an expert already \nknows it. So for whom should that be there?\n\nWe can use the term unreachable. But it is no better than say \"drop\"\n\nTechnically they are not \"unreachable\". If I have the hash, I (as \nexpert) can reach them.\nIf I do not, I can get it from \"fsck\". (And spend a good amount of time, \ngoing through a few dozen hashes. (That is, if the reflog was disabled)\n\n\"Drop\" does not mean \"deleted\". More like \"dropped from view\", \"given up\"\nBut a new user reading \"dropped\" will take it as a hint to be careful.\n\nWe can add \"dropped commit\" to the glossary. Then there is no ambiguity. \n(I don't think its needed, but...)\n\nWe can say \"may no longer have a reference\" instead of \"dropped\"\nBut it is long, and again obscure (to a new user).\n"},{"id":"429674","messageId":"87zgutfb9m.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"1e18c4ed-6975-5041-4b4f-75c4d3d21860@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-11T09:30:29Z","receivedAt":"2021-07-11T09:30:40Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Martin writes:\n\n>\n> As I said, I try to avoid reset, and also there is no \"--reset\" to match. Only a \"reset\" command, and it does a wide range of diff things\n>\n> -force-new \n> -N \n> See the --new option.\n> Allows to [re-]use the name of an existing branch.\n> This may drop commits of that branch.\n>\n> Or\n> See the --new option.\n> Can use the name of an existing branch.\n> Removing that branch may drop commits.\n> If needs must\n> \"Removing\" => \"Resetting\"\n>\n>\n> Or even shorter\n> See the --new option.\n> Allows to re-use a branch-name and may drop commits\n> [resetting it].\n\nI'm strongly against \"may drop commits\". I see what you mean, but \"drop\"\nsounds wrong to me, and we should not be plain wrong in the manuals.\n\nMaybe:\n\n\"Allows to reuse . Commits from the former branch may\nbecome unreferenced.\"\n\nAt least this it technically correct and doesn't sound that utterly\nfatal.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429675","messageId":"87sg0lfayd.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"0d7190ae-e64e-d1fa-2367-29f302c2ff7e@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-11T09:37:14Z","receivedAt":"2021-07-11T09:37:21Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Martin writes:\n\n> On 11/07/2021 09:57, Sergey Organov wrote:\n>> Martin writes:\n>> \n>> [...]\n>> \n>>> Currently only the branch is mentioned.\n>>> Currently nothing does explicitly say that *commits* can be affected.\n>> Commits cannot be immediately affected. One of the most essential\n>> features of Git is that commits could only be affected (deleted) by\n>> garbage collection. That's what makes Git so nicely safe in operation.\n>> It'd be unfortunate to have statements in the manual pages that\n>> contradict this.\n>> \n>\n> Tell that a new user, who never heard of \"dangling commits\" or the reflog.\n>\n> For ages, I wondered what git fsck meant by \"dangling commits\" and why\n> my repro always had \"that problem\".\n> And what I might do with that hash it gave me.\n>\n> For a new user, a commit that is not in any branch listed by\n> \"git branch --all\" or \"git stash\"\n> is effectively not existent.\n>\n> For a new user, it is also \"no help\" (and the doc should help) to\n> avoid saying it, and instead refer to something else from which it\n> could be\n> concluded.\n> \"reset the branch\" talks about the branch, and not the commit.\n> A new user, even if he read about it before, may very well not make\n> the conclusion.\n> So \"reset the branch\" does nothing for a new user. And an expert\n> already knows it. So for whom should that be there?\n>\n> We can use the term unreachable. But it is no better than say \"drop\"\n>\n> Technically they are not \"unreachable\". If I have the hash, I (as\n> expert) can reach them.\n> If I do not, I can get it from \"fsck\". (And spend a good amount of\n> time, going through a few dozen hashes. (That is, if the reflog was\n> disabled)\n>\n> \"Drop\" does not mean \"deleted\". More like \"dropped from view\", \"given up\"\n> But a new user reading \"dropped\" will take it as a hint to be careful.\n>\n> We can add \"dropped commit\" to the glossary. Then there is no\n> ambiguity. (I don't think its needed, but...)\n>\n> We can say \"may no longer have a reference\" instead of \"dropped\"\n> But it is long, and again obscure (to a new user).\n\nAs I just stated in anther answer, which see, I see what you mean. I'm\nstill against \"dropped\" though.\n\nI did suggest a wording in that post:\n\n\"Allows to reuse . Commits from the former branch may\nbecome unreferenced.\"\n\nAnother one could be:\n\n\"Allows to reuse . Commits from the former branch could be\nlost.\"\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429676","messageId":"87im1hfa8r.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"60e9fa5132e14_7ef20849@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-11T09:52:36Z","receivedAt":"2021-07-11T09:52:43Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Felipe Contreras writes:\n\n> Sergey Organov wrote:\n\n[...]\n\n>> Creating (a branch) is fundamentally different operation than switching\n>> to (a branch), and that's why the former doesn't fit into \"git switch\".\n>\n> Not in my mind. Instead of switching to an existing branch, I'm switching\n> to a new branch, which is easily understood by\n> `git switch --new branch`.\n\nTo me:\n\n\"create a new branch\" is basic operation.\n\n\"switch to another branch\" is basic operation.\n\n\"create a new branch and then switch to it\" is compound operation.\n\nThe latter could be implemented as either new-then-switch or\nswitch-to-new indeed, but the \"new\" part is the first action to be made,\nso\n\n git new branch \n\nthat switches to the by default still sounds more logical\nto me than current:\n\n git switch -c \n\nThanks,\n-- \nSergey Organov\n"},{"id":"429677","messageId":"6ffd7f1c-97be-a57c-b738-31deae26e8fc@mfriebe.de","threadId":"56027","inReplyTo":"874kd1gr0q.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-11T10:05:02Z","receivedAt":"2021-07-11T10:05:09Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 11/07/2021 11:04, Sergey Organov wrote:\n> Felipe Contreras writes:\n> \n>>\n>> I don't see the logic in here.\n>>\n>> git branch topic # here 'branch' is the verb\n> \n> Not to me. I assumed the \"branch\" is always a noun in \"git branch\", and\n> the actual meaning of this command is:\n\nWell, it is easy to see it as a noun. But for \"branching\" creation of a \nbranch, it can be seen as verb.\n\nYet in\n git branch --list\nit definitely is a noun.\n\nBut then how would/should those work?\nThe action/verb is \"list\" or \"show\"\n\n git show branches\n git show tags\n git show ...\n\nThat completely tears apart related topics.\n\nOr is it enough if the subcommand is a verb?\n git branch create\n git branch list\nThat be ok for me.\n\n\n>>> is \"branch\" a noun or a verb?\n>>\n>> Both.\n> \n> No, it's rather noun plus lacking subcommand, sometimes making it look\n> like verb :)\n\nAs is\n git stash\nfor\n git stash push\n\nAnd I should guess lots of people like the short form....\n\n\n\n\n> I.e., I'm in favor of universal:\n> \n> git ...\n> \n> syntax to Git commands where specifies an action. [Why things\n> tend to drift to Lisp all the time, I wonder?]\n> \n\nBecause humans are more about the \"things\".\nThe way we interact is more ofter derived from the object, than the \nobject being purposefully made for an interaction?\n\n\n> From that POV, for the commands you mentioned, \"git bisect\" is probably\n> fine, whereas \"git worktree\", and \"git remote\" should better be split to\n> operations on them, e.g.:\n> \n> git new remote\n> git new worktree\n> \n\nThat also makes documentation harder. People who want a worktree, want \nthe documentation for it in one place.\n\nSo a manpage for \"git new\" is not desirable. It would have to be split \ninto the manpages for the objects. But that is not good either, or is it?\n\n\n> Once that is regularized, we may as well consider allowing for inverse\n> order of the first 2 arguments, by making\n> \n> git new remote\n> git remote new\n> \n> the synonyms.\n\nHaving even more ways to do one and the same thing....\n\n\nBtw, missing from the discussion:\n\n git log\n\n\"log\" can be a verb, but not in the above.\n\nBecause \"to log\" is to write something into a log.\nBut \"git log\" is to show (i.e. read) the log.\n\n\n\n"},{"id":"429678","messageId":"4cb46126-c816-065f-9052-8ef392c7778b@mfriebe.de","threadId":"56027","inReplyTo":"87sg0lfayd.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-11T10:24:10Z","receivedAt":"2021-07-11T10:24:19Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 11/07/2021 11:37, Sergey Organov wrote:\n> Martin writes:\n> I did suggest a wording in that post:\n> \n> \"Allows to reuse . Commits from the former branch may\n> become unreferenced.\"\n> \n> Another one could be:\n> \n> \"Allows to reuse . Commits from the former branch could be\n> lost.\"\n> \n\n\"lost\" is perfect for me.\n\n\"could be\" is a good replacement for \"may\". It much stronger points to \n\"this may or may not be\"\n\n\"could be\" should definitely be used.\n\nAfaik many tech docs try to avoid \"may\", \"can\", \"must not\"....\n"},{"id":"429683","messageId":"871r85f39n.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"6ffd7f1c-97be-a57c-b738-31deae26e8fc@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-11T12:23:16Z","receivedAt":"2021-07-11T12:23:23Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Martin writes:\n\n> On 11/07/2021 11:04, Sergey Organov wrote:\n>> Felipe Contreras writes:\n>> \n>>>\n>>> I don't see the logic in here.\n>>>\n>>> git branch topic # here 'branch' is the verb\n>> Not to me. I assumed the \"branch\" is always a noun in \"git branch\", and\n>> the actual meaning of this command is:\n>\n> Well, it is easy to see it as a noun. But for \"branching\" creation of\n> a branch, it can be seen as verb. \n>\n> Yet in\n> git branch --list\n> it definitely is a noun.\n\nIt's definitely a noun if only consider its description, as output by\n\"git help\":\n\n \"branch List, create, or delete branches\"\n\nSo \"git branch\" is \"whatever about branches\", not \"perform the branch\noperation\", whatever the latter might be.\n\n>\n> But then how would/should those work?\n> The action/verb is \"list\" or \"show\"\n>\n> git show branches\n> git show tags\n> git show ...\n>\n> That completely tears apart related topics.\n\nYep, that's it. However, there is no need to immediately do something\nabout it except considering this as a sound design to be targeted at.\n\n>\n> Or is it enough if the subcommand is a verb?\n> git branch create\n> git branch list\n> That be ok for me.\n\nThis we can't do sanely in a backward-compatible manner, I'm afraid, so\nit's likely not an option.\n\nOTOH, adding, say:\n\n git rm \n\nor, say, adding a whole new \"git new\" (pun intended) could be considered\nto be steps in the right direction if we choose \"git ...\"\nmodel.\n\n>\n>\n>>>> is \"branch\" a noun or a verb?\n>>>\n>>> Both.\n>> No, it's rather noun plus lacking subcommand, sometimes making it look\n>> like verb :)\n>\n> As is\n> git stash\n> for\n> git stash push\n>\n> And I should guess lots of people like the short form....\n\nMaybe. My primary point is inconsistency, not my personal preference for\none way or another. I'm afraid one could find suitable example to\nsupport any model.\n\n>\n>> I.e., I'm in favor of universal:\n>> git ...\n>> syntax to Git commands where specifies an action. [Why things\n>> tend to drift to Lisp all the time, I wonder?]\n>> \n>\n> Because humans are more about the \"things\".\n> The way we interact is more ofter derived from the object, than the\n> object being purposefully made for an interaction?\n\nI don't see it, at least not in the usual human conversations. When one\nmeans an action to be performed, they name the action and then the object:\n\n \"Play football\", \"Go home\", \"Set your thoughts straight\", \"Wash your hands\"\n\nNo?\n\nAnyway, it's more the consistency that matters, not particular\nconvention. Git problem is that is has no convention at all. \"Just do\nwhat feels right today\" seems to be the motto.\n\nFinally, the problem for this particular discussion is that if we decide\nthat it's rather:\n\n git \n\nthat is the way to go, that I'm pretty fine with as well, we should\nsimply *obsolete \"git switch\" right away*, rather than spending time\nimproving its now almost useless documentation.\n\n>> From that POV, for the commands you mentioned, \"git bisect\" is probably\n>> fine, whereas \"git worktree\", and \"git remote\" should better be split to\n>> operations on them, e.g.:\n>> git new remote\n>> git new worktree\n>> \n>\n> That also makes documentation harder. People who want a worktree, want\n> the documentation for it in one place.\n\n git help worktree\n\nshould be able to provide a short manual on worktrees. Please notice\nit's again not\n\n git worktree help\n\n\n>\n> So a manpage for \"git new\" is not desirable.\n\nSure it is desirable. That's the primary purpose of manual pages -- to\ndescribe actual commands.\n\n> It would have to be split into the manpages for the objects. But that\n> is not good either, or is it?\n\nNo-no! Manual pages for describing actual commands are to be there.\n\nIt's user/programmer manuals and tutorials that should rather be built\naround concepts. It's fine with me if they are available in the format\nof manual pages, even though it's not very suitable for that.\n\n>\n>> Once that is regularized, we may as well consider allowing for inverse\n>> order of the first 2 arguments, by making\n>> git new remote\n>> git remote new\n>> the synonyms.\n>\n> Having even more ways to do one and the same thing....\n\nPython was aiming to have one obvious way of doing every single thing...\nDid it succeed in that, I wonder? Maybe this aim is only good in theory?\n\n>\n>\n> Btw, missing from the discussion:\n>\n> git log\n>\n> \"log\" can be a verb, but not in the above.\n\nYep, and \"git log\" is yet another can of worms I'm not willing to open.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429685","messageId":"33af677c-8fec-5b49-0e00-878918c4ea1d@mfriebe.de","threadId":"56027","inReplyTo":"871r85f39n.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-11T13:39:19Z","receivedAt":"2021-07-11T13:39:26Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 11/07/2021 14:23, Sergey Organov wrote:\n> Martin writes:\n>> Because humans are more about the \"things\".\n>> The way we interact is more ofter derived from the object, than the\n>> object being purposefully made for an interaction?\n> \n> I don't see it, at least not in the usual human conversations. When one\n> means an action to be performed, they name the action and then the object:\n> \n> \"Play football\", \"Go home\", \"Set your thoughts straight\", \"Wash your hands\"\n> \n> No?\n\n1) the order does not necessarily indicate the significance.\n\n2) That is English for you. Afaik there are languages which have the \nverb at the end.\nAlso, in German it is perfectly fine (though not very common) to use \n\"object verb subject\". Fussball spielen wir.\n\nEven in English you have: Woe is me. Yes \"woe\" is the Subject.\n\n\n> Anyway, it's more the consistency that matters, not particular\n> convention. Git problem is that is has no convention at all. \"Just do\n> what feels right today\" seems to be the motto.\n\nWell human languages are not as rigid as computer languages.\n\n> \n> Finally, the problem for this particular discussion is that if we decide\n> that it's rather:\n> \n> git \n> \n> that is the way to go, that I'm pretty fine with as well, we should\n> simply *obsolete \"git switch\" right away*, rather than spending time\n> improving its now almost useless documentation.\n\nActually then we would end up with\n\n git branch switch\n git tag switch // detach\n git commit switch // detach\n\nWell it could be\n git worktree switch\n(ignoring the effect on the index / and bringing \"worktree\" into a \nsingle worktree setup)\n\n\n\nThe problem is, that IMHO forcing either verb or noun, ends up with \ngrouping commands in ways that create unnecessary dividers between \nrelated actions. (Continued, next paragraph)\n\n> \n>>> From that POV, for the commands you mentioned, \"git bisect\" is probably\n>>> fine, whereas \"git worktree\", and \"git remote\" should better be split to\n>>> operations on them, e.g.:\n>>> git new remote\n>>> git new worktree\n>>>\n\nThis is what I mean with dividers.\n\nThere may be some relation between \"new branch\", \"new tag\"\n\nBut I can see none between \"new branch\" and \"new remote\" and \"new \nworktree\". None at all. Yet I can see relations between different things \nyou can do with a worktree.\n\nI also think that, switching to a commit or branch are to closely \nrelated, and should not be divided.\n(There were even suggestions that switching to a commit, is an unnamed \nbranch)\n\nAs I said, I have not read any research paper on that topic.\nBut to me, it severely disrupts the intuitive aspect.\n\n\n>>\n>>> Once that is regularized, we may as well consider allowing for inverse\n>>> order of the first 2 arguments, by making\n>>> git new remote\n>>> git remote new\n>>> the synonyms.\n>>\n>> Having even more ways to do one and the same thing....\n> \n> Python was aiming to have one obvious way of doing every single thing...\n> Did it succeed in that, I wonder? Maybe this aim is only good in theory?\n\nWe are way away from having \"one single way\". But aiming for the extreme \nopposite may not be any smarter.\n\n\n\nWhile there is nothing wrong with going our own way in the end, maybe we \nshould look around before?\nHow do other vcs do it?\n\nsvn has at least status and log, which I would consider nouns, the way \nthey are used. And it has verbs too.\n\nhg as \"branches\", \"files\" which are nouns. And \"log\".\nAnd it has verbs too.\n\nSo there seems to be a pattern to using \"mixed\" verbs and nouns.\n"},{"id":"429686","messageId":"87sg0kewi2.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"33af677c-8fec-5b49-0e00-878918c4ea1d@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-11T14:49:25Z","receivedAt":"2021-07-11T14:49:32Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Martin writes:\n\n> On 11/07/2021 14:23, Sergey Organov wrote:\n\n[...]\n\n>>>> Once that is regularized, we may as well consider allowing for inverse\n>>>> order of the first 2 arguments, by making\n>>>> git new remote\n>>>> git remote new\n>>>> the synonyms.\n>>>\n>>> Having even more ways to do one and the same thing....\n>> Python was aiming to have one obvious way of doing every single thing...\n>> Did it succeed in that, I wonder? Maybe this aim is only good in theory?\n>\n> We are way away from having \"one single way\". But aiming for the\n> extreme opposite may not be any smarter.\n\nI don't like extremes either, but when there is a choice, there should\nbe at last a stated preferred way of doing things. Guidelines, if not\nthe rules. Otherwise we end up with an ugly mix of random preferences of\ndifferent authors.\n\n>\n> While there is nothing wrong with going our own way in the end, maybe\n> we should look around before?\n>\n> How do other vcs do it?\n>\n> svn has at least status and log, which I would consider nouns, the way\n> they are used. And it has verbs too.\n>\n> hg as \"branches\", \"files\" which are nouns. And \"log\".\n> And it has verbs too.\n>\n> So there seems to be a pattern to using \"mixed\" verbs and nouns.\n\nThere are so many things they did wrong... This could well be just\nanother one.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429705","messageId":"87bl78eqv3.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"33af677c-8fec-5b49-0e00-878918c4ea1d@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-11T16:51:12Z","receivedAt":"2021-07-11T16:51:19Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Martin writes:\n\n> On 11/07/2021 14:23, Sergey Organov wrote:\n>> Martin writes:\n\n[...]\n\n>> Anyway, it's more the consistency that matters, not particular\n>> convention. Git problem is that is has no convention at all. \"Just do\n>> what feels right today\" seems to be the motto.\n>\n> Well human languages are not as rigid as computer languages.\n>\n>> Finally, the problem for this particular discussion is that if we decide\n>> that it's rather:\n>> git \n>> that is the way to go, that I'm pretty fine with as well, we should\n>> simply *obsolete \"git switch\" right away*, rather than spending time\n>> improving its now almost useless documentation.\n>\n> Actually then we would end up with\n>\n> git branch switch\n> git tag switch // detach\n> git commit switch // detach\n\nWhy? You don't switch tags or commits. You switch only branches, so it'd\nbe:\n\n git branch switch \n\nwhere is any commit'ish.\n\n>\n> Well it could be\n> git worktree switch\n> (ignoring the effect on the index / and bringing \"worktree\" into a\n> single worktree setup)\n\nYep, it could be, and it could be even both doing similar things.\n\n>\n> The problem is, that IMHO forcing either verb or noun, ends up with\n> grouping commands in ways that create unnecessary dividers between\n> related actions. (Continued, next paragraph)\n\nThe problem is that there are multiple ways of grouping, and selecting\nthe right one is not an easy decision. Having carefully though-of\nguidelines would help.\n\nGrouping by action first is more universal than grouping by object\nfirst, but not always more \"natural\", as you've correctly noticed.\n\n>\n>> \n>>>> From that POV, for the commands you mentioned, \"git bisect\" is probably\n>>>> fine, whereas \"git worktree\", and \"git remote\" should better be split to\n>>>> operations on them, e.g.:\n>>>> git new remote\n>>>> git new worktree\n>>>>\n>\n> This is what I mean with dividers.\n>\n> There may be some relation between \"new branch\", \"new tag\"\n>\n> But I can see none between \"new branch\" and \"new remote\" and \"new\n> worktree\". None at all. Yet I can see relations between different\n> things\n> you can do with a worktree.\n\nThe only true relation in this model is that if you want to create\n*something* new, you use \"git new\". Simple like hell.\n\n>\n> I also think that, switching to a commit or branch are to closely\n> related, and should not be divided.\n\nStrictly speaking, there is no need to switch to something that is not\na branch. But we'd need the notion of \"unnamed branch\" to achieve this\nsimplicity while not loosing useful functionality, and even gaining\nsome, see below.\n\n> (There were even suggestions that switching to a commit, is an unnamed\n> branch)\n\nYep. We just switch our current *branch*, so another *branch* becomes\ncurrent. If we specify a commit or a tag as the target, the unnamed\nbranch should be reset to point there, and only then we should switch\nour current to this new unnamed branch. That's it. No need for\ncomplications of \"detached HEAD\", that even sounds awfully and makes me\nscared every time I see it.\n\nIn fact this \"unnamed branch\" could have a non-empty name, say \"AUTO\",\nand its own entry in the reflog. That'd give even more functionality\nthan is currently available with this chilling \"detached HEAD\". We should\nbetter bury this Nearly Headless Nick finally.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429720","messageId":"AS8PR02MB730258D0643373CB476A18D39C159@AS8PR02MB7302.eurprd02.prod.outlook.com","threadId":"56027","inReplyTo":"87bl78eqv3.fsf@osv.gnss.ru","subject":"RE: PATCH: improve git switch documentation","fromName":"Kerry, Richard","fromEmail":"richard.kerry@atos.net","sentAt":"2021-07-12T10:31:41Z","receivedAt":"2021-07-12T10:32:14Z","isPatch":false,"sender":{"key":"richard.kerry@atos.net","avatar":null},"body":"\n> > git branch switch\n> > git tag switch // detach\n> > git commit switch // detach\n> \n> Why? You don't switch tags or commits. You switch only branches, \n\nYes you do.\nYou can switch to branches, tags or commits.\n\nIf I remember correctly, \"branch\" is used in Subversion and CVS only for the creation of a branch. Likewise \"tag\" for creating a tag. \nAnd I think they both use \"update\" to load the required branch/tag/commit into the current working area.\n\nIf git were to do that then I think we might get around some of this confusion.\n\nIn that case:\ngit branch = create a branch\ngit tag = create a tag\n\nAnd then a new \"update\", so:\ngit update = make the current working area contain a copy of the given branch, and similarly \"git update \" or \"git update \"\n\nIn all these cases the keyword after \"git\" is definitely a verb, even where the actual word used could be either, and you need to look at all the definitions in the dictionary to check.\n\nRegards,\nRichard.\n\n\n"},{"id":"429721","messageId":"87r1g3n5x3.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"AS8PR02MB730258D0643373CB476A18D39C159@AS8PR02MB7302.eurprd02.prod.outlook.com","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-12T11:11:04Z","receivedAt":"2021-07-12T11:11:12Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"\"Kerry, Richard\" writes:\n\n>> > git branch switch\n>> > git tag switch // detach\n>> > git commit switch // detach\n>> \n>> Why? You don't switch tags or commits. You switch only branches, \n>\n> Yes you do.\n\nNo, you don't. You probably didn't read my sentence carefully. Please\ntry to read what is written there, and see below for more explanations.\n\n> You can switch to branches, tags or commits.\n\n1. Switch branch /to a tag/ is not the same as switching /tag/. You can\nreset tag to point to another commit, yes, but that was outside of the\nscope of the discussion. Switching *commit* doesn't make sense at all.\nOverall, you don't switch tags or commits when you switch branches, --\nthat's the meaning of my original sentence.\n\n2. Event when you switch /to/ tags or commits, you actually still switch\nto a branch, as you can still create new commits that will grow that\nbranch. This \"detached HEAD\" thingy that has been adopted to support\nswitching to commits is just a misnomer that obscures understanding, and\nshould be eventually replaced, probably by means of introducing the\nnotion of \"unnamed\" or \"automatic\" branch.\n\n>\n> If I remember correctly, \"branch\" is used in Subversion and CVS only\n> for the creation of a branch. Likewise \"tag\" for creating a tag.\n> And I think they both use \"update\" to load the required\n> branch/tag/commit into the current working area.\n>\n> If git were to do that then I think we might get around some of this\n> confusion.\n>\n> In that case:\n> git branch = create a branch\n\nSorry, it's too late. I don't think we can actually do it.\n\n> git tag = create a tag\n\nDitto. Too late.\n\n>\n> And then a new \"update\", so:\n> git update = make the current working area contain a copy\n> of the given branch, and similarly \"git update \" or \"git\n> update \"\n\nIt's already called \"git restore\", no?\n\n>\n> In all these cases the keyword after \"git\" is definitely a verb, even\n> where the actual word used could be either, and you need to look at\n> all the definitions in the dictionary to check.\n\nIn the current \"git branch\" command \"branch\" is a noun, and then a verb\ndefining exact operation follows as an option, or is assumed. You may\nwell think about it as being \"namespace\":\n\n \"git\" -- enter \"git\" namespace\n \"branch\" -- enter \"git:branch\" namespace\n\nand everything that follows is about Git branches with more or less\nrandom syntax for particular functions to be performed.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429759","messageId":"60ec6a9d1ffd6_a45252083d@natae.notmuch","threadId":"56027","inReplyTo":"e9c2b9cd-edfb-cbed-9638-382a6b0da59b@mfriebe.de","subject":"Re: Naming the --forec option [[Re: PATCH: improve git switch documentation]]","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-12T16:15:25Z","receivedAt":"2021-07-12T16:15:30Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 11/07/2021 01:18, Felipe Contreras wrote:\n\n> >> Also \"--reset\" does not have the same alerting properties to me, as\n> >> \"force\" or \"discard\" have.\n> >> This may be my English, but to me \"reset\" does not have the same\n> >> alerting property.\n> > \n> > OK, maybe it's a language issue. I'm not a native English speaker, my\n> > mother tongue is Spanish, but I'm pretty sure my understanding of\n> > \"reset\" is what most people understand: set again.\n> \n> I am German. And yes \"set again\" (sometimes \"restart\", but that does not \n> matter here)\n> \n> If a branch is set, as base and head. Then \"reset\" means to set those \n> two again.\n> \n> \"set again\" => They will still be there.\n> (changed indeed, but there)\n> \n> The commits hold by that branch, are not \"set again\".\n> They may become unreachable.\n> \n> The word \"reset\" gives no indication on knock on effects.\n> However, I prefer if those effects are made clear.\n\nI gave plenty of examples where \"reset\" implies the previous state is\ngone after it.\n\n-- \nFelipe Contreras\n"},{"id":"429761","messageId":"60ec6cd622c4c_a4525208a0@natae.notmuch","threadId":"56027","inReplyTo":"874kd1gr0q.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-12T16:24:54Z","receivedAt":"2021-07-12T16:24:59Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Sergey Organov wrote:\n> Felipe Contreras writes:\n> \n> > Sergey Organov wrote:\n> >> Martin writes:\n> >> \n> >> > On 10/07/2021 12:24, Sergey Organov wrote:\n> >> >> Martin writes:\n> >> >>> Actually, \"new\" or \"create\" would make sense in \"git branch\". But in\n> >> >>> git switch, they actually raise the question \"create what?\" / \"new\n> >> >>> what?\".\n> >> >> I believe that's because \"git switch\" tries to do too much. \"git switch\"\n> >> >> should rather switch between existing branches, and do nothing else. As\n> >> >> I said once in this discussion already: trouble writing good\n> >> >> documentation is often indication of some flaws in the design.\n> >> >> Creating (a branch) is fundamentally different operation than switching\n> >> >> to (a branch), and that's why the former doesn't fit into \"git switch\".\n> >> >> \n> >> >\n> >> > Right, yes. But creating a branch is often followed by switching to it.\n> >> \n> >> Yep, but here the creation is the primary operation, not switching, so\n> >> putting this into \"git switch\" looks like design flaw. These 2 actions\n> >> are fine to co-exist in \"git branch\" = \"whatever you want to do to\n> >> branches\", but not in \"git switch\" == \"wherever you want to switch\".\n> >\n> > I don't see the logic in here.\n> >\n> > git branch topic # here 'branch' is the verb\n> \n> Not to me. I assumed the \"branch\" is always a noun in \"git branch\", and\n> the actual meaning of this command is:\n> \n> git branch [create|new] topic\n> \n> I.e., creation just being the default action taken on the branch.\n\nThe question is not what you assumed, the question is can other people\nassume otherwise?\n\n\"branch\" can be a verb, that's a fact.\n\n> >> To me, while the latter is obvious, it's verb and specifies the action\n> >> to be performed, the former looks more like \"whatever you want to do\n> >> with branches\", and thus the \"branch\" is a noun there and the command\n> >> thus is object-oriented.\n> >\n> > I agree, and I did have indeed noticed the inconsistency. But there's\n> > another category of commands that receive subcommands, like:\n> >\n> > git remote $subcommand\n> > git worktree $subcommand\n> > git bisect $subcommand\n> >\n> > In my opinion `git branch` fits more these subcommand commands, and it\n> > was a mistake to make the subcommands options, it should be:\n> >\n> > git branch list\n> > git branch new\n> > git branch set-upstream\n> > git branch move\n> > ...\n> >\n> > Now the verb is crystal-clear.\n> \n> Yes, lacking (assumed) subcommands is yet another dimension of\n> inconsistencies.\n> \n> I mean what I'm after is inconsistency of the first argument to \"git\".\n> It's being the verb more often is where we currently are, at least when\n> considering \"primary\" commands that \"git help\" outputs. \n> \n> I mean, consider:\n> \n> git branch new nice-feature\n> \n> vs\n> \n> git new branch nice-feature\n> \n> It should have been the latter, when in fact it's currently the\n> [reduced] former.\n\nI disagree. I prefer the former.\n\nEither way this is way too far from the original point. I don't think\nyou can convince me that `git new branch` makese sense, but there's no\nneed for that.\n\nTo move forward we need to find consensus, and if you and me agree that\n`git branch new` makes sense, that's where we should focus on.\n\nEven standardizing `git branch` would be an almost-impossible task, even\nif we manage to convince others. `git new branch` even more impossible.\n\n-- \nFelipe Contreras\n"},{"id":"429762","messageId":"60ec6d91deced_a452520825@natae.notmuch","threadId":"56027","inReplyTo":"1e18c4ed-6975-5041-4b4f-75c4d3d21860@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-12T16:28:01Z","receivedAt":"2021-07-12T16:28:06Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 11/07/2021 01:35, Felipe Contreras wrote:\n\n> > Do this:\n> > \n> > -N ::\n> > Create a new branch like '--new', but if it already exists reset it\n> > like '--reset'.\n\n> Or even shorter\n> See the --new option.\n> Allows to re-use a branch-name and may drop commits\n> [resetting it].\n\nYes, it is shorter, but now it doesn't even say what it does.\n\n-- \nFelipe Contreras\n"},{"id":"429764","messageId":"54644739-2138-8086-1696-d3c52960216c@mfriebe.de","threadId":"56027","inReplyTo":"60ec6d91deced_a452520825@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-12T16:33:06Z","receivedAt":"2021-07-12T16:33:10Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 12/07/2021 18:28, Felipe Contreras wrote:\n> Martin wrote:\n>> On 11/07/2021 01:35, Felipe Contreras wrote:\n> \n>>> Do this:\n>>>\n>>> -N ::\n>>> Create a new branch like '--new', but if it already exists reset it\n>>> like '--reset'.\n> \n>> Or even shorter\n>> See the --new option.\n>> Allows to re-use a branch-name and may drop commits\n>> [resetting it].\n> \n> Yes, it is shorter, but now it doesn't even say what it does.\n> \n\nOk instead of \" see the --new option\"\nuse \"Same as the --new option, but allows....\"\n"},{"id":"429765","messageId":"60ec6f167968d_a4525208c4@natae.notmuch","threadId":"56027","inReplyTo":"0d7190ae-e64e-d1fa-2367-29f302c2ff7e@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-12T16:34:30Z","receivedAt":"2021-07-12T16:34:36Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 11/07/2021 09:57, Sergey Organov wrote:\n> > Martin writes:\n> > \n> > \n> > [...]\n> > \n> >> Currently only the branch is mentioned.\n> >> Currently nothing does explicitly say that *commits* can be affected.\n> > \n> > Commits cannot be immediately affected. One of the most essential\n> > features of Git is that commits could only be affected (deleted) by\n> > garbage collection. That's what makes Git so nicely safe in operation.\n> > \n> > It'd be unfortunate to have statements in the manual pages that\n> > contradict this.\n> \n> Tell that a new user, who never heard of \"dangling commits\" or the reflog.\n\nThe user doesn't need to understand what \"dangling comments\" are, not at\nthis point. All she needs is to know is that there's a concept she\ndoesn't understand yet.\n\n> For ages, I wondered what git fsck meant by \"dangling commits\" and why \n> my repro always had \"that problem\".\n> And what I might do with that hash it gave me.\n\nYes, but it's a thousand times better to not know what \"dangling\ncommits\" are, than to incorrectly think commits are somehow gone\nforever.\n\nIt is fine that the user has knowledge gaps, and it is fine for the user\nknows she has knowledge gaps.\n\n-- \nFelipe Contreras\n"},{"id":"429766","messageId":"f0770358-be4c-a747-0851-b2fd73c1978e@mfriebe.de","threadId":"56027","inReplyTo":"60ec6cd622c4c_a4525208a0@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-12T16:39:18Z","receivedAt":"2021-07-12T16:39:25Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 12/07/2021 18:24, Felipe Contreras wrote:\n> Sergey Organov wrote:\n> Even standardizing `git branch` would be an almost-impossible task, even\n> if we manage to convince others. `git new branch` even more impossible.\n> \n\nNot sure but from the glance at hg that I took, they seem to use the \nplural for nouns.\n\nSo then we could have\n\n git branch \n\n git branches new // long version\n git branches list\n git branches delete\n ....\n\nHowever, standardizing to a fixed verb/noun rule will still be more than \na challenge.\n\nThe above would as guildeline be\n\n git verb\nor\n git plural-noun verb\n\nYet try to do that with\n git status\n git log\n\nI don't see how a better alternative for those can be found. One that \nactually is accepted because it's better, not just because it follows a \nrule.\n\nstatus, is not a verb\nlog is the wrong verb, or again a noun.\n\n\n\n"},{"id":"429767","messageId":"60ec715c8338_a452520896@natae.notmuch","threadId":"56027","inReplyTo":"87im1hfa8r.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-12T16:44:12Z","receivedAt":"2021-07-12T16:44:17Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Sergey Organov wrote:\n> Felipe Contreras writes:\n> \n> > Sergey Organov wrote:\n> \n> [...]\n> \n> >> Creating (a branch) is fundamentally different operation than switching\n> >> to (a branch), and that's why the former doesn't fit into \"git switch\".\n> >\n> > Not in my mind. Instead of switching to an existing branch, I'm switching\n> > to a new branch, which is easily understood by\n> > `git switch --new branch`.\n> \n> To me:\n> \n> \"create a new branch\" is basic operation.\n> \n> \"switch to another branch\" is basic operation.\n> \n> \"create a new branch and then switch to it\" is compound operation.\n\nCompound operations soon become basic operations in the mind of an\nexpert.\n\nLifting your feet, and then landing your feet might be basic operations\nwhen you are 1 yo, but soon enough they become \"walking\".\n\nSimilarly checking out a commit and then cherry-picking a sequence of\ncommits while resolving conflicts becomes \"rebasing\".\n\nIn my mind I'm not doing two operations, it's one operation with a\nmodifier:\n\n git switch --new branch\n\n--new is an adverb, not an operation.\n\n-- \nFelipe Contreras\n"},{"id":"429775","messageId":"60ec740d6c560_a4525208d3@natae.notmuch","threadId":"56027","inReplyTo":"87r1g3n5x3.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-12T16:55:41Z","receivedAt":"2021-07-12T16:55:45Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Sergey Organov wrote:\n> \"Kerry, Richard\" writes:\n\n> > If I remember correctly, \"branch\" is used in Subversion and CVS only\n> > for the creation of a branch. Likewise \"tag\" for creating a tag.\n> > And I think they both use \"update\" to load the required\n> > branch/tag/commit into the current working area.\n> >\n> > If git were to do that then I think we might get around some of this\n> > confusion.\n> >\n> > In that case:\n> > git branch = create a branch\n> \n> Sorry, it's too late. I don't think we can actually do it.\n> \n> > git tag = create a tag\n> \n> Ditto. Too late.\n\nIt's never too late consider what would have been the correct UI.\n\nEven if ultimately unachievable, exploring these ideas might give you\nother ideas that are more achievable.\n\n-- \nFelipe Contreras\n"},{"id":"429776","messageId":"60ec74c513b2b_a45252081b@natae.notmuch","threadId":"56027","inReplyTo":"54644739-2138-8086-1696-d3c52960216c@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-12T16:58:45Z","receivedAt":"2021-07-12T16:58:49Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 12/07/2021 18:28, Felipe Contreras wrote:\n> > Martin wrote:\n> >> On 11/07/2021 01:35, Felipe Contreras wrote:\n> > \n> >>> Do this:\n> >>>\n> >>> -N ::\n> >>> Create a new branch like '--new', but if it already exists reset it\n> >>> like '--reset'.\n> > \n> >> Or even shorter\n> >> See the --new option.\n> >> Allows to re-use a branch-name and may drop commits\n> >> [resetting it].\n> > \n> > Yes, it is shorter, but now it doesn't even say what it does.\n> > \n> \n> Ok instead of \" see the --new option\"\n> use \"Same as the --new option, but allows....\"\n\nYeah, that explains more, but what happend when you use a branch name\nthat already exists? Still not explained.\n\n-- \nFelipe Contreras\n"},{"id":"429778","messageId":"60ec7741640d5_a452520863@natae.notmuch","threadId":"56027","inReplyTo":"f0770358-be4c-a747-0851-b2fd73c1978e@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-12T17:09:21Z","receivedAt":"2021-07-12T17:09:26Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 12/07/2021 18:24, Felipe Contreras wrote:\n> > Sergey Organov wrote:\n> > Even standardizing `git branch` would be an almost-impossible task, even\n> > if we manage to convince others. `git new branch` even more impossible.\n> > \n> \n> Not sure but from the glance at hg that I took, they seem to use the \n> plural for nouns.\n> \n> So then we could have\n> \n> git branch \n> \n> git branches new // long version\n> git branches list\n> git branches delete\n> ....\n> \n> However, standardizing to a fixed verb/noun rule will still be more than \n> a challenge.\n> \n> The above would as guildeline be\n> \n> git verb\n> or\n> git plural-noun verb\n\nI don't see what's wrong with considering the second form a subcommand:\n\n git $subcommand $verb\n\nLike `git bisect start`. That way you could consider `branches` to be a\nsubcommand, it doesn't need to be a plural noun.\n\n> Yet try to do that with\n> git status\n> git log\n> \n> I don't see how a better alternative for those can be found. One that \n> actually is accepted because it's better, not just because it follows a \n> rule.\n> \n> status, is not a verb\n> log is the wrong verb, or again a noun.\n\nIf `git branch` is a shorthand for `git branches new`, the you could\nconsider `git status` to be the a shortcut for `git status show`, but\nsince there's no other action to be done with the status subcommand,\nthen it's always implied.\n\n-- \nFelipe Contreras\n"},{"id":"429786","messageId":"0d7bd249-2aba-236a-9f93-3a5b30182d15@mfriebe.de","threadId":"56027","inReplyTo":"60ec74c513b2b_a45252081b@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-12T17:52:03Z","receivedAt":"2021-07-12T17:52:07Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 12/07/2021 18:58, Felipe Contreras wrote:\n> Martin wrote:\n>> On 12/07/2021 18:28, Felipe Contreras wrote:\n>>> Martin wrote:\n>>>> On 11/07/2021 01:35, Felipe Contreras wrote:\n>>>\n>>>>> Do this:\n>>>>>\n>>>>> -N ::\n>>>>> Create a new branch like '--new', but if it already exists reset it\n>>>>> like '--reset'.\n>>>\n>>>> Or even shorter\n>>>> See the --new option.\n>>>> Allows to re-use a branch-name and may drop commits\n>>>> [resetting it].\n>>>\n>>> Yes, it is shorter, but now it doesn't even say what it does.\n>>>\n>>\n>> Ok instead of \" see the --new option\"\n>> use \"Same as the --new option, but allows....\"\n> \n> Yeah, that explains more, but what happend when you use a branch name\n> that already exists? Still not explained.\n> \n\n\nI have to look back in the mails.\nThere was a lot about getting it shorter, I am happy with a verbose \nversion too.\n\nTaking a step back.\n\n> -c \n> --create \n> \n> Create a new branch named starting at\n> before switching to the branch. \n> This is a convenient shortcut for:\n\nShould that actually say, that it will fail if the branch-name is \nalready taken?\nIMHO yes.\n\nThe \"-C\" option could then be (incorporating the \"could be lost\" from a \nprior mail.\n\n > -C \n > Same the --new option.\n > But allows to use an existing branch-name. The\n > [existing|old] branch [for the name] will be removed, and\n > its commits could be lost.\n\nIf using \"existing\" or \"old\" then \"for the name\" is *not* needed, and \nvice versa.\n\nAnd, yes they can be lost. They can be found again, if one knows where \nto look.\n"},{"id":"429814","messageId":"60ec93155663f_a231f208fb@natae.notmuch","threadId":"56027","inReplyTo":"0d7bd249-2aba-236a-9f93-3a5b30182d15@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-12T19:08:05Z","receivedAt":"2021-07-12T19:08:10Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 12/07/2021 18:58, Felipe Contreras wrote:\n\n> The \"-C\" option could then be (incorporating the \"could be lost\" from a \n> prior mail.\n> \n> > -C \n> > Same the --new option.\n\nBut it's not the same as --new.\n\n> > But allows to use an existing branch-name.\n\nIf this is an essential part of the previous sentence, it should be part\nof the sentence:.\n\n Same [as] the --new option, but allows to use an existing branch name.\n\nBut this is wasted space:\n\n Shouting is the same as talking, but with a different volume.\n\nThere's no need for another sentence explaining in what way it is\ndifferent (higher volume), do it in the same sentence.\n\nWhat happens when we use an existing branch name?\n\n> > The [existing|old] branch [for the name] will be removed,\n\nExcept this is a lie. At no point is the branch removed; the branch name\nis never gone, neither are the commits.\n\nWhat is actually happening is that the branch head is changed. That is\nall. And as I already explained in the subthread, everyone understands\nwhat changing the branch head does to the branch.\n\nEveryone knows what happens when you reset your computer without saving\nyour Excel spreadsheet. The word \"reset\" implies loosing state.\n\nIf you don't want to use the word \"reset\", or the term \"branch head\",\nthen you can say:\n\n Same as --new, but if the branch already exists it's replaced.\n\nThis *still* doesn't explain what it is doing, you would need to read\n--new.\n\n Create a new branch like '--new', but if the branch already exists\n it's replaced.\n\nNow it is actually self-contained.\n\n> > and its commits could be lost.\n\nThe commits are not lost, they are just not part of this branch anymore.\nThey could easily be part of another branch already.\n\n Create a new branch like '--new', but if the branch already exists\n it's replaced. The commits that are initially part of the branch might\n not be part of the branch afterwards.\n\nI think the last sentence is superfluous and obvious. Everyone\nunderstands that if A is replaced by B, B might be different from A, and\nthus not everything of A might end up in B.\n\nIf you want to send a patch with that unnecessary information, go ahead,\nwhat I'm saying is that if the first part is written correctly the last\npart is obvious.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"429849","messageId":"87czrnf8bj.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"60ec6cd622c4c_a4525208a0@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-12T22:58:40Z","receivedAt":"2021-07-12T22:58:47Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Felipe Contreras writes:\n\n> Sergey Organov wrote:\n>> Felipe Contreras writes:\n>> \n>> > Sergey Organov wrote:\n>> >> Martin writes:\n>> >> \n>> >> > On 10/07/2021 12:24, Sergey Organov wrote:\n>> >> >> Martin writes:\n>> >> >>> Actually, \"new\" or \"create\" would make sense in \"git branch\". But in\n>> >> >>> git switch, they actually raise the question \"create what?\" / \"new\n>> >> >>> what?\".\n>> >> >> I believe that's because \"git switch\" tries to do too much.\n>> >> >> \"git switch\"\n>> >> >> should rather switch between existing branches, and do nothing else. As\n>> >> >> I said once in this discussion already: trouble writing good\n>> >> >> documentation is often indication of some flaws in the design.\n>> >> >> Creating (a branch) is fundamentally different operation than switching\n>> >> >> to (a branch), and that's why the former doesn't fit into \"git switch\".\n>> >> >> \n>> >> >\n>> >> > Right, yes. But creating a branch is often followed by switching to it.\n>> >> \n>> >> Yep, but here the creation is the primary operation, not switching, so\n>> >> putting this into \"git switch\" looks like design flaw. These 2 actions\n>> >> are fine to co-exist in \"git branch\" = \"whatever you want to do to\n>> >> branches\", but not in \"git switch\" == \"wherever you want to switch\".\n>> >\n>> > I don't see the logic in here.\n>> >\n>> > git branch topic # here 'branch' is the verb\n>> \n>> Not to me. I assumed the \"branch\" is always a noun in \"git branch\", and\n>> the actual meaning of this command is:\n>> \n>> git branch [create|new] topic\n>> \n>> I.e., creation just being the default action taken on the branch.\n>\n> The question is not what you assumed, the question is can other people\n> assume otherwise?\n\nSure they can, and that's part of the problem. I described how *I* see\nit, as I try to interpret things as coherently as possible, and I don't\nlike to interpret \"branch\" in \"git branch\" as either noun or verb\ndepending on options when universal interpretation as noun is\nsufficient.\n\n>\n> \"branch\" can be a verb, that's a fact.\n\nYep, who argues?\n\nMy argument is that specifically in \"git branch\" it could be universally\ninterpreted as noun, but can't universally be interpreted as verb, so\n/for me/ it's noun there.\n\n>\n>> >> To me, while the latter is obvious, it's verb and specifies the action\n>> >> to be performed, the former looks more like \"whatever you want to do\n>> >> with branches\", and thus the \"branch\" is a noun there and the command\n>> >> thus is object-oriented.\n>> >\n>> > I agree, and I did have indeed noticed the inconsistency. But there's\n>> > another category of commands that receive subcommands, like:\n>> >\n>> > git remote $subcommand\n>> > git worktree $subcommand\n>> > git bisect $subcommand\n>> >\n>> > In my opinion `git branch` fits more these subcommand commands, and it\n>> > was a mistake to make the subcommands options, it should be:\n>> >\n>> > git branch list\n>> > git branch new\n>> > git branch set-upstream\n>> > git branch move\n>> > ...\n>> >\n>> > Now the verb is crystal-clear.\n>> \n>> Yes, lacking (assumed) subcommands is yet another dimension of\n>> inconsistencies.\n>> \n>> I mean what I'm after is inconsistency of the first argument to \"git\".\n>> It's being the verb more often is where we currently are, at least when\n>> considering \"primary\" commands that \"git help\" outputs. \n>> \n>> I mean, consider:\n>> \n>> git branch new nice-feature\n>> \n>> vs\n>> \n>> git new branch nice-feature\n>> \n>> It should have been the latter, when in fact it's currently the\n>> [reduced] former.\n>\n> I disagree. I prefer the former.\n\n git create branch \"nice-feature\"\n\nAlmost plain human language. Isn't it nice? I mean I fail to see why\nyou prefer the former, but I don't care that much either.\n\n>\n> Either way this is way too far from the original point. I don't think\n> you can convince me that `git new branch` makese sense, but there's no\n> need for that.\n>\n> To move forward we need to find consensus, and if you and me agree that\n> `git branch new` makes sense, that's where we should focus on.\n\nIt does make sense, in isolation.\n\nNo, I don't think it's an option, as unfortunately for your preferences,\n\n git branch new\n\nlooks impossible to introduce in a backward compatible manner, nor there\nis significant need to, as\n\n git branch\n\nalready does the job, even if by introducing syntax irregularity. \n\n>\n> Even standardizing `git branch` would be an almost-impossible task, even\n> if we manage to convince others. `git new branch` even more\n> impossible.\n\nQuite an opposite. In fact it's easier to add new ways of doing things\nthat, provided they prove being useful, eventually obsolete and replace\nold ways. \"git switch\" and \"git restore\" are recent examples of that.\n\nThat's why I started to discuss \"git new\" that does not yet exist. No, I\ndon't think it will be there any time soon, as there are more important\nthings to improve in Git, and then overall consistency of Git command\ninterfaces is not recognized by the community as a valuable design goal\nanyway.\n\nThus, for foreseeable future we will likely continue to witness hot\ndiscussions of what \"looks reasonable\" and what not, contenders lacking\ncommon ground that some basic principles of design agreed upon would\nhave provided.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429853","messageId":"60ecd216bd177_a7177208bc@natae.notmuch","threadId":"56027","inReplyTo":"87czrnf8bj.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-12T23:36:54Z","receivedAt":"2021-07-12T23:36:59Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Sergey Organov wrote:\n> Felipe Contreras writes:\n> > Sergey Organov wrote:\n> >> Felipe Contreras writes:\n\n> >> > I don't see the logic in here.\n> >> >\n> >> > git branch topic # here 'branch' is the verb\n> >> \n> >> Not to me. I assumed the \"branch\" is always a noun in \"git branch\", and\n> >> the actual meaning of this command is:\n> >> \n> >> git branch [create|new] topic\n> >> \n> >> I.e., creation just being the default action taken on the branch.\n> >\n> > The question is not what you assumed, the question is can other people\n> > assume otherwise?\n> \n> Sure they can, and that's part of the problem. I described how *I* see\n> it, as I try to interpret things as coherently as possible, and I don't\n> like to interpret \"branch\" in \"git branch\" as either noun or verb\n> depending on options when universal interpretation as noun is\n> sufficient.\n> \n> > \"branch\" can be a verb, that's a fact.\n> \n> Yep, who argues?\n> \n> My argument is that specifically in \"git branch\" it could be universally\n> interpreted as noun, but can't universally be interpreted as verb, so\n> /for me/ it's noun there.\n\nYeah, but universal interpretation is not part of human language.\nContext is always relevant.\n\nSometimes it can be a verb.\n\n> >> > I agree, and I did have indeed noticed the inconsistency. But there's\n> >> > another category of commands that receive subcommands, like:\n> >> >\n> >> > git remote $subcommand\n> >> > git worktree $subcommand\n> >> > git bisect $subcommand\n> >> >\n> >> > In my opinion `git branch` fits more these subcommand commands, and it\n> >> > was a mistake to make the subcommands options, it should be:\n> >> >\n> >> > git branch list\n> >> > git branch new\n> >> > git branch set-upstream\n> >> > git branch move\n> >> > ...\n> >> >\n> >> > Now the verb is crystal-clear.\n> >> \n> >> Yes, lacking (assumed) subcommands is yet another dimension of\n> >> inconsistencies.\n> >> \n> >> I mean what I'm after is inconsistency of the first argument to \"git\".\n> >> It's being the verb more often is where we currently are, at least when\n> >> considering \"primary\" commands that \"git help\" outputs. \n> >> \n> >> I mean, consider:\n> >> \n> >> git branch new nice-feature\n> >> \n> >> vs\n> >> \n> >> git new branch nice-feature\n> >> \n> >> It should have been the latter, when in fact it's currently the\n> >> [reduced] former.\n> >\n> > I disagree. I prefer the former.\n> \n> git create branch \"nice-feature\"\n> \n> Almost plain human language. Isn't it nice?\n\nBut I'm not talking to a human. If I wast talking to a human I would say\n\"create a branch called X\", and \"with git\" would be implied.\n\nBut there's no \"create\" binary on my system. Why would there be? I've\nbeen using Linux systems for more than 20 years, I know that if I want\nto do something with vim, I have to start the command with 'vim'.\n\n> > Even standardizing `git branch` would be an almost-impossible task, even\n> > if we manage to convince others. `git new branch` even more\n> > impossible.\n> \n> Quite an opposite. In fact it's easier to add new ways of doing things\n> that, provided they prove being useful, eventually obsolete and replace\n> old ways. \"git switch\" and \"git restore\" are recent examples of that.\n\nThat's what *should* be the case, but this discussion proves that even\nexperimental commands (which are clearly demarcated as experimental) are\nhard to change.\n\nMoreover, keep in mind that the person who managed to introduce both\n`git switch` and `git resotre` already left the project. That should\ngive you a pretty good idea of how much faith he has on these commands\neventually being useful.\n\nSure, at this point in time introducing `git branch new` might be\nimpossible, however, `git branch --new` isn't. And if we agree on what\nshould have been the case for `git branch`, then what should be the case\nfor `git switch` is more attainable.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"429885","messageId":"d3678ef6-1bcd-2666-87dc-751aef2ca1a7@mfriebe.de","threadId":"56027","inReplyTo":"60ecbe577a086_a6b702082@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-13T10:42:56Z","receivedAt":"2021-07-13T10:43:04Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 13/07/2021 00:12, Felipe Contreras wrote:\n> Martin wrote:\n> A user that does:\n> \n> git switch -n \n> \n> Would naturally expect a new branch to be created.\n> \n> If that command creates a new branch safely, why would the user do:\n> \n> git switch -N \n> \n> What do you think the user expects to happen without reading the\n> documenation?\n\nWell, first of all what would he think it does if he reads the doc? And \nif that doc looses no (explicit) word on the possible loss?\n\nFirst of all (not sure, if I mentioned that before), I have seen *many* \ncase like that:\nThe user wants to create a new branch on master \"my-feature\".\n git switch -c my-feature\nThen he realizes that he had not been on master, but on some other \nbranch. \"-c\" now gives an error.\nSo the user reads the documentation.\nUp to this point, everything is exactly as it should be.\nNow what the user reads is that \"-C\" works if the branch already exists. \nAt this point, without being prompted those user will not think of any \ncontent of the branch (they haven't even added some).\n\"-C\" does in that case what they want.\n\nOf course now, that they had no need to think about any commits, an no \nwarning that would have prompted that, they believe \"-C\" to be save.\nNext time they will have commit. And they are gone.\n\nAnd as for the reflog, look at \"checkout -B\", \"switch -C\", \"branch -f\", \nor \"reset\".\nIn the context of re-creating/ressetting a branch, neither of them \nmention how to get it back. (and reflog is something most people learn a \nlot later)\n\nAs I said, the first part I have seen many times. The 2nd part, \nobviously only a subset. But that is rather down to people being lucky, \nthan to people actually understanding that the commits will disappear.\n\nNow, of course I cannot predict how many people would remember a warning \nit the docs.\nBut I can tell, if I read a doc, and it says \"you may loose...\", I will \npay attention.\n\n\n\n\n> \n> And what do you think they'll expect to happen given this documentation:\n> \n> Create a new branch like '--new', but if the branch already exists\n> it's replaced.\n> \n> Forget about what they could misunderstand. Nobody does anything without\n> a reason, so what would be the reason why a user does `git switch -N`\n> instead of `git switch -n`?\n> \n\nYou and I will make the connection between \"something happens to the \nbranch\" and \"something happens to the commits\".\nA lot of people with less experience, who a busy looking through lots of \nstuff to solve their problem, they will not make that connection in that \nparticular moment.\nHeck, I've seen highly educated people missing far more obvious things \nlike that.\n\n\n> To me this is another instance of \"do not drink scorching hot coffee\".\n> Sure, some users might benefit from reading this, but how many? And how\n> many would be annoyed by the obvious unnecessary warning?\n\nWell, at least in the U.S, you apparently have to tell your customers \nthat the coffee you sell is hot. (If you recall, there was a \"famous\" \ncourt case).\nI have always thought, that coffee should be hot (except iced coffee).\nYou also have to warn people not to put their pets into the microwave. \nAgain to me: bleeding obvious.\n\n\n\n> \n> Moreover, most users don't even read the documentation. Some might even\n> be doing `git switch -h`, and others using zsh completion description.\n> So we can't just rely on them reading this line.\n\nWell, so we can't warn the rest? Why do we have docs at all?\n\n\n> \n> If you are really worried about the user losing information, why don't\n> we add a true warning:\n> \n> hint: The previous state of the '%s' branch might have been lost.\n> hint: The id was '%s'.\n> hint:\n> hint: If you didn't intend to do this, you can restore the previous\n> hint: state with:\n> hint:\n> hint: git reset --hard @{1}\n> hint:\n> hint: Disable this message with \"git config advice.switchForceNew false\"\n> \n> That way the user doesn't need to read the documentation.\n\nWell yes, printing a recovery note, may be another helpful addition.\n\nBut as you said, a single way of pushing info, will not reach everyone. \nPeople putting the command in a script, may not read this.\nBtw, a better warning would be similar to the one you get, if you leave \nbehind a detached commit.\nIIRC, print the sha1, and how to create a branch on that sha1.\n\n\n\nOf course there is a different alternative, but IMHO it is overdone.\n git switch -C branch\nwill only force the current \"head value\" (I.e. the sha1 used a pointer).\nSo if you have no commits on that branch, or if they are part of another \nbranch, then this will work.\n\nIf you stand to \"loose\" commits, you would have to do:\n git switch -D -C branch\n\n(the D is just an example / other letters/words may be better)\n -D drop commits\n\n\nBut even, then until that is implemented, a temporary fix by changing \nthe docs would still be appropriate.\n"},{"id":"429886","messageId":"87y2aalbvq.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"60ec715c8338_a452520896@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-13T10:57:29Z","receivedAt":"2021-07-13T10:57:34Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Felipe Contreras writes:\n\n> Sergey Organov wrote:\n>> Felipe Contreras writes:\n>> \n>> > Sergey Organov wrote:\n>> \n>> [...]\n>> \n>> >> Creating (a branch) is fundamentally different operation than switching\n>> >> to (a branch), and that's why the former doesn't fit into \"git switch\".\n>> >\n>> > Not in my mind. Instead of switching to an existing branch, I'm switching\n>> > to a new branch, which is easily understood by\n>> > `git switch --new branch`.\n>> \n>> To me:\n>> \n>> \"create a new branch\" is basic operation.\n>> \n>> \"switch to another branch\" is basic operation.\n>> \n>> \"create a new branch and then switch to it\" is compound operation.\n>\n> Compound operations soon become basic operations in the mind of an\n> expert.\n>\n> Lifting your feet, and then landing your feet might be basic operations\n> when you are 1 yo, but soon enough they become \"walking\".\n\n[caveat: please don't take the rest of this post too seriously]\n\nYeah, using another name for a compound is yet another option indeed.\n\"git cretching\"?\n\n>\n> Similarly checking out a commit and then cherry-picking a sequence of\n> commits while resolving conflicts becomes \"rebasing\".\n\nThis is very questionable example. Please don't let me even start on\nthis.\n\n>\n> In my mind I'm not doing two operations, it's one operation with a\n> modifier:\n>\n> git switch --new branch\n>\n> --new is an adverb, not an operation.\n\nWell, let's see:\n\n git walk \"First Avenue\"\n git walk parkway\n\nthen, suddenly:\n\n git walk --new road\n\nJust an adverb, a modifier. As if no any additional operations were\nactually needed. Minecraft: who cares? Just saying.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"429887","messageId":"3c32c82c-5121-285a-036f-08e6daa320eb@mfriebe.de","threadId":"56027","inReplyTo":"87czrnf8bj.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-13T11:20:15Z","receivedAt":"2021-07-13T11:20:22Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 13/07/2021 00:58, Sergey Organov wrote:\n> Felipe Contreras writes:\n>> I disagree. I prefer the former.\n> \n> git create branch \"nice-feature\"\n> \n> Almost plain human language. Isn't it nice? I mean I fail to see why\n> you prefer the former, but I don't care that much either.\n> \n\nBut human language is not always the best to express something to a \ncomputer (sometimes not even to a human). Human language for starters is \noften very ambiguous. (Not in this particular example, but in general).\n\nSo even if it looks like human language, its not (not a \"duck\" either;) ).\nIt still needs each token (each word is a token) to be documented.\n\nThe \"create\" vs \"new\" is a good example.\n- \"creating\" still happens when you add commits into the branch (human \nlanguage \"branch\"). Because that's what the branch wants to be, a series \nof commits. You keep creating it, until its done, then you merge it.\n- \"new\" of course is not a verb...\n\n git prepare branch\nwould probably be more accurate.\nBut I am sure it has flaws too.\n\n\n> No, I don't think it's an option, as unfortunately for your preferences,\n> \n> git branch new\n> \n> looks impossible to introduce in a backward compatible manner, nor there\n> is significant need to, as\n> \n> git branch\n> \n> already does the job, even if by introducing syntax irregularity.\n\nIt is not that it already does the job (\"git stash push\" and \"git stash\" \nboth do the job)\n\nBut in\n git branch new\n\"new\" would be the name of a branch. :(\n\nBut at some point, it was indicated that this is about finding \nguidelines for future additions.\nSo not all old commands need to be \"fixed\".\n\nNot that they are broken. They are fine. We do not need to break them by \nadding a rule like that.\n\nAnd\n git noun verb \n git verb \nworks as guideline for new additions.\n\nOf course you want to add\n git verb noun\nwhich I personally to not favour.\n\n"},{"id":"429898","messageId":"60edb8ff814cf_ab6dd208d9@natae.notmuch","threadId":"56027","inReplyTo":"d3678ef6-1bcd-2666-87dc-751aef2ca1a7@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-13T16:02:07Z","receivedAt":"2021-07-13T16:02:12Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 13/07/2021 00:12, Felipe Contreras wrote:\n> > Martin wrote:\n> > A user that does:\n> > \n> > git switch -n \n> > \n> > Would naturally expect a new branch to be created.\n> > \n> > If that command creates a new branch safely, why would the user do:\n> > \n> > git switch -N \n> > \n> > What do you think the user expects to happen without reading the\n> > documenation?\n> \n> Well, first of all what would he think it does if he reads the doc? And \n> if that doc looses no (explicit) word on the possible loss?\n> \n> First of all (not sure, if I mentioned that before), I have seen *many* \n> case like that:\n> The user wants to create a new branch on master \"my-feature\".\n> git switch -c my-feature\n> Then he realizes that he had not been on master, but on some other \n> branch. \"-c\" now gives an error.\n> So the user reads the documentation.\n> Up to this point, everything is exactly as it should be.\n> Now what the user reads is that \"-C\" works if the branch already exists. \n> At this point, without being prompted those user will not think of any \n> content of the branch (they haven't even added some).\n> \"-C\" does in that case what they want.\n> \n> Of course now, that they had no need to think about any commits, an no \n> warning that would have prompted that, they believe \"-C\" to be save.\n\nWhy would they think -C \"saves\"? And save how?\n\n> > And what do you think they'll expect to happen given this documentation:\n> > \n> > Create a new branch like '--new', but if the branch already exists\n> > it's replaced.\n> > \n> > Forget about what they could misunderstand. Nobody does anything without\n> > a reason, so what would be the reason why a user does `git switch -N`\n> > instead of `git switch -n`?\n> \n> You and I will make the connection between \"something happens to the \n> branch\" and \"something happens to the commits\".\n> A lot of people with less experience, who a busy looking through lots of \n> stuff to solve their problem, they will not make that connection in that \n> particular moment.\n> Heck, I've seen highly educated people missing far more obvious things \n> like that.\n\nOnce again I'm not talking about what they could miss, I'm talking about\nwhat they are thinking the command will do.\n\n> > To me this is another instance of \"do not drink scorching hot coffee\".\n> > Sure, some users might benefit from reading this, but how many? And how\n> > many would be annoyed by the obvious unnecessary warning?\n> \n> Well, at least in the U.S, you apparently have to tell your customers \n> that the coffee you sell is hot. (If you recall, there was a \"famous\" \n> court case).\n\nYes, and that's stupid. There's plenty of unnecessary warnings.\n\n * Do not hold the wrong end of a chainsaw.\n * Do not drive with sun shield in place. \n * Avoid death.\n\nhttps://www.forbes.com/2011/02/23/dumbest-warning-labels-entrepreneurs-sales-marketing-warning-labels_slide.html\n\n> I have always thought, that coffee should be hot (except iced coffee).\n> You also have to warn people not to put their pets into the microwave. \n> Again to me: bleeding obvious.\n\nThe fact that you have to do it in USA doesn't mean you should.\n\n> > Moreover, most users don't even read the documentation. Some might even\n> > be doing `git switch -h`, and others using zsh completion description.\n> > So we can't just rely on them reading this line.\n> \n> Well, so we can't warn the rest? Why do we have docs at all?\n\nTo explain how to use commands.\n\n> > If you are really worried about the user losing information, why don't\n> > we add a true warning:\n> > \n> > hint: The previous state of the '%s' branch might have been lost.\n> > hint: The id was '%s'.\n> > hint:\n> > hint: If you didn't intend to do this, you can restore the previous\n> > hint: state with:\n> > hint:\n> > hint: git reset --hard @{1}\n> > hint:\n> > hint: Disable this message with \"git config advice.switchForceNew false\"\n> > \n> > That way the user doesn't need to read the documentation.\n> \n> Well yes, printing a recovery note, may be another helpful addition.\n> \n> But as you said, a single way of pushing info, will not reach everyone. \n\nOur objective is not to reach everyone.\n\n-- \nFelipe Contreras\n"},{"id":"429899","messageId":"60edbaefa0208_ab6dd2081f@natae.notmuch","threadId":"56027","inReplyTo":"87y2aalbvq.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-13T16:10:23Z","receivedAt":"2021-07-13T16:10:27Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Sergey Organov wrote:\n> Felipe Contreras writes:\n> \n> > Sergey Organov wrote:\n> >> Felipe Contreras writes:\n> >> \n> >> > Sergey Organov wrote:\n> >> \n> >> [...]\n> >> \n> >> >> Creating (a branch) is fundamentally different operation than switching\n> >> >> to (a branch), and that's why the former doesn't fit into \"git switch\".\n> >> >\n> >> > Not in my mind. Instead of switching to an existing branch, I'm switching\n> >> > to a new branch, which is easily understood by\n> >> > `git switch --new branch`.\n> >> \n> >> To me:\n> >> \n> >> \"create a new branch\" is basic operation.\n> >> \n> >> \"switch to another branch\" is basic operation.\n> >> \n> >> \"create a new branch and then switch to it\" is compound operation.\n> >\n> > Compound operations soon become basic operations in the mind of an\n> > expert.\n> >\n> > Lifting your feet, and then landing your feet might be basic operations\n> > when you are 1 yo, but soon enough they become \"walking\".\n> \n> [caveat: please don't take the rest of this post too seriously]\n> \n> Yeah, using another name for a compound is yet another option indeed.\n> \"git cretching\"?\n> \n> > Similarly checking out a commit and then cherry-picking a sequence of\n> > commits while resolving conflicts becomes \"rebasing\".\n> \n> This is very questionable example. Please don't let me even start on\n> this.\n\nYou don't need to validate the concept, but chunking is an established\nconcept in cognitive pshychology [1]. It's how humans learn (and\npossibly machines too).\n\n> > In my mind I'm not doing two operations, it's one operation with a\n> > modifier:\n> >\n> > git switch --new branch\n> >\n> > --new is an adverb, not an operation.\n> \n> Well, let's see:\n> \n> git walk \"First Avenue\"\n> git walk parkway\n> \n> then, suddenly:\n> \n> git walk --new road\n> \n> Just an adverb, a modifier. As if no any additional operations were\n> actually needed. Minecraft: who cares? Just saying.\n\nThat's how my mind works, regardless of what you think about it.\n\nAnd any experienced driver of manual cars would tell you that they don't\nthink in terms of pressing pedals and moving the gear stick. The\nindividual operations are meaningless.\n\n[1] https://en.wikipedia.org/wiki/Chunking_(psychology)\n\n-- \nFelipe Contreras\n"},{"id":"430104","messageId":"874kcwemhn.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"60edbaefa0208_ab6dd2081f@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-14T19:14:44Z","receivedAt":"2021-07-14T19:14:51Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Felipe Contreras writes:\n\n> Sergey Organov wrote:\n>> Felipe Contreras writes:\n>> \n>> > Sergey Organov wrote:\n>> >> Felipe Contreras writes:\n>> >> \n>> >> > Sergey Organov wrote:\n>> >> \n>> >> [...]\n>> >> \n>> >> >> Creating (a branch) is fundamentally different operation than switching\n>> >> >> to (a branch), and that's why the former doesn't fit into \"git switch\".\n>> >> >\n>> >> > Not in my mind. Instead of switching to an existing branch, I'm switching\n>> >> > to a new branch, which is easily understood by\n>> >> > `git switch --new branch`.\n>> >> \n>> >> To me:\n>> >> \n>> >> \"create a new branch\" is basic operation.\n>> >> \n>> >> \"switch to another branch\" is basic operation.\n>> >> \n>> >> \"create a new branch and then switch to it\" is compound operation.\n>> >\n>> > Compound operations soon become basic operations in the mind of an\n>> > expert.\n>> >\n>> > Lifting your feet, and then landing your feet might be basic operations\n>> > when you are 1 yo, but soon enough they become \"walking\".\n>> \n>> [caveat: please don't take the rest of this post too seriously]\n>> \n>> Yeah, using another name for a compound is yet another option indeed.\n>> \"git cretching\"?\n>> \n>> > Similarly checking out a commit and then cherry-picking a sequence of\n>> > commits while resolving conflicts becomes \"rebasing\".\n>> \n>> This is very questionable example. Please don't let me even start on\n>> this.\n>\n> You don't need to validate the concept, but chunking is an established\n> concept in cognitive pshychology [1]. It's how humans learn (and\n> possibly machines too).\n\nThe urdge to dive into the muddy waters of psychology to support your\nexample, where pure logic should probably have sufficed, makes the\nexample only even more suspect.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"430113","messageId":"60ef404076d18_9578a2089a@natae.notmuch","threadId":"56027","inReplyTo":"874kcwemhn.fsf@osv.gnss.ru","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-14T19:51:28Z","receivedAt":"2021-07-14T19:59:49Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Sergey Organov wrote:\n> Felipe Contreras writes:\n> > Sergey Organov wrote:\n> >> Felipe Contreras writes:\n\n> >> > Compound operations soon become basic operations in the mind of an\n> >> > expert.\n> >> >\n> >> > Lifting your feet, and then landing your feet might be basic operations\n> >> > when you are 1 yo, but soon enough they become \"walking\".\n> >> \n> >> [caveat: please don't take the rest of this post too seriously]\n> >> \n> >> Yeah, using another name for a compound is yet another option indeed.\n> >> \"git cretching\"?\n> >> \n> >> > Similarly checking out a commit and then cherry-picking a sequence of\n> >> > commits while resolving conflicts becomes \"rebasing\".\n> >> \n> >> This is very questionable example. Please don't let me even start on\n> >> this.\n> >\n> > You don't need to validate the concept, but chunking is an established\n> > concept in cognitive pshychology [1]. It's how humans learn (and\n> > possibly machines too).\n> \n> The urdge to dive into the muddy waters of psychology to support your\n> example, where pure logic should probably have sufficed, makes the\n> example only even more suspect.\n\nSuspect to you, maybe, not to anyone who works in the teaching industry,\nwhere this concept is well understood and accepted.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"430125","messageId":"87o8b4d3vl.fsf@osv.gnss.ru","threadId":"56027","inReplyTo":"60ef404076d18_9578a2089a@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2021-07-14T20:42:06Z","receivedAt":"2021-07-14T20:42:12Z","isPatch":false,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Felipe Contreras writes:\n\n> Sergey Organov wrote:\n>> Felipe Contreras writes:\n>> > Sergey Organov wrote:\n>> >> Felipe Contreras writes:\n>\n>> >> > Compound operations soon become basic operations in the mind of an\n>> >> > expert.\n>> >> >\n>> >> > Lifting your feet, and then landing your feet might be basic operations\n>> >> > when you are 1 yo, but soon enough they become \"walking\".\n>> >> \n>> >> [caveat: please don't take the rest of this post too seriously]\n>> >> \n>> >> Yeah, using another name for a compound is yet another option indeed.\n>> >> \"git cretching\"?\n>> >> \n>> >> \n>> >> This is very questionable example. Please don't let me even start on\n>> >> this.\n>> >\n>> > You don't need to validate the concept, but chunking is an established\n>> > concept in cognitive pshychology [1]. It's how humans learn (and\n>> > possibly machines too).\n>> \n>> The urdge to dive into the muddy waters of psychology to support your\n>> example, where pure logic should probably have sufficed, makes the\n>> example only even more suspect.\n>\n> Suspect to you, maybe, not to anyone who works in the teaching industry,\n> where this concept is well understood and accepted.\n\nWell, if you've replied to them, then I'm sorry.\n\nTo me your particular example:\n\n>>> Similarly checking out a commit and then cherry-picking a sequence\n>>> of commits while resolving conflicts becomes \"rebasing\".\n\nremains controversial; concepts or no concepts.\n\nThanks,\n-- \nSergey Organov\n"},{"id":"430367","messageId":"d264e1b6-dde4-025f-c137-86345ba55d4e@mfriebe.de","threadId":"56027","inReplyTo":"60edb8ff814cf_ab6dd208d9@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-16T18:12:12Z","receivedAt":"2021-07-16T18:12:16Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 13/07/2021 18:02, Felipe Contreras wrote:\n> Martin wrote:\n>> Of course now, that they had no need to think about any commits, an no\n>> warning that would have prompted that, they believe \"-C\" to be save.\n> \n> Why would they think -C \"saves\"? And save how?\n> \nSorry, spelling.\n\n\"safe\"\n\n"},{"id":"430369","messageId":"02f1f12a-0ff3-ef46-fce3-e222b2867309@mfriebe.de","threadId":"56027","inReplyTo":"60edb8ff814cf_ab6dd208d9@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-16T18:31:33Z","receivedAt":"2021-07-16T18:31:39Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 13/07/2021 18:02, Felipe Contreras wrote:\n> Martin wrote\n>> You and I will make the connection between \"something happens to the\n>> branch\" and \"something happens to the commits\".\n>> A lot of people with less experience, who a busy looking through lots of\n>> stuff to solve their problem, they will not make that connection in that\n>> particular moment.\n>> Heck, I've seen highly educated people missing far more obvious things\n>> like that.\n> \n> Once again I'm not talking about what they could miss, I'm talking about\n> what they are thinking the command will do.\n\n\nWell they think it creates a new branch with the given name. And that is \n*all* they think.\n\nWe can argue as much as we want, that from that thought all else should \nfollow, in reality that does not apply.\n\nOr rather it applies only if someone really ask the question. But no one \nasks it.\n\nAnd that leaves as with the point how much of the so called obvious is \nnot being thought about. My answer: Quite a lot, and an important lot too.\n\nIf people would always consider the consequences of their actions, this \nworld would have a lot less trouble.\n\nBut that again gets to the point of what is not thought of. People to \nnot think of consequence.\n\nIf people a told the consequences some will still ignore it, but some \nwill take it into account.\n\n\n> \n> Yes, and that's stupid. There's plenty of unnecessary warnings.\n\nYes and that is why we do not need to add\n\"a solarflare may damage your pc while you perform this action\"\n(As was previously brought up)\n\n\n> \n> The fact that you have to do it in USA doesn't mean you should.\n\nWell, yes. But the point is, there are people who miss out for more \nobvious things.\nAnd \"loosing commits\" as results of an action on \"branches\" is not that \nobvious. Not if you are new.\n\nI understand that it is as bleeding obvious to you (and me) as \"hot coffee\".\nBut neither of us is a new user. Not even the average (I guess)\n\n> \n> Our objective is not to reach everyone.\n> \n\n\"everyone that uses git\" (and wants to be reached)\n\nAnd that should be an objective.\n\n\n"},{"id":"430374","messageId":"60f1d650e2667_330208e@natae.notmuch","threadId":"56027","inReplyTo":"02f1f12a-0ff3-ef46-fce3-e222b2867309@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-16T18:56:16Z","receivedAt":"2021-07-16T18:56:26Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin wrote:\n> On 13/07/2021 18:02, Felipe Contreras wrote:\n> > Martin wrote\n> >> You and I will make the connection between \"something happens to the\n> >> branch\" and \"something happens to the commits\".\n> >> A lot of people with less experience, who a busy looking through lots of\n> >> stuff to solve their problem, they will not make that connection in that\n> >> particular moment.\n> >> Heck, I've seen highly educated people missing far more obvious things\n> >> like that.\n> > \n> > Once again I'm not talking about what they could miss, I'm talking about\n> > what they are thinking the command will do.\n> \n> Well they think it creates a new branch with the given name. And that is \n> *all* they think.\n\nNo. You are avoiding the question.\n\n-c creates a new branch. Obviously -C creates a new branch too.\n\nOnce again, *why* would they pick -C over -c? What do they think it will\ndo differently?\n\n> > Yes, and that's stupid. There's plenty of unnecessary warnings.\n> \n> Yes and that is why we do not need to add\n> \"a solarflare may damage your pc while you perform this action\"\n> (As was previously brought up)\n\nExactly. Unnecessary warnings are unnecessary.\n\n> > The fact that you have to do it in USA doesn't mean you should.\n> \n> Well, yes. But the point is, there are people who miss out for more \n> obvious things.\n\nThat's almost meaningless. Like, *some* people have more than five\nfingers per hand.\n\nYes, but how many? 1 in 2? 1 in 100? 1 in a million?\n\nBothering 99.99% of users with a useless warning just because one (who\nis not the sharpest pencil in the box) might make a mistake is just not\nwise.\n\n> > Our objective is not to reach everyone.\n> > \n> \n> \"everyone that uses git\" (and wants to be reached)\n> \n> And that should be an objective.\n\nImpossible objectives are no possible to achieve. Just like trying to be\nliked by everyone. You are just going to waste your time, and fail.\n\n\nThat being said, we don't have to agree. And we don't have to\ncontinuously discuss forever. At some point you need to send a new\nversion of your patch, and I think that point is long past due.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"430414","messageId":"db554ab1-11b3-d7e9-6b64-799bc79cb622@mfriebe.de","threadId":"56027","inReplyTo":"60f1d650e2667_330208e@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-17T07:02:32Z","receivedAt":"2021-07-17T07:02:43Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 16/07/2021 20:56, Felipe Contreras wrote:\n> Martin wrote:\n>> On 13/07/2021 18:02, Felipe Contreras wrote:\n>>> Martin wrote\n>>>> You and I will make the connection between \"something happens to the\n>>>> branch\" and \"something happens to the commits\".\n>>>> A lot of people with less experience, who a busy looking through lots of\n>>>> stuff to solve their problem, they will not make that connection in that\n>>>> particular moment.\n>>>> Heck, I've seen highly educated people missing far more obvious things\n>>>> like that.\n>>>\n>>> Once again I'm not talking about what they could miss, I'm talking about\n>>> what they are thinking the command will do.\n>>\n>> Well they think it creates a new branch with the given name. And that is\n>> *all* they think.\n> \n> No. You are avoiding the question.\n\nI did not avoid it. I answered it, as I understood it. Seems your \nquestion was not very clear.\n\n> \n> -c creates a new branch. Obviously -C creates a new branch too.\n> \n> Once again, *why* would they pick -C over -c? What do they think it will\n> do differently?\n> \n\nThey think: it makes go away that error message. They can use that \nbranchname.\n\nWhat they do not think is: If I take away the old branch name, what \nhappens to the commits in it?\n\nI know, you firmly believe everyone must surely make that conclusion.\nBut that fails several times..\n1) It assumes everyone has enough knowledge to make that conclusion.\nWhile I agree: \"they should\", I acknowledge they might not.\nBut, ok. lets say: \"there fault\". And we don't give a sh*t if others get \ninto problem, because they did not read lots of pages and memorized \nevery detail...e\n\n2) It assumes the can.\nI.e. they have the experience and skill to make the connection. Ok, \nprobably 99% can do.\n\n3) It assumes they do (the attempt to make a connection)\nAnd this is my point. Many people will not attempt to think ahead.\n\n\nPeople at that moment think about the branch, and the branch only. Many \nwill not an all think about commits.\n\nAnd why would they. In git there are plenty of situations where you can \ndelete a branch, without loosing anything else (i.e. without loosing \ncommits), because there is an upstream or another local branch.\nUntil they day that you pick a branch where there is no safety net.\n\n\n\n> \n> Bothering 99.99% of users with a useless warning just because one (who\n> is not the sharpest pencil in the box) might make a mistake is just not\n> wise.\n> \nWell, I see you did a survey over a representative group of randomly \npicked people?\n\nWell, yes I cannot tell you any final number. But from what I observed \nfrom those people that I know, there a quite a few how mistook that \ndocumentation.\nMany (almost most) of those where lucky, in that they had yet only done \nit, when indeed it was safe. But upon question they were surprised that \nit could have gone another way.\n\nYes that is not representative. But even if I say that in real live the \nquota of such misunderstanding is at only 10% of what I saw, that would \nbe a considerable total.\n\n\n> \n> That being said, we don't have to agree. And we don't have to\n> continuously discuss forever. At some point you need to send a new\n> version of your patch, and I think that point is long past due.\n\nYes but part of this has been educative.\n\n(and some of it a bit of fun too)\n\nAnd I said I will.\nBut right now, I have things in my live, that prevent me from doing so \nimmediately.\nThey should prevent me from spending time on those mails too, but I \ncan't always withstand - so some shortened nights ahead.\n\nI will look at sending a patch, when I have good time to do so without \nbeing in any rush.\n\n"},{"id":"430415","messageId":"e57f1d19-d574-5ba5-efc1-abb8ab2a8c01@mfriebe.de","threadId":"56027","inReplyTo":"60f22aaa6a4f1_1f602081b@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-17T10:07:32Z","receivedAt":"2021-07-17T10:07:38Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 17/07/2021 02:56, Felipe Contreras wrote:\n> Martin wrote:\n> It is the Socratic method. If I tell you \"the user will think X\" you are\n> not going to believe me. Therefore I'm asking you what the user will\n> think.\n> \n>> But no one is taking them by the hand. No one is asking all those\n>> questions to them.\n>> So they (new users) will not always make that conclusion.\n> \n> What conclusion would they reach?\n\nYou realize that your question makes no sense?\n\nIf the user does not enter the state of concluding, then they will not \nreach a conclusion at all.\n\nIf you want to challenge my statement, that the user does not start \nconcluding, then you could ask me: Why?\nTo which I have to admit, I do not know, I did not ask those who didn't.\nAnd frankly it does not matter. Lets assume we knew \"why\". Then to \nremedy that cause, some change would be needed. So most likely the doc \nwould need to be changed to have some trigger added, to overcome that \nreason. In the end, that means more info in the doc. Same as what is \nalready proposed.\n\n\n>>> What do they think it will happen?\n>>\n>> They do not think about it at all.\n> \n> This doesn't make any sense. They used -C instead of -c for a reason.\nFor the 4th or 5th time (not going to count the exact number of times I \nhave answered the exact same question)\n\nThe reason is the branchname was used, and the wanted to use it again. \nThe doc says they can use it again. So that is all they want at that moment.\n\nWhy is there an extra option for doing this, good question but to them \nat that point in time: not relevant. The doc of the option does not say, \nthat there may be any consequences, so that is good enough at that moment.\n\nIf you want, you can call them ignorant. But in their defence they may \nnot even know that. They have whatever other issues to solve at that \ntime. They are happy to have found that option, and they really need to \nreturn to whatever other stuff they were doing. So they trust the docs, \nand the docs have no explicit warning.\n\nFrankly all the above, is a very common pattern that lots of people show \nat some time or another. Whatever the problem, people go for whatever \n*appears* to be the easy fix. No thought on what will happen after that. \nIn German their is a saying \"Nach mir die Sinnflut\".\n\n\n>>\n>> Because they did not correctly understand what the net protected the from.\n> \n> Users should not be executing commands they don't understand. If a user\n> doesn't understand what `git delete-this-branch` does, then he shouldn't\n> run it.\n> \nHow can they check they understand it?\n\nSee also the example of the person that makes *two* the conclusions. How \ncan they tell there is nothing further that they need to conclude?\n\n\n> If the documentation says a command overwrites a branch, and the user\n> runs the command anyway,\nSo is that an admission that people may not always come to the conclusion?\nI.e., what I said: They do not think about that part at all.\n\n > and the branch is overwritten, git did what the\n> user told it to do, and what happened is the responsibility of the user.\n\nWell, that is a matter of philosophical debate.\n\nIt does not say \"commits may be affected\".\nI think or hope, that we can agree the effect on commits is something, \nthat is to be concluded. The discrepancy we have is, whether it will be \nconcluded by all users (\"all\" is to mean a high percentage leaving no \nsignificant rest).\n\nIf we agree on that \"conclusion\" statement, then the discrepancy we have \ncan be further deducted on whether there is such an \"significant rest\" \namount of users.\n\nI believe there is. You do afaik not believe this.\n\nBut if there is (or \"if there were\") such an significant amount of \nusers, then it would be a valuable addition to add text, that add the \nresult of that conclusion.\n\n\nSo then all the \"what would they think...\" question do not really \nmatter. It does not matter what they think, if it is not what they are \nexpected to think. If there is a significant amount of people who for \nany reason whatsoever do not think this, then I believe the \ndocumentation should respect the fact, that those people exist (and more \nthan just as an exception).\n\n\n\n\n\n>>> Let me try yet another analogy.\n>>>\n>>> If an alarm clock has two buttons \"snooze\" and \"off\".\n>> How exactly is that connected?\n>> This is a random story. Not an analogy.\n> \n> The fact that you don't see the analogy doesn't mean it isn't one.\n> \n> Did the user click \"off\" for a reason?\n\n\"Off\" is not called \"force snooze\". Off does not require to conclude \ninfo, as \"-C\" does.\n\nLets say, there is a \"change timezone\" and a \"force change timezone\" \nbutton, and the first one would reject to work, if an alarm is active, \nthe 2nd would work even if an alarm exists.\nThen that would be an analogy. Because then the user has to figure out, \nthat changing the timezone would change the displayed hour, and as a \nconsequence clear the alarm.\n\nIn your example, where is the conclusion the user has to make?\n\n\n\n>>> Mistook it for what? What did they expect it was going to happen?\n>> I have answered that in great detail, at least 3 times in this mail thread.\n> \n> I'm sorry, but no, \"they'll think nothing and they'll do it for no\n> reason\" is not an answer.\nWell, that is not what I wrote.\n\n\n"},{"id":"430447","messageId":"1cb8774e-2489-e8aa-12ce-8d7e34b700ff@mfriebe.de","threadId":"56027","inReplyTo":"60f33f8a7c39b_507220823@natae.notmuch","subject":"Re: PATCH: improve git switch documentation","fromName":"Martin","fromEmail":"git@mfriebe.de","sentAt":"2021-07-17T21:23:54Z","receivedAt":"2021-07-17T21:24:00Z","isPatch":false,"sender":{"key":"git@mfriebe.de","avatar":null},"body":"On 17/07/2021 22:37, Felipe Contreras wrote:\n>> If the user does not enter the state of concluding, then they will not\n>> reach a conclusion at all.\n> \n> If they had not reached a conclussion of what the command would do, then\n> they would have not typed the command.\n\nPlease re-read my previous answers.\n\n> \n> But they did type the command. Therefore they reached a conclussion about\n> what the command would do.\n\nPlease re-read my previous answers.\n\n> Just like before I click \"send\" I had already reached a conclussion\n> about what that command will do, otherwise why would I click it?\n> \n\nAre you sure that a\n- all your information was by conclusion, and none by other means?\n- your conclusions where complete?\n\nFor the 2 above points, I pointed out several times that the users had \npartial info, and did not realize that it was incomplete.\nThey were happy with what the partial info was, therefore they run the \ncommand.\nThey never realized there was more.\n\nBy clicking \"send\" you have therefore revealed, that you have either not \nread, or otherwise not realized the content of those previous \nexplanations of mine.\nDid you really conclude that before clicking send?\n\n> I do not want to challenge your statement. Either you see what is\n> obvious to me, or you don't.\nI think I do see what is obvious to you. Unfortunately however that what \nyou (afaik) think to be obvious, that is wrong.\n\nYou appear to believe a partial realization of what -C does is not \npossible. That for some reason, a user either realizes the full extend \nor nothing. No middle ground.\n\nBut that middle ground exists.\n\nIIRC It was you who suggested something along the lines \"taking steps \nbecomes walking\".\nWell, when I walk, I do not think about the steps. I do not realize \nthem, nor conclude their existence.\nSo it is possible to overlook important parts of a given whole.\n\n\n\n> To me it's obvious that effect comes after cause.\nWhich has nothing to do with the issue at hand.\n\nAs soon as you see any part of the effect, that statement is satisfied. \nYou cause something, you see some effect. All is good.\nBut if what you saw is only a fraction of the entire effect, then you \nmay never know.\n\nWhen mankind started burning fuel, did they do so knowingly that it \nwould destroy the environment, which they need to survive?\nAccording to you they must have, its an effect. They did the cause, they \nburned the fuel. The must have known the effect it would have.\n\nWell they would have, if it had come with a documentation including a \nproper warning ;)\n\n\n>> For the 4th or 5th time (not going to count the exact number of times I\n>> have answered the exact same question)\n> \n> Repeating \"I have washed the dishes properly\" multiple times doesn't mean\n> that you actually did it.\n\nYes, but you repeat the question.\nRather than pointing out, what in your view is incorrect in my \nstatement, you ask the same question again hoping for a different answer.\n\n> \n>> The reason is the branchname was used, and the wanted to use it again.\n> \n> What does \"use it again\" mean?\n\nTo them: Create a branch of that name at some commit.\nTo me: much more.\n\n\n> It does matter to me. Unless I see evidence for the existence of\n> something, I'm not going to *assume* that that something exists.\n> \nBut you assume that the following exists: \"With the current doc, all \nusers are fully aware of all consequence\"\n\nYet you have no prove for that. You only can have prove that this \napplies to those you know (or those you ask).\n\nSo, since you have no proof, you can not assume that a situation exists \nin which the current doc is sufficient.\n\n\n>> \"Off\" is not called \"force snooze\". Off does not require to conclude\n>> info, as \"-C\" does.\n> \n> It's a \"yes\" or \"no\" question. Did he have a reason to click \"off\"?\n>\n\nWell in the sense that I understand your question: Yes.\n\nAnd it did do, what the documentation said. Exactly that, and nothing \nmore. So there was no surprise of any kind for that user.\n\nIf you mean to say, he fell asleep again, and the doc had no warning \nagainst that, well good (the doc part, not the falling asleep).\nI also do not request, that we add warnings to the git doc that say \"you \nmay do something wrong, get angry, and in your rage destroy parts of \nyour work\". No we should not add that.\n\nThose are personal issues. The lost commits are a technical issue.\n"},{"id":"430525","messageId":"60f5bb8e15329_13f2e220855@natae.notmuch","threadId":"56027","inReplyTo":"1cb8774e-2489-e8aa-12ce-8d7e34b700ff@mfriebe.de","subject":"Re: PATCH: improve git switch documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-07-19T17:51:10Z","receivedAt":"2021-07-19T17:52:27Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"I already told you I don't think this extended discussion is of interest\nto the mailing list, and that's why I removed it from the receipients.\n\nI'd be more than happy to continue the discussion privately, but please\ndon't add the mailing list again. I won't reply here.\n\nCheers.\n\n-- \nFelipe Contreras\n"}]}