{"thread":{"id":"45645","subject":"Git documentation on branching.","startedAt":"2017-04-10T07:02:54Z","lastAt":"2017-04-11T05:32:36Z","messageCount":6,"participants":["Samuel Åslund","Konstantin Khomoutov","Ævar Arnfjörð Bjarmason"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"316457","messageId":"3563ee7a-1175-2010-7176-0339cd3e60ee@update.uu.se","threadId":"45645","inReplyTo":null,"subject":"Git documentation on branching.","fromName":"Samuel Åslund","fromEmail":"samuel@update.uu.se","sentAt":"2017-04-10T06:56:30Z","receivedAt":"2017-04-10T07:02:54Z","isPatch":false,"sender":{"key":"samuel@update.uu.se","avatar":null},"body":"Hi all.\n\nI just started playing around with branching in git.\nI have been using it more or less as Subversion until now.\n\nOne feature with \"git branch xyz\" and \"git checkout xyz\" that is rather \nobvious if you know them but bit me a little since I did not, is that \nuncommitted work in progress is not affected or saved when switching \nbetween branches. Thus I cleaned up the directory when working with the \nbranch and now I'm trying to find a stash where I hopefully have a copy \nof those files.\n\nWould it be possible to add something in the documentation to warn \nothers that uncommitted work is not saved or affected by branching?\nThe first two hits on my google search was very informative about \nbranching but I did not see that specific nugget of information (I might \nhave been careless reading, but if I did not see it others will probably \nalso miss it).\n\nGit - git-branch Documentation\nhttps://git-scm.com/docs/git-branch\n\nGit - Branches in a Nutshell\nhttps://git-scm.com/book/.../Git-Branching-Branches-in-a-Nutsh...\n\nThis is my first try to contribute to the Git community, I hope it will \nbe useful to somebody.\n\nRegards,\n//Samuel\n"},{"id":"316458","messageId":"20170410101336.c93a423e7d3a8594151bebef@domain007.com","threadId":"45645","inReplyTo":"3563ee7a-1175-2010-7176-0339cd3e60ee@update.uu.se","subject":"Re: Git documentation on branching.","fromName":"Konstantin Khomoutov","fromEmail":"kostix+git@007spb.ru","sentAt":"2017-04-10T07:13:36Z","receivedAt":"2017-04-10T07:54:20Z","isPatch":false,"sender":{"key":"kostix+git@007spb.ru","avatar":null},"body":"On Mon, 10 Apr 2017 08:56:30 +0200\nSamuel Åslund <samuel@update.uu.se> wrote:\n\n> I just started playing around with branching in git.\n> I have been using it more or less as Subversion until now.\n> \n> One feature with \"git branch xyz\" and \"git checkout xyz\" that is\n> rather obvious if you know them but bit me a little since I did not,\n> is that uncommitted work in progress is not affected or saved when\n> switching between branches.\n[...]\n\nBut neither is uncommitted work saved anywhere when you do\n`svn switch` in Subversion which is analogous to `git checkout`.\n\nWhile I do know quite many people expect Git to somehow \"preserve\"\ntheir work when switching branches without having them do anything,\nI wonder what in Subversion workflow makes you think Git should have\nhad the behaviour you expected?\n"},{"id":"316468","messageId":"CACBZZX5jD0AhqZ8ucdicW=6s3=HPfpPeyne6jSVbZKnQ+sRZkQ@mail.gmail.com","threadId":"45645","inReplyTo":"3563ee7a-1175-2010-7176-0339cd3e60ee@update.uu.se","subject":"Re: Git documentation on branching.","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2017-04-10T10:21:10Z","receivedAt":"2017-04-10T10:21:38Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Mon, Apr 10, 2017 at 8:56 AM, Samuel Åslund <samuel@update.uu.se> wrote:\n> Hi all.\n>\n> I just started playing around with branching in git.\n> I have been using it more or less as Subversion until now.\n>\n> One feature with \"git branch xyz\" and \"git checkout xyz\" that is rather\n> obvious if you know them but bit me a little since I did not, is that\n> uncommitted work in progress is not affected or saved when switching between\n> branches. Thus I cleaned up the directory when working with the branch and\n> now I'm trying to find a stash where I hopefully have a copy of those files.\n>\n> Would it be possible to add something in the documentation to warn others\n> that uncommitted work is not saved or affected by branching?\n\nThe main UI in git for switching branches is \"git checkout\", and it's\nmentioned in the second paragraph of the documentation:\n\n\"[when switching branches] local modifications to the files in the\nworking tree are kept, so that they can be committed to the\n<branch>.\".\n\nDid you read this and find it unclear, and if so can you elaborate on\nwhat the confusion was, maybe we can fix the docs with that in mind?\n\nOr did you read some entirely different docs (what docs?) where we're\nperhaps not mentioning this as prominently?\n\n\n> The first two hits on my google search was very informative about branching\n> but I did not see that specific nugget of information (I might have been\n> careless reading, but if I did not see it others will probably also miss\n> it).\n>\n> Git - git-branch Documentation\n> https://git-scm.com/docs/git-branch\n>\n> Git - Branches in a Nutshell\n> https://git-scm.com/book/.../Git-Branching-Branches-in-a-Nutsh...\n>\n> This is my first try to contribute to the Git community, I hope it will be\n> useful to somebody.\n>\n> Regards,\n> //Samuel\n"},{"id":"316472","messageId":"3b793b18-7911-1859-e54d-8817f9c97a78@update.uu.se","threadId":"45645","inReplyTo":"CACBZZX5jD0AhqZ8ucdicW=6s3=HPfpPeyne6jSVbZKnQ+sRZkQ@mail.gmail.com","subject":"Re: Git documentation on branching.","fromName":"Samuel Åslund","fromEmail":"samuel@update.uu.se","sentAt":"2017-04-10T10:45:33Z","receivedAt":"2017-04-10T10:45:41Z","isPatch":false,"sender":{"key":"samuel@update.uu.se","avatar":null},"body":"On 17/4/10 12:21, Ævar Arnfjörð Bjarmason wrote:\n> On Mon, Apr 10, 2017 at 8:56 AM, Samuel Åslund <samuel@update.uu.se> wrote:\n>> Hi all.\n>>\n>> I just started playing around with branching in git.\n>> I have been using it more or less as Subversion until now.\n>>\n>> One feature with \"git branch xyz\" and \"git checkout xyz\" that is rather\n>> obvious if you know them but bit me a little since I did not, is that\n>> uncommitted work in progress is not affected or saved when switching between\n>> branches. Thus I cleaned up the directory when working with the branch and\n>> now I'm trying to find a stash where I hopefully have a copy of those files.\n>>\n>> Would it be possible to add something in the documentation to warn others\n>> that uncommitted work is not saved or affected by branching?\n>\n> The main UI in git for switching branches is \"git checkout\", and it's\n> mentioned in the second paragraph of the documentation:\n>\n> \"[when switching branches] local modifications to the files in the\n> working tree are kept, so that they can be committed to the\n> <branch>.\".\n>\n> Did you read this and find it unclear, and if so can you elaborate on\n> what the confusion was, maybe we can fix the docs with that in mind?\n>\n> Or did you read some entirely different docs (what docs?) where we're\n> perhaps not mentioning this as prominently?\n\nNo, I did not read the git checkout manpage.\nWhen I googled \"git branch\" I got the two pages mentioned below and this \none:\nGit - Basic Branching and Merging\nhttps://git-scm.com/.../Git-Branching-Basic-Branching-and-Mer...\n\nI find that mostly manpages require some context before they are useful \nso I go for the more wordy pages when trying to get my head around \nsomething new. Neither of the three top-hits on google included the \nlocal modifications comment where I noticed it. An actual search for \nthat string right now does not find anything either.\n\nThe comment you refer to in the git checkout man-page is probably enough \nheads-up for someone who knows git reasonably well, I do not know if it \nwould have made me realize exactly how the feature works.\nI'm not even sure I know how \"local modifications\" is defined in Git \nterminology, does it include \"(un)staged changes\", and or untracked files?\n\nThanks for the attention.\n\n>> The first two hits on my google search was very informative about branching\n>> but I did not see that specific nugget of information (I might have been\n>> careless reading, but if I did not see it others will probably also miss\n>> it).\n>>\n>> Git - git-branch Documentation\n>> https://git-scm.com/docs/git-branch\n>>\n>> Git - Branches in a Nutshell\n>> https://git-scm.com/book/.../Git-Branching-Branches-in-a-Nutsh...\n>>\n>> This is my first try to contribute to the Git community, I hope it will be\n>> useful to somebody.\n>>\n>> Regards,\n>> //Samuel\n\n"},{"id":"316474","messageId":"CACBZZX6bup33aBErxaAc6v=2zTEWGfXB8WtD4qt9boFOH=XWAA@mail.gmail.com","threadId":"45645","inReplyTo":"3b793b18-7911-1859-e54d-8817f9c97a78@update.uu.se","subject":"Re: Git documentation on branching.","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2017-04-10T10:59:26Z","receivedAt":"2017-04-10T10:59:52Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Mon, Apr 10, 2017 at 12:45 PM, Samuel Åslund <samuel@update.uu.se> wrote:\n> On 17/4/10 12:21, Ævar Arnfjörð Bjarmason wrote:\n>>\n>> On Mon, Apr 10, 2017 at 8:56 AM, Samuel Åslund <samuel@update.uu.se>\n>> wrote:\n>>>\n>>> Hi all.\n>>>\n>>> I just started playing around with branching in git.\n>>> I have been using it more or less as Subversion until now.\n>>>\n>>> One feature with \"git branch xyz\" and \"git checkout xyz\" that is rather\n>>> obvious if you know them but bit me a little since I did not, is that\n>>> uncommitted work in progress is not affected or saved when switching\n>>> between\n>>> branches. Thus I cleaned up the directory when working with the branch\n>>> and\n>>> now I'm trying to find a stash where I hopefully have a copy of those\n>>> files.\n>>>\n>>> Would it be possible to add something in the documentation to warn others\n>>> that uncommitted work is not saved or affected by branching?\n>>\n>>\n>> The main UI in git for switching branches is \"git checkout\", and it's\n>> mentioned in the second paragraph of the documentation:\n>>\n>> \"[when switching branches] local modifications to the files in the\n>> working tree are kept, so that they can be committed to the\n>> <branch>.\".\n>>\n>> Did you read this and find it unclear, and if so can you elaborate on\n>> what the confusion was, maybe we can fix the docs with that in mind?\n>>\n>> Or did you read some entirely different docs (what docs?) where we're\n>> perhaps not mentioning this as prominently?\n>\n>\n> No, I did not read the git checkout manpage.\n> When I googled \"git branch\" I got the two pages mentioned below and this\n> one:\n> Git - Basic Branching and Merging\n> https://git-scm.com/.../Git-Branching-Basic-Branching-and-Mer...\n\nThis list doesn't maintain that book, it looks like the right place to\nfile bugs & improvement suggestions in it is\nhttps://github.com/progit/progit2\n\nIt might be an issue with the git-scm site though that issues in the\nbook aren't funneled there instead of here. How did you go from\nnoticing an issue in the book to contacting this mailing list? Maybe\nwe need to update some page involved in that.\n\n> I find that mostly manpages require some context before they are useful so I\n> go for the more wordy pages when trying to get my head around something new.\n> Neither of the three top-hits on google included the local modifications\n> comment where I noticed it. An actual search for that string right now does\n> not find anything either.\n\nYeah but unfortunately we can do little about that stuff, we just\nmaintain the man pages.\n\n> The comment you refer to in the git checkout man-page is probably enough\n> heads-up for someone who knows git reasonably well, I do not know if it\n> would have made me realize exactly how the feature works.\n> I'm not even sure I know how \"local modifications\" is defined in Git\n> terminology, does it include \"(un)staged changes\", and or untracked files?\n\nMaybe we should say \"uncommitted modifications\" there. I think\nstarting to talk about staged & unstaged might just invite similar\nconfusion.\n\nIt's hard to say anything in these docs without being inaccurate or\nlosing the audience :(\n\n> Thanks for the attention.\n>\n>\n>>> The first two hits on my google search was very informative about\n>>> branching\n>>> but I did not see that specific nugget of information (I might have been\n>>> careless reading, but if I did not see it others will probably also miss\n>>> it).\n>>>\n>>> Git - git-branch Documentation\n>>> https://git-scm.com/docs/git-branch\n>>>\n>>> Git - Branches in a Nutshell\n>>> https://git-scm.com/book/.../Git-Branching-Branches-in-a-Nutsh...\n>>>\n>>> This is my first try to contribute to the Git community, I hope it will\n>>> be\n>>> useful to somebody.\n>>>\n>>> Regards,\n>>> //Samuel\n>\n>\n"},{"id":"316547","messageId":"20170410201313.e69bc8798d569d85a493dc19@domain007.com","threadId":"45645","inReplyTo":"a967439f-117e-1f09-6f40-7f62bc6cbae1@update.uu.se","subject":"Re: Git documentation on branching.","fromName":"Konstantin Khomoutov","fromEmail":"kostix+git@007spb.ru","sentAt":"2017-04-10T17:13:13Z","receivedAt":"2017-04-11T05:32:36Z","isPatch":false,"sender":{"key":"kostix+git@007spb.ru","avatar":null},"body":"On Mon, 10 Apr 2017 12:24:47 +0200\nSamuel Åslund <samuel@update.uu.se> wrote:\n\n[...]\n> >> One feature with \"git branch xyz\" and \"git checkout xyz\" that is\n> >> rather obvious if you know them but bit me a little since I did\n> >> not, is that uncommitted work in progress is not affected or saved\n> >> when switching between branches.\n> > [...]\n> > But neither is uncommitted work saved anywhere when you do\n> > `svn switch` in Subversion which is analogous to `git checkout`.\n> >\n> > While I do know quite many people expect Git to somehow \"preserve\"\n> > their work when switching branches without having them do anything,\n> > I wonder what in Subversion workflow makes you think Git should have\n> > had the behaviour you expected?\n> \n> svn switch is heavy, thus I usually checked out a new branch in\n> another directory. So probably not the Subversion workflow but rather\n> _my_ workflow in Subversion.\n\nYes.  The equivalent thing with Git would be using its `git worktree`\nsubcommand (which is a stock subcommand since some time, and previously\nwas available in the form of an external script).  The said command\nbasically creates another \"checkout\" -- a working tree and a separate\nindex -- linked to the original repository.  You can have any number of\nsuch separate work trees, and what's checked out in them is completely\nirrelevant to the repository itself (which only keeps commits and the\ndata they refer to).\n\nNote that since `git worktree` was (is?) sort of a clever hack not\noriginally envisioned as one of \"stock\" workflows, its insufficiently\ncovered by the documentation.  And while it indeed may be useful --\nsometimes it's ineed convenient to have two versions of the same\ncodebase to be checked out side-by-side, -- I'd warn you against\nrushing for using `git worktree` as it appears to support what you did\nwith Subversion: there is another approach to support your mindset\nwhich I'll explain in a moment.\n\n> Either way, your comment about peoples expectations was what I wanted\n> to address. Expectation management is the responsibility of the \n> documentation, right?\n\nIt's hard to tell -- as Ævar Arnfjörð pointed out: there are two kinds\nof documentation: manuals and books / introductory courses.  As was\nshown to you, the manual page on `git checkout` explains what it does.\nWhether that's clear right away to any newcomer, I cannot say.\nProbably not, but if we'd turn that manual page to a book it will lose\nits original meaning of being dry and to the point.\n\nI have that problem with manual pages all the time: quite often they\nare most useful on some Nth re-reading, where you approach them with\ncertain working knowledge under your belt -- and suddenly certain\nthings you read there \"click\" in your head; you did read them before\nbut your mind just skimmed over them while having the impression of\ngrasping the material.\n\n> I find it quite reasonable to choose whether to stash the work in \n> progress myself before checking out another branch, but since I did\n> not expect to need to do that I didn't.\n> \n> I think that what made me expect Git to handle my uncommitted work is \n> how the documentation talks about making it easy to switch between \n> working on different features, most of the time I do not feel \n> comfortable checking in when a feature is in a broken state and \n> interruptions for quick fixes usually comes in those situations.\n\nThat's more complicated that it sounds.\nConsider the following things (in no particular order).\n\nSometimes \"carrying your uncommitted work over\" to another state of the\ncodebase is precisely what you'd want to happen, and that's what\n`git checkout` does for your.  It even has a specual \"I DO REALLY WANT\nIT TO HAPPEN\" switch, \"-m\", which makes that command to try to merge\nyour local modifications into what is about to be checked out if\notherwise your changes would be in conflict with that state.\n\nWhat's with untracked files?  Sometimes they should be considered part\nof the work to be saved away before checking out another state, and\nsometimes not (`git stash` has a special switch, \"-u\" to make it stash\nuntracked stuff as well).  What would be the default mode?  Think of\nit, and supposedly you'll come to a conclusion that either mode Git\ncould implement would alienate some group of folks. ;-)\n\nNow let's consider the most interesting bit.\n\nPeople switching from a non-distributed VC system are inherently and\nsubconsciously afraid of committing anything which \"is not ready\".\nThis is definitely a correct mindset with Subversion (which, IIUC,\nstill does not implement shelving it considered for a long time)\nbut not with Git.\n\nHere, it's absolutely OK to lump together all the stuff you're\ncurrently working it by `git add`-ing them, `git commit` it all --\nusually putting an informal \"WIP\" prefix in the front of the commit\nmessage to indicate it's work in progress -- and then switch away to\nanother branch.\n\nWhen back, you just to `git reset HEAD~1` to move your checked out\nbranch one commit back and still having all your changes where you had\nthem -- in your work tree.  You could have saved a series of N WIP\ncommits if you wanted it this way for some reason, and then you'd do\n`git reset HEAD~N` to achieve the same effect.  When you record a new\ncommit afterwards it will be recorded on to of what you've just reset\nyour branch to -- as if those WIP commits never existed.\n\nThis way your \"not ready yet\" changes maintained on particular branches\nare kept right there -- at the tips of those branches.\nSince Git is fine with using any commit for anything -- forking a\nbranch off it or pushing it, -- it's okay if, say, your boss orders you\nto push what you've done on the \"develop\" branch while you have some\nWIP commits at its tip: you just push not its tip but the last \"ready\"\ncommit on that branch.\n\nTL;DR\nConsider more possibilities ;-)\n"}]}