{"thread":{"id":"4079","subject":"[RFC] Managing projects - advanced Git tutorial/walkthrough","startedAt":"2006-05-06T08:43:37Z","lastAt":"2006-05-07T01:34:56Z","messageCount":4,"participants":["Jakub Narebski","Junio C Hamano","sean","J. Bruce Fields"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"19602","messageId":"e3hnjg$k9f$1@sea.gmane.org","threadId":"4079","inReplyTo":null,"subject":"[RFC] Managing projects - advanced Git tutorial/walkthrough","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2006-05-06T08:43:37Z","receivedAt":"2006-05-06T08:43:37Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"I have browsed through Git documentation: \"A tutorial introduction to\ngit\" (tutorial.txt), \"A short git tutorial\" (core-tutorial.txt) which\ncontrary to the title is the tutorial in low-level git commands and is\nlonger that the first one, \"Everyday GIT With 20 Commands Or\nSo\" (everyday.txt) and \"git for CVS users\" (cvs-migration.txt) which does\nnot mention git-blame and git-annotate.\n\nWhat I miss is walkthrough type tutorial, describing typical workflow (or\nworkflows), and tutorial concentrating on advanced topics which may come\nonce in a while or for some topics only, but it would be nice to know how\nto resolve them.\n\nPerhaps some of the following problems would need Git improvement (e.g.\nbetter support for subprojects: \"bind\" idea)...\n\n\n1. Description of typical workflow, with 'stable'/'maintenance'/'fixes' and\n'development'/'master'/'main' branches, how to put bugfixes into both\nbranches etc. Perhaps description of git branches and workflow, or Linux\nkernel branches and workflow.\n\n2. Contrib: how to add project which was externally managed to contrib and\nlater/or to core, preserving history. Examples: gitk for git, or like\nperhaps parsecvs would be for git, or like git-svn for git.\n\n3. Subprojects: how to manage project which depends on other externally\nmanaged (third-party) project, and perhaps needs patches for it. Examples:\nout of tree kernel patches + userspace tools, plugin for some program which\nmay need bugfixes, program which need some library, gitk before\nincorporating into git,... Perhaps description of the whole sequence of\nproject development from add-on project (some new filesystem for Linux,\ngitk) to being incorporated into bigger project (filesystem included in\nLinux kernel, gitk in git repository).\n\n4. Splitting repository: splitting one big project (X.org, Linux\ndistribution) into modules.\n\n-- \nJakub Narebski\nWarsaw, Poland\n"},{"id":"19613","messageId":"7v64kisyow.fsf@assigned-by-dhcp.cox.net","threadId":"4079","inReplyTo":"e3hnjg$k9f$1@sea.gmane.org","subject":"Re: [RFC] Managing projects - advanced Git tutorial/walkthrough","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-05-06T20:09:03Z","receivedAt":"2006-05-06T20:09:03Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narebski <jnareb@gmail.com> writes:\n\n> I have browsed through Git documentation: \"A tutorial introduction to\n> git\" (tutorial.txt), \"A short git tutorial\" (core-tutorial.txt) which\n> contrary to the title is the tutorial in low-level git commands and is\n> longer that the first one, \"Everyday GIT With 20 Commands Or\n> So\" (everyday.txt) and \"git for CVS users\" (cvs-migration.txt) which does\n> not mention git-blame and git-annotate.\n\nI was initially somewhat dissapointed that a posting marked as\nRFC did not contain a draft that is commentable, but we would\nprobably want to know how the updated document set will be\norganized in general first.  There was a discussion both here\nand on #irc, while Pasky and gang were working on the wiki,\nabout sprucing up the introductory documentation set.\n\nThe core-tutorial grow out of a short tutorial to start from\nPlumbing basics (what's in object store) to cover Porcelainish;\nwhen it was written there was not another user-level document,\nso it had to cover both, but it is probably a good idea to move\nthe parts that talk about Porcelainish to other documents and\nmake it \"A short tutorial on git Plumbing\" document.  Maybe we\ncan have a tiered document set like this:\n\n - Your first experience with git with walkthru.  This shows the\n   minimum basic operations to get started a stand-alone \"hello\n   world\" project, without talking about index nor object store.\n   The current tutorial.txt is probably good enough with\n   updates.\n\n - Understanding git as an end user.  Currently, this is\n   included in the global map git(7) documentation.  It might\n   make sense to separate it out.  This should talk about\n   concepts like blobs/trees/commits/trust/index without going\n   into lowlevel details of the implementation.  The stress\n   should be on what they are for, not operationally but\n   philosophically.  What's currently in README would be\n   suitable for this part, with some additional topics:\n\n   - branches.  \"Tying it all together\" section talks about the\n     single branch and \"the HEAD state\"; we should talk about\n     why you would want to use multiple branches (either\n     keeping track of your own development, or keeping track of\n     somebody else's) and stress branches are to keep separate\n     things separate (explained that way it becomes clear why\n     you should not commit on a remote tracking branch).\n\n   - ancestry traversal.  what \"A..B\" or \"^A ^B C\" means and why\n     you would want to say them.\n\n - Everyday.\n\n - Special interests: cvs migration, howto/ documents.\n\n - The global map git(7) with pointers to individual commands,\n   and the glossary.\n\n - Tutorial on Plumbing.\n\nFor a new end-user, the order to read would be from the top to\nbottom.  \"Everyday\" should cover most of what are needed for\ndifferent classes of users, and other things can be looked up\nfrom the global map.\n\n\nI think tutorial.txt is the right \"your first experience with\ngit with walkthru\" document, and the materials it gives, and the\norder in which it introduces them, are very well thought out;\nkudos to JBF.  We might also want to show \"git grep\", but other\nthan that I do not think of anything that a new user might want\nto use on the first day.\n\nIt is deliberately sketchy at times to keep the flow of walkthru\nclean and simple, and I'd like to keep it that way.  I would\nhowever like to see the examples to show the expected output\nfrom the commands, like the initial part of the current\ncore-tutorial.txt does.  Also, I'd like to see a \"see also\" link\nto each step that refers the user to \"what if this step does not\nwork as expected for you\", either separate document or a section\nin the appendix part of the same document, without cluttering\nthe main text too much.\n\nSome commands and syntax it mentions may need to be rethought in\nthe light what happened recently, especially the internal\nversion of diff and log/show/whatchanged unification that\nhappened before the 1.3.0 came out.\n\n * \"git diff A B\" should probably be spelled as \"git diff A..B\"\n   throughout for consistency.\n\n * Today's \"git log\" is more powerful than the one we had when\n   the tutorial was first written, and we probably want to\n   recommend \"git log [-p|--stat]\" in place of whatchanged;\n   whatchanged is kept primarily for historical reasons and to\n   give a different default output format than log.  A new user\n   does not have to even know about it.\n\nThen reorganize the initial part core-tutorial.txt to match the\nexamples tutorial.txt gives, and demonstrate what is happening\nunder the hood.  The tutorial says \"git init-db\" then \"git\nadd\".  The core-tutorial would match that and explain what\nhappens when \"git init-db\" is run (creates .git/objects etc.)\nand \"git add\" is run (populates the index).\n"},{"id":"19620","messageId":"BAYC1-PASMTP10D8E6E33237EA0B422677AEAA0@CEZ.ICE","threadId":"4079","inReplyTo":"7v64kisyow.fsf@assigned-by-dhcp.cox.net","subject":"Re: [RFC] Managing projects - advanced Git tutorial/walkthrough","fromName":"sean","fromEmail":"seanlkml@sympatico.ca","sentAt":"2006-05-06T21:54:50Z","receivedAt":"2006-05-06T21:54:50Z","isPatch":false,"sender":{"key":"seanlkml@sympatico.ca","avatar":"https://gravatar.com/avatar/f92923f54fc08c401fc59b71829d4b89e9b8087fbba45ff87c82e6a83aee02ae?d=mp&s=160"},"body":"On Sat, 06 May 2006 13:09:03 -0700\nJunio C Hamano <junkio@cox.net> wrote:\n\n[...]\n> I think tutorial.txt is the right \"your first experience with\n> git with walkthru\" document, and the materials it gives, and the\n> order in which it introduces them, are very well thought out;\n> kudos to JBF.  We might also want to show \"git grep\", but other\n> than that I do not think of anything that a new user might want\n> to use on the first day.\n\nIt doesn't mention git log, show or status which are important\nfor the first day.  Also an example of git commit --amend would\nbe a nice touch.\n\nPart of the problem people new to git are having arise by reading\ndocumentation in the wrong order and coming to the conclusion that\ngit is an ugly beast.   Also many people are still finding out-of-\ndate information before anything else (eg. git isn't an scm only an\nobject tracker).\n\nPart of this will be solved by having a useful and inviting web page\n(thanks Pasky!).  But it would also help to rename core-tutorial.txt\nto something that doesn't sound inviting to newbies.  Something\nalong the line of core-internal-design.txt (or here-be-dragons.txt).\n\nTurning the main man page into more of a reference than a tutorial\nslash concepts page would be something worth doing too.  Removing\nall of the plumbing commands from that page should at least be\nconsidered.\n\n[...]\n\n> Then reorganize the initial part core-tutorial.txt to match the\n> examples tutorial.txt gives, and demonstrate what is happening\n> under the hood.  The tutorial says \"git init-db\" then \"git\n> add\".  The core-tutorial would match that and explain what\n> happens when \"git init-db\" is run (creates .git/objects etc.)\n> and \"git add\" is run (populates the index).\n> \n\nThere really seems to be a lot of room for another intermediate user\nlevel document between tutorial.txt and the current core-tutorial.txt.\nThere are lots of concepts that can be explained without having to get\ninto the low level design or tools of git.  For example, a user could\nhave long been productive with git before ever having to learn about\nread-tree/write-tree etc.. all those commands are more for porcelain\nwriters and git guru/experts now.\n\nSean\n"},{"id":"19634","messageId":"20060507013455.GB5709@fieldses.org","threadId":"4079","inReplyTo":"7v64kisyow.fsf@assigned-by-dhcp.cox.net","subject":"Re: [RFC] Managing projects - advanced Git tutorial/walkthrough","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2006-05-07T01:34:56Z","receivedAt":"2006-05-07T01:34:56Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sat, May 06, 2006 at 01:09:03PM -0700, Junio C Hamano wrote:\n>  - Understanding git as an end user.  Currently, this is\n>    included in the global map git(7) documentation.  It might\n>    make sense to separate it out.  This should talk about\n>    concepts like blobs/trees/commits/trust/index without going\n>    into lowlevel details of the implementation.  The stress\n>    should be on what they are for, not operationally but\n>    philosophically.  What's currently in README would be\n>    suitable for this part, with some additional topics:\n\nYeah, I actually made a start at a sequel to tutorial.txt, with the goal\nthat after reading the sequel a user would have encountered the main\nconcepts necessary to read any of the man pages--mainly the object\ndatabase and the index file.  My work so far is in the\n\"advanced-tutorial\" branch of\n\n\tgit://linux-nfs.org/~bfields/exports/git.git\n\nbut it needs some cleaning up.\n\nI was hoping I'd be able to replace some of the README or\ncore-tutorial.txt in the process, but the latter has a lot of\ngit-hacker-only detail in it, and the former is a bit more verbose and\nhas some motivation (explaining why stuff was designed the way it was)\nthat is nice but maybe not necessary for a minimal tutorial.\n\n--b.\n"}]}