{"thread":{"id":"13156","subject":"git branch diagram","startedAt":"2008-04-17T17:00:56Z","lastAt":"2008-04-21T13:07:15Z","messageCount":10,"participants":["patrick.higgins@cexp.com","Sitaram Chamarty","Roman V. Shaposhnik","Karl Hasselström","Fedor Sergeev","Matt Graham","Jakub Narebski","Luciano Rocha"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"74653","messageId":"911589C97062424796D53B625CEC0025E460C3@USCOBRMFA-SE-70.northamerica.cexp.com","threadId":"13156","inReplyTo":null,"subject":"git branch diagram","fromName":"","fromEmail":"patrick.higgins@cexp.com","sentAt":"2008-04-17T17:00:56Z","receivedAt":"2008-04-17T17:00:56Z","isPatch":false,"sender":{"key":"patrick.higgins@cexp.com","avatar":null},"body":"I am trying to get my employer to start using git and have found the distributed model and git's branching to be one of the hardest parts to explain and understand. I put together the attached diagram (done with graphviz so some things are not in the most logical place) to help explain things to my coworkers.\n\nUnfortunately, I don't understand things well enough myself to know if the diagram is correct or not. I read in the stgit docs that developing directly in the master branch is discouraged by convention, but I don't really understand why. The git tutorial shows work happening directly in master, so I wasn't sure if that's a convention that only makes sense for stgit or for plain git, too.\n\nIn my diagram, I am assuming that most developers work in master, and make branches for their own long-lived projects and experimental things.\n\nDoes my diagram make sense? Are there any suggestions or corrections?\n\nThanks,\nPatrick\n"},{"id":"74706","messageId":"2e24e5b90804171838w6809cb17sded64367d5ebc222@mail.gmail.com","threadId":"13156","inReplyTo":"911589C97062424796D53B625CEC0025E460C3@USCOBRMFA-SE-70.northamerica.cexp.com","subject":"Re: git branch diagram","fromName":"Sitaram Chamarty","fromEmail":"sitaramc@gmail.com","sentAt":"2008-04-18T01:38:46Z","receivedAt":"2008-04-18T01:38:46Z","isPatch":false,"sender":{"key":"sitaramc@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43316?v=4"},"body":"[Patrick: apologies if you get this twice; the first time I did\n\"reply\" instead of \"reply all\" and it only went to you, not the list.]\n\nOn Thu, Apr 17, 2008 at 10:30 PM, wrote:\n> Does my diagram make sense? Are there any suggestions or corrections?\n\nLooks ok to me, but I'm still learning git myself... so beware of what I say :-)\n\nSome quick comments:\n\nThe Project repo (the big one in the middle) need not, I think,\nmaintain long-lived tracking branches for every developer. Rather,\nthat repo would pull based on outside-git inputs (analogous to emails\nsaying \"please pull from ...\") and there might be a temp tree created\nto test stuff out but once the merge or cherry-pick into the local\nmaster is done that temp tree would disappear\n\nHowever, if you don't have too many devs then your method is fine too.\n\nThe problem with devs working on the same branch that the project repo\npulls is that the commits may have some cruft, even though you said\nthey'd make branches for experimental things. The way I'm working\nnow, my \"master\" is clean as a whistle and anyone pulling from it and\nmerging gets exactly what is needed.\n\nAgain, this is not a rule, but personal preference and if your style\nof working is very clean then this may not be needed.\n\nRegards,\n\nSitaram\n"},{"id":"74709","messageId":"1208485747.26863.246.camel@goose.sun.com","threadId":"13156","inReplyTo":"911589C97062424796D53B625CEC0025E460C3@USCOBRMFA-SE-70.northamerica.cexp.com","subject":"Re: git branch diagram","fromName":"Roman V. Shaposhnik","fromEmail":"rvs@sun.com","sentAt":"2008-04-18T02:29:07Z","receivedAt":"2008-04-18T02:29:07Z","isPatch":false,"sender":{"key":"rvs@sun.com","avatar":null},"body":"On Thu, 2008-04-17 at 11:00 -0600, Patrick.Higgins@cexp.com wrote:\n> I am trying to get my employer to start using git and have found the distributed model and git's \n> branching to be one of the hardest parts to explain and understand. I put together the attached \n> diagram (done with graphviz so some things are not in the most logical place)\n\nJust as a usability comment: I believe that you should color-code or \nenumerate your arrows based on what part of the workflow they belong to.\n\n> Unfortunately, I don't understand things well enough myself to know if the diagram is correct\n> or not. I read in the stgit docs that developing directly in the master branch is discouraged \n> by convention, but I don't really understand why. The git tutorial shows work happening directly\n> in master, so I wasn't sure if that's a convention that only makes sense for stgit or for plain\n> git, too.\n> \n> In my diagram, I am assuming that most developers work in master, and make branches for their own \n> long-lived projects and experimental things.\n\nSpeaking of diagram: when you say that inter-repo arrows are pulls, \ndoes it mean that you are not allowing developers to push their changes\nback to the origin? If you're really trying to build your workflow \naround the pull-only, who does the pulling? IOW, who controls the\n\"Project Repo\" (the big box in the middle)?\n\n> Does my diagram make sense? Are there any suggestions or corrections?\n\nHere are my comments (beware: they do not come from a Git guru, although\nI'm trying to make my employer take Git seriously as well):\n * It looks like \"Integration Repo\" is really a Superproject that\n consists of submodules. Was that the intention?\n * do you really need dev[123]/master branches in the \"Project Repo\"?\n * I don't really understand what the smaller boxes labels \"Local\n branches\" are supposed to represent.\n\nThanks,\nRoman.\n"},{"id":"74710","messageId":"20080418064655.GA23209@diana.vm.bytemark.co.uk","threadId":"13156","inReplyTo":"911589C97062424796D53B625CEC0025E460C3@USCOBRMFA-SE-70.northamerica.cexp.com","subject":"Re: git branch diagram","fromName":"Karl Hasselström","fromEmail":"kha@treskal.com","sentAt":"2008-04-18T06:46:55Z","receivedAt":"2008-04-18T06:46:55Z","isPatch":false,"sender":{"key":"kha@treskal.com","avatar":"https://gravatar.com/avatar/f0120c734b5279b345075a28521e1ac66acb20c9913ffe9bf6ae97e53f7f3f13?d=mp&s=160"},"body":"On 2008-04-17 11:00:56 -0600, Patrick.Higgins@cexp.com wrote:\n\n> I read in the stgit docs that developing directly in the master\n> branch is discouraged by convention, but I don't really understand\n> why. The git tutorial shows work happening directly in master, so I\n> wasn't sure if that's a convention that only makes sense for stgit\n> or for plain git, too.\n\nIt doesn't even make sense for StGit. The documentation on the StGit\nhomepage that claims this (\"As a convention, you should avoid working\nin the 'master' branch of a remote project and use it only as a\nreference, since it reflects someone else's work.\") is simply\nhorribly, horribly outdated.\n\n-- \nKarl Hasselström, kha@treskal.com\n www.treskal.com/kalle\n"},{"id":"74713","messageId":"alpine.WNT.1.10.0804181219420.1528@theodor","threadId":"13156","inReplyTo":"911589C97062424796D53B625CEC0025E460C3@USCOBRMFA-SE-70.northamerica.cexp.com","subject":"Re: git branch diagram","fromName":"Fedor Sergeev","fromEmail":"fedor.sergeev@sun.com","sentAt":"2008-04-18T08:39:52Z","receivedAt":"2008-04-18T08:39:52Z","isPatch":false,"sender":{"key":"fedor.sergeev@sun.com","avatar":null},"body":"On Thu, 17 Apr 2008, Patrick.Higgins@cexp.com wrote:\n> I am trying to get my employer to start using git and have found the distributed model\n> and git's branching to be one of the hardest parts to explain and understand.\n> I put together the attached diagram (done with graphviz so some things\n> are not in the most logical place) to help explain things to my coworkers.\n\nOne bit of advice - make at least two or three versions of this diagram,\nwith varying levels of complexity (say, complex one for integrators and \nsimple one for developers).\nFull diagram might appear to be very intimidating to newcomers :)\n\nDepending on their background your coworkers might not like the whole idea\nof branching (because of prior bad experience with branches and merges).\nIn my case the very word \"branch\" was not always accepted nicely.\n\nMy own experience in a similar situation (which has not yet been fully resolved,\nso take my words with a grain of salt) shows that for the initial acceptance\nit is better to devise a scheme that does not involve branching.\n\nPeople will learn branching and will appreciate git's flexible branching \nin future, but for starters it might appear to be better to restrict amount of branches\nto master + origin/master.\n\n>\n> Unfortunately, I don't understand things well enough myself to know if the diagram is correct or not.\n> I read in the stgit docs that developing directly in the master branch\n> is discouraged by convention, but I don't really understand why.\n> The git tutorial shows work happening directly in master, so I wasn't\n> sure if that's a convention that only makes sense for stgit or for plain git, too.\n\nThat is really up to your policies and your trust to the developers.\nIt is harder to screw up a master in Git than it is, say, in TeamWare.\n\nBut I would not let everybody in my project to freely go and do stuff in \nmaster. And I definitely would not make it a development requirement, as \nTeamWare background makes my coworkers shudder and sweat of a very thought\nof touching master.\n\nYour milage might definitely vary.\n\nregards,\n Fedor.\n"},{"id":"74732","messageId":"1c5969370804180607q675eb528na431ecdce99c49fd@mail.gmail.com","threadId":"13156","inReplyTo":"911589C97062424796D53B625CEC0025E460C3@USCOBRMFA-SE-70.northamerica.cexp.com","subject":"Re: git branch diagram","fromName":"Matt Graham","fromEmail":"mdg149@gmail.com","sentAt":"2008-04-18T13:07:55Z","receivedAt":"2008-04-18T13:07:55Z","isPatch":false,"sender":{"key":"mdg149@gmail.com","avatar":"https://gravatar.com/avatar/a1f130a60a6550f75e8d7d3849e58e46494f36bfaf764a38cfd695ac85de8576?d=mp&s=160"},"body":"Full disclosure: I'm a git newbie.\n\n\nOn Thu, Apr 17, 2008 at 1:00 PM, wrote:\n> I am trying to get my employer to start using git and have found the distributed model and git's branching to be one of the hardest parts to explain and understand. I put together the attached diagram (done with graphviz so some things are not in the most logical place) to help explain things to my coworkers.\n>\n\nA worthy goal. It seems like a good corporate work flow for git is\neither yet to be devised or yet to be documented.\n\n\n> In my diagram, I am assuming that most developers work in master, and make branches for their own long-lived projects and experimental things.\n>\n> Does my diagram make sense? Are there any suggestions or corrections?\n\nIt feels more complicated than it needs to be. My reaction is that\nthere should be a simpler way to represent it.\n\nIn the dev repos, do the remote branches and local branches have to be\nin separate boxes? It seems these could be put into a single box.\n\nIt's not clear who's doing the pulls into the project repository or\nwho is doing the integration. My expectation would be that pushes\nwould be involved at some point, is it not necessary?\n\nmatt\n"},{"id":"74853","messageId":"m3fxtgqcbr.fsf@localhost.localdomain","threadId":"13156","inReplyTo":"911589C97062424796D53B625CEC0025E460C3@USCOBRMFA-SE-70.northamerica.cexp.com","subject":"Re: git branch diagram","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-04-21T00:30:21Z","receivedAt":"2008-04-21T00:30:21Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":" writes:\n\n> I am trying to get my employer to start using git and have found the\n> distributed model and git's branching to be one of the hardest parts\n> to explain and understand. \n\nTake a look at description of version control and distributed version\ncontrol at BetterExplained, and slides from presentations / seminars\nwhich you can find in GitLinks page at git wiki.\n\n> I put together the attached diagram (done with graphviz so some\n> things are not in the most logical place) to help explain things to\n> my coworkers.\n> \n> Unfortunately, I don't understand things well enough myself to know\n> if the diagram is correct or not. I read in the stgit docs that\n> developing directly in the master branch is discouraged by\n> convention, but I don't really understand why. The git tutorial\n> shows work happening directly in master, so I wasn't sure if that's\n> a convention that only makes sense for stgit or for plain git, too.\n> \n> Does my diagram make sense? Are there any suggestions or corrections?\n\nIt is much too complicated. IMHO it would be better to explain the\nidea of remote branches first (separate diagram), then simplify\ndiagram by showing only relationships between repositories:\nrelationship between branches is impled.\n\nPerhaps adding what branches are supposed to be found at given\nrepository...\n\nBTW. do all transfer is pull (or fetch) only, or are there pushes and\nexchanging patches via email?\n\n> In my diagram, I am assuming that most developers work in master,\n> and make branches for their own long-lived projects and experimental\n> things.\n\nFor example git itself, as a project, uses three long-lived branches:\n'maint', 'master' and 'next', uses 'pu' (proposed updates) branch as\npropagation / review mechanism for short-lived tipic branches.\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"74868","messageId":"1c5969370804210548q4b6aa30h8a8c0323b3fc51d4@mail.gmail.com","threadId":"13156","inReplyTo":"m3fxtgqcbr.fsf@localhost.localdomain","subject":"Re: git branch diagram","fromName":"Matt Graham","fromEmail":"mdg149@gmail.com","sentAt":"2008-04-21T12:48:46Z","receivedAt":"2008-04-21T12:48:46Z","isPatch":false,"sender":{"key":"mdg149@gmail.com","avatar":"https://gravatar.com/avatar/a1f130a60a6550f75e8d7d3849e58e46494f36bfaf764a38cfd695ac85de8576?d=mp&s=160"},"body":"On Sun, Apr 20, 2008 at 8:30 PM, Jakub Narebski wrote:\n> writes:\n>\n> > In my diagram, I am assuming that most developers work in master,\n> > and make branches for their own long-lived projects and experimental\n> > things.\n>\n> For example git itself, as a project, uses three long-lived branches:\n> 'maint', 'master' and 'next', uses 'pu' (proposed updates) branch as\n> propagation / review mechanism for short-lived tipic branches.\n\nJakub, could you explain the difference between maint and master? And\nthe difference between master and next? Maint and next are clear, but\nhow does master relate to those 2?\n"},{"id":"74869","messageId":"200804211506.53251.jnareb@gmail.com","threadId":"13156","inReplyTo":"1c5969370804210548q4b6aa30h8a8c0323b3fc51d4@mail.gmail.com","subject":"Re: git branch diagram","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-04-21T13:06:52Z","receivedAt":"2008-04-21T13:06:52Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Monday, 21 April 2008, Matt Graham wrote:\n> On Sun, Apr 20, 2008 at 8:30 PM, Jakub Narebski wrote:\n>> writes:\n>>\n>>> In my diagram, I am assuming that most developers work in master,\n>>> and make branches for their own long-lived projects and experimental\n>>> things.\n>>\n>> For example git itself, as a project, uses three long-lived branches:\n>> 'maint', 'master' and 'next', uses 'pu' (proposed updates) branch as\n>> propagation / review mechanism for short-lived tipic branches.\n> \n> Jakub, could you explain the difference between maint and master? And\n> the difference between master and next? Maint and next are clear, but\n> how does master relate to those 2?\n\nThe posts titled \"A note from the maintainer\", posted around major git\nrelease, should explain it. You can find them also at:\n http://git.or.cz/gitwiki/MaintNotes\n http://repo.or.cz/w/git.git?a=blob_plain;f=MaintNotes;hb=todo\n\nIn short, the minor releases like 1.5.3.8 are cut out of 'maint' branch,\nthe major releases like latest 1.5.5 are cut out of 'master' branch, and\n'next' is where major part of development happens.\n\n-- \nJakub Narebski\nPoland\n"},{"id":"74870","messageId":"20080421130715.GB14598@bit.office.eurotux.com","threadId":"13156","inReplyTo":"1c5969370804210548q4b6aa30h8a8c0323b3fc51d4@mail.gmail.com","subject":"Re: git branch diagram","fromName":"Luciano Rocha","fromEmail":"luciano@eurotux.com","sentAt":"2008-04-21T13:07:15Z","receivedAt":"2008-04-21T13:07:15Z","isPatch":false,"sender":{"key":"luciano@eurotux.com","avatar":null},"body":"On Mon, Apr 21, 2008 at 08:48:46AM -0400, Matt Graham wrote:\n> On Sun, Apr 20, 2008 at 8:30 PM, Jakub Narebski wrote:\n> > writes:\n> >\n> > > In my diagram, I am assuming that most developers work in master,\n> > > and make branches for their own long-lived projects and experimental\n> > > things.\n> >\n> > For example git itself, as a project, uses three long-lived branches:\n> > 'maint', 'master' and 'next', uses 'pu' (proposed updates) branch as\n> > propagation / review mechanism for short-lived tipic branches.\n> \n> Jakub, could you explain the difference between maint and master? And\n> the difference between master and next? Maint and next are clear, but\n> how does master relate to those 2?\n\n\nThere are four branches in git.git repository that track the\nsource tree of git: \"master\", \"maint\", \"next\", and \"pu\". I may\nadd more maintenance branches (e.g. \"maint-1.5.4\") if we have\nhugely backward incompatible feature updates in the future to keep\nan older release alive; I may not, but the distributed nature of\ngit means any volunteer can run a stable-tree like that herself.\n\nThe \"master\" branch is meant to contain what are very well\ntested and ready to be used in a production setting. There\ncould occasionally be minor breakages or brown paper bag bugs\nbut they are not expected to be anything major, and more\nimportantly quickly and trivially fixable. Every now and\nthen, a \"feature release\" is cut from the tip of this branch and\nthey typically are named with three dotted decimal digits. The\nlast such release was 1.5.5 done on Apr 7th this year. You\ncan expect that the tip of the \"master\" branch is always more\nstable than any of the released versions.\n\nWhenever a feature release is made, \"maint\" branch is forked off\nfrom \"master\" at that point. Obvious, safe and urgent fixes\nafter a feature release are applied to this branch and\nmaintenance releases are cut from it. The maintenance releases\nare named with four dotted decimal, named after the feature\nrelease they are updates to; the last such release was 1.5.4.5.\nNew features never go to this branch. This branch is also\nmerged into \"master\" to propagate the fixes forward.\n\nA trivial and safe enhancement goes directly on top of \"master\".\nA new development, either initiated by myself or more often by\nsomebody who found his or her own itch to scratch, does not\nusually happen on \"master\", however. Instead, a separate topic\nbranch is forked from the tip of \"master\", and it first is\ntested in isolation; I may make minimum fixups at this point.\nUsually there are a handful such topic branches that are running\nahead of \"master\" in git.git repository. I do not publish the\ntip of these branches in my public repository, however, partly\nto keep the number of branches that downstream developers need\nto worry about low, and primarily because I am lazy.\n\nThe quality of topic branches are judged primarily by the mailing list\ndiscussions. Some of them start out as \"good idea but obviously is\nbroken in some areas (e.g. breaks the existing testsuite)\" and then\nwith some more work (either by the original contributor's effort or\nhelp from other people on the list) becomes \"more or less done and can\nnow be tested by wider audience\". Luckily, most of them start out in\nthe latter, better shape.\n\nThe \"next\" branch is to merge and test topic branches in the\nlatter category. In general, the branch always contains the tip\nof \"master\". It might not be quite rock-solid production ready,\nbut is expected to work more or less without major breakage. I\nusually use \"next\" version of git for my own work, so it cannot\nbe _that_ broken to prevent me from pushing the changes out.\nThe \"next\" branch is where new and exciting things take place.\n\nThe two branches \"master\" and \"maint\" are never rewound, and\n\"next\" usually will not be either (this automatically means the\ntopics that have been merged into \"next\" are usually not\nrebased, and you can find the tip of topic branches you are\ninterested in from the output of \"git log next\"). You should be\nable to safely track them.\n\nAfter a feature release is made from \"master\", however, \"next\"\nwill be rebuilt from the tip of \"master\" using the surviving\ntopics. The commit that replaces the tip of the \"next\" will\nhave the identical tree, but it will have different ancestry\nfrom the tip of \"master\". An announcement will be made to warn\npeople about such a rebasing.\n\nThe \"pu\" (proposed updates) branch bundles all the remainder of\ntopic branches. The \"pu\" branch, and topic branches that are\nonly in \"pu\", are subject to rebasing in general. By the above\ndefinition of how \"next\" works, you can tell that this branch\nwill contain quite experimental and obviously broken stuff.\n\nWhen a topic that was in \"pu\" proves to be in testable shape, it\ngraduates to \"next\". I do this with:\n\n git checkout next\n git merge that-topic-branch\n\nSometimes, an idea that looked promising turns out to be not so\ngood and the topic can be dropped from \"pu\" in such a case.\n\nA topic that is in \"next\" is expected to be tweaked and fixed to\nperfection before it is merged to \"master\" (that's why \"master\"\ncan be expected to stay very stable). Similarly to the above, I\ndo it with this:\n\n git checkout master\n git merge that-topic-branch\n git branch -d that-topic-branch\n\nNote that being in \"next\" is not a guarantee to appear in the\nnext release (being in \"master\" is such a guarantee, unless it\nis later found seriously broken and reverted), or even in any\nfuture release. There even were cases that topics needed\nreverting a few commits in them before graduating to \"master\",\nor a topic that already was in \"next\" were entirely reverted\nfrom \"next\" because fatal flaws were found in them later.\n\nStarting from v1.5.0, \"master\" and \"maint\" have release notes\nfor the next release in Documentation/RelNotes-* files, so that\nI do not have to run around summarizing what happened just\nbefore the release.\n\n\n-- \nLuciano Rocha \nEurotux Informática, S.A. \n"}]}