# Git Documentation 10 messages from 2008-07-22 to 2008-07-24. Participants: Scott Chacon, Johan Herland, david@lang.hm, Pedro Melo, Johannes Schindelin, Jay Soffian, Karl Hasselström. Thread: https://gitlist.dev/t/14584 ## Scott Chacon, 2008-07-22 03:35 Subject: Git Documentation Message-ID: URL: https://gitlist.dev/e/d411cc4a0807212035v68c2ed95m93b77c1e61cfec9e%40mail.gmail.com ``` Hey all, I'm starting a project to host a really nice, user-friendly, easy to use Git learning materials website for Git newbies to get new users started and make it as easy to learn as possible. I'll be redoing or editing some of my screencasts from gitcasts.com and starting an open book at github and putting it all in one place for new users to get started easily. Anyone will be free to submit changes, additions, etc. If anyone has any tips on how they think git should be taught, issues they are asked a lot, problems newbies tend to have, something they wish there were a screencast for or was better documented, etc - please do contact me so I can incorporate it. I would contribute to git itself, but my C-foo is seriously wanting, so if by teaching people properly I can free up some time for you guys, I would love to do so. Please let me know if you have any pointers or think anything should really be better documented for end-users. I plan to do a lot of graphics, screencasts and whatever else makes it as simple as possible. Thanks, and thanks again for git. Scott Chacon ``` ## Johan Herland, 2008-07-22 07:17 Subject: Re: Git Documentation Message-ID: <200807220917.57363.johan@herland.net> URL: https://gitlist.dev/e/200807220917.57363.johan%40herland.net In-Reply-To: ``` On Tuesday 22 July 2008, Scott Chacon wrote: > If anyone has any tips on how they think git should be taught, issues > they are asked a lot, problems newbies tend to have, something they > wish there were a screencast for or was better documented, etc - > please do contact me so I can incorporate it. You should at least take a look at this thread: http://thread.gmane.org/gmane.comp.version-control.git/88698 (even though it goes off-topic after a while...) > If anyone has any tips on how they think git should be taught... It seems there are primarily two ways to teach Git: 1. Top-down: Start with simple use cases and commands. Teach people a minimal, but necessary set of porcelain commands to get them started. Stay _far_ away from plumbing commands and most of the command options. 2. Bottom-up: Start with how Git structures the data. Talk about blobs, trees, commits, refs, how everything is connected, and how various Git commands query and manipulate this structure. This _may_ involve a fair amount of plumbing commands, especially when discovering how the more complicated high-level commands manipulate the structure. Some people seem to prefer the first approach, other people prefer the other approach. Both paths lead to enlightenment ;). In many cases a bit of both may be useful. HOWEVER, I think it is _very_ important to keep in mind that these are two _different_ approaches, and the contexts in which they are taught should be kept separate. I would almost suggest splitting your website down the middle and make the difference between top-down and bottom-up immediately visible with, say, a different background color, or something else that immediately tells the user what "track" they are following... BTW, I think what you're doing is good and important (and I've already enjoyed some of your gitcasts). Keep up the good work! :) Have fun! ...Johan -- Johan Herland, www.herland.net ``` ## david@lang.hm, 2008-07-22 07:56 Subject: Re: Git Documentation Message-ID: URL: https://gitlist.dev/e/alpine.DEB.1.10.0807220035110.1125%40asgard.lang.hm In-Reply-To: <200807220917.57363.johan@herland.net> ``` On Tue, 22 Jul 2008, Johan Herland wrote: > On Tuesday 22 July 2008, Scott Chacon wrote: >> If anyone has any tips on how they think git should be taught, issues >> they are asked a lot, problems newbies tend to have, something they >> wish there were a screencast for or was better documented, etc - >> please do contact me so I can incorporate it. > > You should at least take a look at this thread: > > http://thread.gmane.org/gmane.comp.version-control.git/88698 > > (even though it goes off-topic after a while...) > >> If anyone has any tips on how they think git should be taught... > > It seems there are primarily two ways to teach Git: > > 1. Top-down: Start with simple use cases and commands. Teach people a > minimal, but necessary set of porcelain commands to get them started. Stay > _far_ away from plumbing commands and most of the command options. > > 2. Bottom-up: Start with how Git structures the data. Talk about blobs, > trees, commits, refs, how everything is connected, and how various Git > commands query and manipulate this structure. This _may_ involve a fair > amount of plumbing commands, especially when discovering how the more > complicated high-level commands manipulate the structure. > > Some people seem to prefer the first approach, other people prefer the other > approach. Both paths lead to enlightenment ;). In many cases a bit of both > may be useful. HOWEVER, I think it is _very_ important to keep in mind that > these are two _different_ approaches, and the contexts in which they are > taught should be kept separate. I would almost suggest splitting your > website down the middle and make the difference between top-down and > bottom-up immediately visible with, say, a different background color, or > something else that immediately tells the user what "track" they are > following... possibly a combination of the two? under the covers the git data-structures are pretty simple and explaining them (and the minimal tools to manipulate them) isn't that bad. what gets ugly is when you then try to use the plumbing to do the non-trivial things. so how about an optional 'under the covers' primer, covering just the trivial plumbing, then the high-level minimal introduction with a link on each of the commands as they are introduced (so that a person can dig into deeper detail if they want to, possibly including 'up until version X this command was implemented by the following script'), followed by links to sample work-flows and a full dive into the plumbing (because at this point the person should know enough to get by, now they need reference material and examples more then a tutorial). ideally this would let people dive as deep as they are comfortable with, or skim the explanation for the functionality I think one reason the 'plumbing first' approach gets a bad rap is that it's so easy to get caught up into how clever you can get with the plumbing. it's like teaching someone programming by spending a day introducing them to concepts and language syntax, and then giving them the entries in the obfuscated C contests as examples of how someone can use them to get work done, but skipping any mention of libc or other standard libraries. on the other hand, teaching only porcelain is like teaching them without teaching any concept of what they computer is doing under the covers, they can work, and even get useful work done, but they will be limited on how effective they can be. you can't be a great programmer until you can understand both levels, the under-the-covers 'plumbing' and the high level libraries of the 'porcelain', trying to ignore either will limit you. David Lang ``` ## Johan Herland, 2008-07-22 09:21 Subject: Re: Git Documentation Message-ID: <200807221121.22520.johan@herland.net> URL: https://gitlist.dev/e/200807221121.22520.johan%40herland.net In-Reply-To: ``` On Tuesday 22 July 2008, david@lang.hm wrote: > On Tue, 22 Jul 2008, Johan Herland wrote: > > It seems there are primarily two ways to teach Git: > > > > 1. Top-down: Start with simple use cases and commands. Teach people a > > minimal, but necessary set of porcelain commands to get them started. > > Stay _far_ away from plumbing commands and most of the command options. > > > > 2. Bottom-up: Start with how Git structures the data. Talk about blobs, > > trees, commits, refs, how everything is connected, and how various Git > > commands query and manipulate this structure. This _may_ involve a fair > > amount of plumbing commands, especially when discovering how the more > > complicated high-level commands manipulate the structure. > > > > Some people seem to prefer the first approach, other people prefer the > > other approach. Both paths lead to enlightenment ;). In many cases a > > bit of both may be useful. HOWEVER, I think it is _very_ important to > > keep in mind that these are two _different_ approaches, and the > > contexts in which they are taught should be kept separate. I would > > almost suggest splitting your website down the middle and make the > > difference between top-down and bottom-up immediately visible with, > > say, a different background color, or something else that immediately > > tells the user what "track" they are following... > > possibly a combination of the two? > > under the covers the git data-structures are pretty simple and explaining > them (and the minimal tools to manipulate them) isn't that bad. Not sure. In both cases one will need _some_ kind of model to work with, but I think that for the top-down approach, it will suffice with a very simple/simplified model along the lines of: - A commit contains the state of some repo at some point in time (plus some metadata) - A commit points to its direct parents (zero or more). A collection of commits make up a DAG, representing the history of a project. - Refs point to select commits. Tags are static, branches are dynamic, etc. Specifically, for the top-down approach I do NOT think it is necessary to teach: - blobs and trees - plumbing tools > what gets ugly is when you then try to use the plumbing to do the > non-trivial things. Certainly. We should only use plumbing tools in the bottom-up approach, and even then we should only use them when it _simplifies_ or otherwise nicely _illustrates_ the concepts being taught. > so how about an optional 'under the covers' primer, covering just the > trivial plumbing, then the high-level minimal introduction with a link on > each of the commands as they are introduced (so that a person can dig > into deeper detail if they want to, possibly including 'up until version > X this command was implemented by the following script'), followed by > links to sample work-flows and a full dive into the plumbing (because at > this point the person should know enough to get by, now they need > reference material and examples more then a tutorial). Nope. A primer (i.e. a document to be read before the "real" teaching starts) should not cover more than the simplest/simplified model (see above). Of course, the courses should reference manual pages and more in-depth documentation wherever it makes sense, but we should make sure to note that such knowledge is not _required_ to follow the course. > ideally this would let people dive as deep as they are comfortable with, > or skim the explanation for the functionality > > I think one reason the 'plumbing first' approach gets a bad rap is that > it's so easy to get caught up into how clever you can get with the > plumbing. it's like teaching someone programming by spending a day > introducing them to concepts and language syntax, and then giving them > the entries in the obfuscated C contests as examples of how someone can > use them to get work done, but skipping any mention of libc or other > standard libraries. I see your point, but I still don't think teaching plumbing have any value in and of itself (unless you need to specifically learn plumbing to write porcelain code/scripts, in which case you'd better already know how to navigate the existing manual pages and other documentation). For newbies, I think plumbing should only be taught/mentioned when it simplifies or illustrates a concept in the bottom-up approach. > on the other hand, teaching only porcelain is like teaching them high-level *th generation buzzword language> without teaching any concept > of what they computer is doing under the covers, they can work, and even > get useful work done, but they will be limited on how effective they can > be. I don't agree that teaching only porcelain will not give them any concept of what their computer does "under the covers". I think we can teach porcelain with reference to the simplified object model, and still achieve a (simplified, but still rewarding) understanding of what happens at an object level. When I use Git myself, I normally only think in terms of the simplified model, and I have no problem getting things done without paying attention to the full object model (blobs, trees, etc) or the plumbing tools that are implicitly involved in the process. > you can't be a great programmer until you can understand both levels, the > under-the-covers 'plumbing' and the high level libraries of the > 'porcelain', trying to ignore either will limit you. Agreed. But we shouldn't need every Git user to be a great programmer. At least I hope not. Otherwise, there will be few Git users, indeed... ;) Many Git users will not be VCS geeks like us; they will be "regular" people that use Git because it's useful for them (or because they're forced to use Git at $dayjob). They will not be interested in how Git manages their data, and how a complex Git operation can be split into simple plumbing components. We should not require them to learn such details in order to become good Git users. Instead we should teach them Git using porcelain commands with reference to the simplified object model. They should learn how to use Git in a simple, yet still rewarding manner. ...and _that_ is how we achieve world domination ;) Have fun! :) ...Johan -- Johan Herland, www.herland.net ``` ## Pedro Melo, 2008-07-22 10:15 Subject: Re: Git Documentation Message-ID: URL: https://gitlist.dev/e/EDFF27AB-9B74-4868-A0BF-61AC8ED75037%40simplicidade.org In-Reply-To: ``` Hi, On Jul 22, 2008, at 4:35 AM, Scott Chacon wrote: > I'm starting a project to host a really nice, user-friendly, easy to > use Git learning materials website for Git newbies to get new users > started and make it as easy to learn as possible. I'll be redoing or > editing some of my screencasts from gitcasts.com and starting an open > book at github and putting it all in one place for new users to get > started easily. Anyone will be free to submit changes, additions, > etc. > > If anyone has any tips on how they think git should be taught, issues > they are asked a lot, problems newbies tend to have, something they > wish there were a screencast for or was better documented, etc - > please do contact me so I can incorporate it. I would contribute to > git itself, but my C-foo is seriously wanting, so if by teaching > people properly I can free up some time for you guys, I would love to > do so. > > Please let me know if you have any pointers or think anything should > really be better documented for end-users. I plan to do a lot of > graphics, screencasts and whatever else makes it as simple as > possible. A section on usual workflows and setups would be most useful. Some like a pull/push workflow, others a email based workflow. As for learning git stuff, I usually point new users to your stuff :). I also point them to Tommi Virtanen "Git for Computer Scientists":http://eagain.net/articles/git-for-computer-scientists/ . It was that article that made it all "click" for me regarding git. Best regards, -- Pedro Melo Blog: http://www.simplicidade.org/notes/ XMPP ID: melo@simplicidade.org Use XMPP! ``` ## Johannes Schindelin, 2008-07-22 11:40 Subject: Re: Git Documentation Message-ID: URL: https://gitlist.dev/e/alpine.DEB.1.00.0807221335560.3391%40eeepc-johanness In-Reply-To: <200807221121.22520.johan@herland.net> ``` Hi, On Tue, 22 Jul 2008, Johan Herland wrote: > Many Git users will not be VCS geeks like us; they will be "regular" > people that use Git because it's useful for them (or because they're > forced to use Git at $dayjob). Exactly. But it seems a concept hard to understand to some people. It also seems that VCS geeks like scripting, and assume everybody else does, too. Not so. Most people hate to know the internals. They buy the car, and never want to look inside the motor compartment. They buy wine, and never want to know how it is made. They buy an iPod and never want to know who assembles it, and how, and in what environment. You cannot teach those people to be more interested/interesting by showing them how things work internally. But you can give Git a bad reputation in the process. This, amongst other reasons, was why a company I worked at had a policy to never _ever_ have presentations or tutorials by technical staff. Never. Ciao, Dscho ``` ## Scott Chacon, 2008-07-22 14:46 Subject: Re: Git Documentation Message-ID: URL: https://gitlist.dev/e/d411cc4a0807220746l3dfbca0fk11364741a36da14c%40mail.gmail.com In-Reply-To: ``` Thanks all for your input - I like the idea of the two-track thing and I'll probably use a lot of what you've laid out to help structure the site. I have personally tried to do a quick under the covers overview beforehand because I have found that it helps, but I know many of you work with new converts a lot too, so thanks again for your feedback. As this gets going, I'll post here with updates from time to time to make sure not too many of you feel it's going too far off track or I'm not making incredible mistakes anywhere. Thanks, Scott On Tue, Jul 22, 2008 at 4:40 AM, Johannes Schindelin wrote: > Hi, > > On Tue, 22 Jul 2008, Johan Herland wrote: > >> Many Git users will not be VCS geeks like us; they will be "regular" >> people that use Git because it's useful for them (or because they're >> forced to use Git at $dayjob). > > Exactly. But it seems a concept hard to understand to some people. It > also seems that VCS geeks like scripting, and assume everybody else does, > too. Not so. > > Most people hate to know the internals. They buy the car, and never want > to look inside the motor compartment. They buy wine, and never want to > know how it is made. They buy an iPod and never want to know who > assembles it, and how, and in what environment. > > You cannot teach those people to be more interested/interesting by showing > them how things work internally. But you can give Git a bad reputation in > the process. > > This, amongst other reasons, was why a company I worked at had a policy to > never _ever_ have presentations or tutorials by technical staff. Never. > > Ciao, > Dscho > > ``` ## Jay Soffian, 2008-07-22 15:47 Subject: Re: Git Documentation Message-ID: <76718490807220847i298f256bm4c3f85bfde079ee2@mail.gmail.com> URL: https://gitlist.dev/e/76718490807220847i298f256bm4c3f85bfde079ee2%40mail.gmail.com In-Reply-To: ``` On Tue, Jul 22, 2008 at 7:40 AM, Johannes Schindelin wrote: > Most people hate to know the internals. They buy the car, and never want > to look inside the motor compartment. They buy wine, and never want to > know how it is made. They buy an iPod and never want to know who > assembles it, and how, and in what environment. I agree with this. And I like the top-down approach. Nonetheless, I think there are a few git concepts that are important to understand. Specifically, I don't think you can use git without understanding the index. Unfortunately, git isn't quite as good about abstractions yet as some of the items you make analogies to. And even car's leak: "And you can't drive as fast when it's raining, even though your car has windshield wipers and headlights and a roof and a heater, all of which protect you from caring about the fact that it's raining (they abstract away the weather), but lo, you have to worry about hydroplaning (or aquaplaning in England) and sometimes the rain is so strong you can't see very far ahead so you go slower in the rain, because the weather can never be completely abstracted away, because of the law of leaky abstractions." http://www.joelonsoftware.com/articles/LeakyAbstractions.html :-) j. ``` ## Johannes Schindelin, 2008-07-22 16:07 Subject: Re: Git Documentation Message-ID: URL: https://gitlist.dev/e/alpine.DEB.1.00.0807221705150.8986%40racer In-Reply-To: <76718490807220847i298f256bm4c3f85bfde079ee2@mail.gmail.com> ``` Hi, On Tue, 22 Jul 2008, Jay Soffian wrote: > On Tue, Jul 22, 2008 at 7:40 AM, Johannes Schindelin > wrote: > > Most people hate to know the internals. They buy the car, and never > > want to look inside the motor compartment. They buy wine, and never > > want to know how it is made. They buy an iPod and never want to know > > who assembles it, and how, and in what environment. > > I agree with this. And I like the top-down approach. Nonetheless, I > think there are a few git concepts that are important to understand. > Specifically, I don't think you can use git without understanding the > index. I do not see that the index is an internal. I see that the term "index" is. So I think about not even bothering to mention it in my first two Git lessons. And you would be surprised to learn that I personally know a few people who use Git happily _without_ knowing any internals. Now guess why: was it because I explained a few easy-to-grasp commands, or because I made it pretty complicated but thorough? Exactly. Ciao, Dscho ``` ## Karl Hasselström, 2008-07-24 00:31 Subject: Re: Git Documentation Message-ID: <20080724003105.GA16873@diana.vm.bytemark.co.uk> URL: https://gitlist.dev/e/20080724003105.GA16873%40diana.vm.bytemark.co.uk In-Reply-To: ``` On 2008-07-22 11:15:40 +0100, Pedro Melo wrote: > I also point them to Tommi Virtanen "Git for Computer > Scientists":http://eagain.net/articles/git-for-computer-scientists/. > It was that article that made it all "click" for me regarding git. Me too. I've found that starting off by explaining how git represents history with blobs, trees, and commits (no need to mention tags or other objects just yet), and how branches and merging just fall out naturally from the commit DAG, is a good way to get people to appreciate just how simple git's data model is. After that five-minute introduction, they have a reasonable mental model of what the git commands operate on -- then they just need to fill in the details, like what commands there are and how they work. (I've never taught git to anyone who didn't already know what a DAG or a cryptographic hash is -- presumably, that would make it take more than five minutes.) -- Karl Hasselström, kha@treskal.com www.treskal.com/kalle ```