{"thread":{"id":"43312","subject":"Re: [DRAFT] Branching and merging with git","startedAt":"2006-11-17T18:21:57Z","lastAt":"2006-11-26T04:01:42Z","messageCount":10,"participants":["linux@horizon.com","Junio C Hamano","Petr Baudis","J. Bruce Fields","Jakub Narebski","Robin Rosenberg"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"294978","messageId":"20061117182157.GC11882@fieldses.org","threadId":"43312","inReplyTo":"20061117153246.GA20065@thunk.org","subject":"Re: [DRAFT] Branching and merging with git","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2006-11-17T18:21:57Z","receivedAt":"2006-11-17T18:21:57Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Fri, Nov 17, 2006 at 10:32:46AM -0500, Theodore Tso wrote:\n> Personally, I think this information is actually more important to an\n> end-user than the current \"part two\" of the tutorial, which discusses\n> the object database and the index file.  Perhaps this should be \"part\n> 2\", and the object database and index file should become \"part 3\"?  \n\nYeah, the really difficult problem here is figuring out how to organize\nthe documentation.  There are a few needs:\n\n\t1. Quick-start/task-based documentation\n\t\t- We want to \"sell\" git to the beginning user by getting\n\t\t  them up and running as quickly as possible.\n\t\t- We need to help people with some limited needs--\n\t\t  testers who just need to download the latest linux git\n\t\t  tree, or bisect, or whatever.\n\t\t- It's also a fun way to demonstrate the richness of\n\t\t  some git features (e.g. history explanation).\n\t2. Conceptual background\n\t\t- People need to understand the commit graph, branches,\n\t\t  merging, the index file (gack), pack files, etc.--some of\n\t\t  that can be put off a little while, some of it can't.\n\t3. Reference documentation\n\nThe man pages do most of #3, but maybe they could be better organized--I\nthink people aren't finding stuff there that they should be.\n\nNumbers 1 and 2 are scattered around git(7), the two-part tutorial, the\ngit-core tutorial, etc.\n\n> It might also be a good to consider moving some of the \"discussion\"\n> portion the top-level git(7) man page into the object database and\n> index file discussion.  Right now, the best way to introduce git's\n> concepts (IMHO), is to start with the part 1 of the tutorial, then go\n> into the your draft branch/merging with git, then the current part 2\n> of the tutorial, and then direct folks to read the \"discussion\"\n> section of git(7).  Only then do they really have enough background\n> understanding of the fundamental concepts of git that they won't get\n> confused when they start talking to other git users, on the git\n> mailing list, for example.\n> \n> It would be nice if there was an easy way to direct users through the\n> documentation in a way which makes good pedagogical sense.  Right now,\n> one of the reasons why life gets hard for new users is that the\n> current tutorials aren't enough for them to really undersatnd what's\n> going on at a conceptual level.  And if users start using \"everyday\n> git\" as a crutch, without the right background concepts, the human\n> brain naturally tries to intuit what's happening in the background,\n> but without reading the background docs, git is different enough that\n> they will probably get it wrong, which means more stuff that they have\n> to unlearn later.  \n\nI agree.  Unfortunately, people who need to use git but aren't\nstudy-the-manual-first types *are* going to just dive in whether we want\nthem to or not, so we have to make it easy for them to pick up what they\nneed as they go.\n\nHow about this as a strawman \"git user's manual\" outline:\n\n\tI. Quick-start: drawn from the tutorial part I and everyday.txt?\n\n\tII. Basic git concepts, drawn from \"discussion\" in git(7) (the\n\tREADME), tutorial part II, this branching-and-merging tutorial, etc.:\n\n\t\t1. The commit graph and the object database\n\t\t2. References\n\t\t3. Fetching and pulling, remotes\n\t\t4. The index file\n\n\tIII. Using git: \n\n\t\t1. History exploration\n\t\t2. merge resolution\n\t\t3. pack files, fsck, repository maintenance\n\t\t4. pushing, setting up a public repo\n\n\tIV. Advanced examples: drawn from the howto directories,\n\t    cvs-migration.txt,...\n\n\t\t1. More complicated commandline magic, scripting\n\t\t   (history exploration with git-rev-list, etc.)\n\t\t2. History re-writing: cherry-picking, rebasing,...\n\t\t3. Setting up a shared public repo?\n\t\t4. Migration to/from other SCM's.\n\n\tIV. Technical details: core-tutorial.txt, plumbing, code tours, etc.\n\nChapter II is the prerequisite for everything else, so a lot of thought\nhas to be given to treating exactly what's necessary there and no more.\nMaybe more of it could be mixed into chapter I.\n\nIt has to be readable in order by the 10% of people who actually like to\nread manuals, and easy to pick up in the middle for the 90% who will\njust dive into the section they were told they need to read to\nunderstand some particular problem.\n\nIn particular, ideally only I and II would really be sequential, and\nthe rest would be readable in any order.\n\n"},{"id":"294318","messageId":"20061118001355.23488.qmail@science.horizon.com","threadId":"43312","inReplyTo":"20061117182157.GC11882@fieldses.org","subject":"Re: [DRAFT] Branching and merging with git","fromName":"","fromEmail":"linux@horizon.com","sentAt":"2006-11-18T00:13:55Z","receivedAt":"2006-11-18T00:13:55Z","isPatch":false,"sender":{"key":"linux@horizon.com","avatar":null},"body":"I'm working on incorporating all of the comments I've received, so\nthank you all!\n\n(BTW, the reason I didn't document git-describe is that I didn't\nknow about it!  You fixed the latter, so I'll fix the former.)\n\n\nI'm glad if others like it, but I was really scratching my own\nitch.  I'm still wrapping my head around how to work with git, and\nwriting this was my own learning experience.\n\nEven writing it out in full rather than as rougher notes wasn't\nan entirely unselfish act; it ensures:\n1) I don't leave some important assumption unstated; that's the\n   type most likely to be wrong, and\n2) If I can get it good enough to post publicly, I'll get all the\n   experts to fact-check it for me.\n\n\nAs for the target audience, it's basically someone who's read git(1)\nand knows what a VCS is supposed to do, but has a CVS/SVN mindset.\nThe emphasis is on branching and merging because that's the big\n\"mental mode\" difference in the way that git works.\n\n\nFor anyone else documenting git, I recommend describing \"what if I\nmake a mistake\" early.  It was a bit of a revelation to realize\nthat there's not much point to \"git pull --no-commit\" because\nit's so easy to undo.\n\n\nJust a couple of questions:\n\nWe seem to have developed a consensus on the desirability of allowing\nHEAD to point outside refs/heads, postponing the check until\ncommit/merge time.  (At least, junkio and Linus seemed to like it.)\n\nI proposed it, so I get to write it, but you notice I have a whole\nsection on how to work around the lack of that feature, so if someone\nfeels like picking up the baton while I'm still writing docs, it would\nsimplify things.\n\n\nI'd like to learn more about the zillion options to git-log.\nIf people feel like sharing useful incantations, it would be\nbe very helpful to give a concrete example of its usefulness,\npreferably within the git history itself.\n\n(Are there any octopus merges in git's history?  If not, could I ask\n"},{"id":"296898","messageId":"ejlk82$av5$1@sea.gmane.org","threadId":"43312","inReplyTo":"20061118001355.23488.qmail@science.horizon.com","subject":"Re: [DRAFT] Branching and merging with git","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2006-11-18T00:32:25Z","receivedAt":"2006-11-18T00:32:25Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"linux@horizon.com wrote:\n\n[...]\n> (Are there any octopus merges in git's history?  If not, could I ask\n> for one for pedagogical value?)\n\nSee commit d425142e2a045a9dd7879d028ec68bd748df48a3 (most legged octopus\nI found in git.git repository). Doing git-rev-parse --parents -all, or \ngit log --all and greppoing for merges is a good idea to find octopi.\n\nThe commit is both v1.1.2-gd425142 (git describe) and tags/v1.2.0^0~143 \n(git name-rev --tags)\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n\n"},{"id":"294552","messageId":"7virhdh9j8.fsf@assigned-by-dhcp.cox.net","threadId":"43312","inReplyTo":"20061118001355.23488.qmail@science.horizon.com","subject":"Re: [DRAFT] Branching and merging with git","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-11-18T00:40:27Z","receivedAt":"2006-11-18T00:40:27Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"linux@horizon.com writes:\n\n> We seem to have developed a consensus on the desirability of allowing\n> HEAD to point outside refs/heads, postponing the check until\n> commit/merge time.  (At least, junkio and Linus seemed to like it.)\n\nYes, and I am actually interested in at least doing the initial\ndamage assessment myself but people are welcome to beat me to\nit.  The easies part would be to just try writing a bare SHA-1\nto .git/HEAD with:\n\n\tH=$(git-rev-parse --verify HEAD)\n        echo $H >.git/HEAD\n\nand see what breaks and start picking up the pieces from there.\n\n> I'd like to learn more about the zillion options to git-log.\n> If people feel like sharing useful incantations, it would be\n> be very helpful to give a concrete example of its usefulness,\n> preferably within the git history itself.\n>\n> (Are there any octopus merges in git's history?  If not, could I ask\n> for one for pedagogical value?)\n\ngit.git itself is full of them, but the very first octopus (it\nactually is a pentapus) is rather nice to watch in gitk:\n\n\t211232bae64bcc60bbf5d1b5e5b2344c22ed767e\n\nYou can look for them with:\n\n\tgit rev-list --parents HEAD | grep '..* ..* ..* ..* ..* ..*'\n\nRepeat as many \" ..*\" as the number of parents you would want to require.\nI knew the very first one was pentapus (I did it) so I wrote six ..*\nthere (one for the commit, one each for parents).\n\nLen's dodecapus in linux-2.6.git is this one:\n\n\t9fdb62af92c741addbea15545f214a6e89460865\n\nIt is very interesting to watch it with \"git show\".  Len has\nanother one in August:\n\n\tda547d775fa9ba8d9dcaee7bc4e960540e2be576\n\n"},{"id":"298043","messageId":"20061119175040.GB15608@fieldses.org","threadId":"43312","inReplyTo":"20061117182157.GC11882@fieldses.org","subject":"Re: [DRAFT] Branching and merging with git","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2006-11-19T17:50:40Z","receivedAt":"2006-11-19T17:50:40Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Fri, Nov 17, 2006 at 01:21:57PM -0500, bfields wrote:\n> On Fri, Nov 17, 2006 at 10:32:46AM -0500, Theodore Tso wrote:\n> > It would be nice if there was an easy way to direct users through the\n> > documentation in a way which makes good pedagogical sense.\n....\n> How about this as a strawman \"git user's manual\" outline:\n\nIn fact, I'm tempted to submit a patch that just assigns a chapter\nnumber to everything under Documentation/, slaps a single table of\ncontents on the front, and calls the result \"the git user's manual.\"\n\nOf course, the moment people started trying to read the thing they'd\ncomplain that it was a mess--some stuff referenced without being\nintroduced, other stuff introduced too many times.  But then over time\nmaybe that'd force us to mold it into some sort of logical sequence.\n\n"},{"id":"294790","messageId":"20061119175952.GX7201@pasky.or.cz","threadId":"43312","inReplyTo":"20061119175040.GB15608@fieldses.org","subject":"Git manuals","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2006-11-19T17:59:52Z","receivedAt":"2006-11-19T17:59:52Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"On Sun, Nov 19, 2006 at 06:50:40PM CET, J. Bruce Fields wrote:\n> On Fri, Nov 17, 2006 at 01:21:57PM -0500, bfields wrote:\n> > On Fri, Nov 17, 2006 at 10:32:46AM -0500, Theodore Tso wrote:\n> > > It would be nice if there was an easy way to direct users through the\n> > > documentation in a way which makes good pedagogical sense.\n> ....\n> > How about this as a strawman \"git user's manual\" outline:\n\n(I was briefly discussing Git Book with Junio at OLS, I think the result\nwas \"yeah, would be nice, perhaps we can start poking it soon\". I\nstarted to think about it once again in the last few weeks.)\n\n> In fact, I'm tempted to submit a patch that just assigns a chapter\n> number to everything under Documentation/, slaps a single table of\n> contents on the front, and calls the result \"the git user's manual.\"\n> \n> Of course, the moment people started trying to read the thing they'd\n> complain that it was a mess--some stuff referenced without being\n> introduced, other stuff introduced too many times.  But then over time\n> maybe that'd force us to mold it into some sort of logical sequence.\n\nSequencing isn't the only problem. A _manual_ is different from\n_reference documentation_ in that it does not usually describe command\nafter command, but rather concept after concept. So instead of slamming\ngit-*-pack commands together, you have a section \"Handling Packs\" where\nyou try to coherently describe the commands together.\n\nYour approach is fine for something you would call \"Git Reference\nManual\", but it is something really different from \"The Git Book\" or\n\"Git User's Manual\".\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nStuff: http://pasky.or.cz/\nThe meaning of Stonehenge in Traflamadorian, when viewed from above, is:\n\"Replacement part being rushed with all possible speed.\"\n"},{"id":"296265","messageId":"ejq6ul$7co$1@sea.gmane.org","threadId":"43312","inReplyTo":"20061119175952.GX7201@pasky.or.cz","subject":"Re: Git manuals","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2006-11-19T18:16:13Z","receivedAt":"2006-11-19T18:16:13Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Petr Baudis wrote:\n\n> Your approach is fine for something you would call \"Git Reference\n> Manual\", but it is something really different from \"The Git Book\" or\n> \"Git User's Manual\".\n\nBy the way, does AsciiDoc support conversion to texinfo (and then to info)\nformat? It would be nice to have \"The Git Book\" aka \"GUM - Git User's\nManual\" in texinfo, HTML and perhaps also PDF (HTML and PDF with\ngraphs/images).\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n\n"},{"id":"296896","messageId":"20061119193609.GA21866@fieldses.org","threadId":"43312","inReplyTo":"20061119175952.GX7201@pasky.or.cz","subject":"Re: Git manuals","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2006-11-19T19:36:09Z","receivedAt":"2006-11-19T19:36:09Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sun, Nov 19, 2006 at 06:59:52PM +0100, Petr Baudis wrote:\n> On Sun, Nov 19, 2006 at 06:50:40PM CET, J. Bruce Fields wrote:\n> > In fact, I'm tempted to submit a patch that just assigns a chapter\n> > number to everything under Documentation/, slaps a single table of\n> > contents on the front, and calls the result \"the git user's manual.\"\n> > \n> > Of course, the moment people started trying to read the thing they'd\n> > complain that it was a mess--some stuff referenced without being\n> > introduced, other stuff introduced too many times.  But then over time\n> > maybe that'd force us to mold it into some sort of logical sequence.\n> \n> Sequencing isn't the only problem. A _manual_ is different from\n> _reference documentation_ in that it does not usually describe command\n> after command, but rather concept after concept. So instead of slamming\n> git-*-pack commands together, you have a section \"Handling Packs\" where\n> you try to coherently describe the commands together.\n> \n> Your approach is fine for something you would call \"Git Reference\n> Manual\", but it is something really different from \"The Git Book\" or\n> \"Git User's Manual\".\n\nYeah, of course, but I wasn't actually thinking of the man pages so much\nas:\n\teveryday.txt\n\ttutorial.txt\n\ttutorial-2.txt\n\tcore-tutorial.txt\n\thowto/\n\thooks.txt\n\tREADME\n\tglossary.txt\n\netc.\n\n"},{"id":"298263","messageId":"200611192050.52711.robin.rosenberg.lists@dewire.com","threadId":"43312","inReplyTo":"ejq6ul$7co$1@sea.gmane.org","subject":"Re: Git manuals","fromName":"Robin Rosenberg","fromEmail":"robin.rosenberg.lists@dewire.com","sentAt":"2006-11-19T19:50:52Z","receivedAt":"2006-11-19T19:50:52Z","isPatch":false,"sender":{"key":"robin.rosenberg@dewire.com","avatar":"https://avatars.githubusercontent.com/u/46357?v=4"},"body":"söndag 19 november 2006 19:16 skrev Jakub Narebski:\n> Petr Baudis wrote:\n> > Your approach is fine for something you would call \"Git Reference\n> > Manual\", but it is something really different from \"The Git Book\" or\n> > \"Git User's Manual\".\n>\n> By the way, does AsciiDoc support conversion to texinfo (and then to info)\n> format? It would be nice to have \"The Git Book\" aka \"GUM - Git User's\n> Manual\" in texinfo, HTML and perhaps also PDF (HTML and PDF with\n> graphs/images).\nNot sure if there is a texinfo translator, but HTML, PDF and anything else \nthat DocBook can be used for is possible. \n\n"},{"id":"298353","messageId":"20061126040142.GB3782@fieldses.org","threadId":"43312","inReplyTo":"20061119175040.GB15608@fieldses.org","subject":"[PATCH] Documentation: add a \"git user's manual\"","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2006-11-26T04:01:42Z","receivedAt":"2006-11-26T04:01:42Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sun, Nov 19, 2006 at 12:50:40PM -0500, J. Bruce Fields wrote:\n> In fact, I'm tempted to submit a patch that just assigns a chapter\n> number to everything under Documentation/, slaps a single table of\n> contents on the front, and calls the result \"the git user's manual.\"\n\nSomething like this, as a start?:\n\n\nAdd a manual.txt file which generates a \"git user's manual\" by including\na bunch of preexisting files under Documentation and declaring each to\nbe a chapter.\n\nThe result is a disorganized mess, because the documentation itself is a\ndisorganized mess.  This is intended to call attention to that fact\nrather than fix it.  Hopefully we can massage it into a better order\nover time.  And hopefully we can encourage anyone that adds new\ndocumentation to think about where in the order it should be inserted.\n\nNot built or installed by default for now.\n\nSigned-off-by: J. Bruce Fields <bfields@citi.umich.edu>\n---\n Documentation/Makefile    |    7 ++++++-\n Documentation/manual.conf |    2 ++\n Documentation/manual.txt  |   30 ++++++++++++++++++++++++++++++\n 3 files changed, 38 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex c00f5f6..684dacf 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -85,9 +85,14 @@ clean:\n %.1 %.7 : %.xml\n \txmlto -m callouts.xsl man $<\n \n-%.xml : %.txt\n+%.html : %.txt\n \tasciidoc -b docbook -d manpage -f asciidoc.conf $<\n \n+manual.html: manual.txt\n+\ta2x -f xhtml --no-icons --asciidoc-opts=\"-d book -f asciidoc.conf\" $<\n+\n+# a2x -f xhtml --ascidoc-opts=\"-d book -f asciidoc.conf\" $<\n+\n git.html: git.txt README\n \n glossary.html : glossary.txt sort_glossary.pl\ndiff --git a/Documentation/manual.conf b/Documentation/manual.conf\nnew file mode 100644\nindex 0000000..0d0cfad\n--- /dev/null\n+++ b/Documentation/manual.conf\n@@ -0,0 +1,2 @@\n+[titles]\n+underlines=\"__\",\"==\",\"--\",\"~~\",\"^^\"\ndiff --git a/Documentation/manual.txt b/Documentation/manual.txt\nnew file mode 100644\nindex 0000000..5512212\n--- /dev/null\n+++ b/Documentation/manual.txt\n@@ -0,0 +1,30 @@\n+Git User's manual\n+_________________\n+\n+include::tutorial.txt[]\n+\n+include::tutorial-2.txt[]\n+\n+Git design overview\n+===================\n+\n+include::README[]\n+\n+include::everyday.txt[]\n+\n+include::cvs-migration.txt[]\n+\n+include::howto-index.txt[]\n+\n+include::hooks.txt[]\n+\n+include::diffcore.txt[]\n+\n+include::repository-layout.txt[]\n+\n+include::core-tutorial.txt[]\n+\n+Glossary of git terms\n+=====================\n+\n+include::glossary.txt[]\n-- \n1.4.4.rc1.g83ee9\n"}]}