Git Documentation

Git Documentation

[Scott Chacon]

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

Re: Git Documentation

[Johan Herland]

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, <johan@herland.net>
www.herland.net

Re: Git Documentation

[david]

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 <insert 
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.


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

Re: Git Documentation

[Johan Herland]

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 <insert
> 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, <johan@herland.net>
www.herland.net

Re: Git Documentation

[Pedro Melo]

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!

Re: Git Documentation

[Johannes Schindelin]

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

Re: Git Documentation

[Scott Chacon]

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
<Johannes.Schindelin@gmx.de> 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
>
>

Re: Git Documentation

[Jay Soffian]

On Tue, Jul 22, 2008 at 7:40 AM, Johannes Schindelin
<Johannes.Schindelin@gmx.de> 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.

Re: Git Documentation

[Johannes Schindelin]

Hi,

On Tue, 22 Jul 2008, Jay Soffian wrote:

> On Tue, Jul 22, 2008 at 7:40 AM, Johannes Schindelin
> <Johannes.Schindelin@gmx.de> 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

Re: Git Documentation

[Karl Hasselström]

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

Re: git documentation

[Jakub Narebski]

David Lang <david@lang.hm> writes:

> On lwn there is a comment (under the GNOME survey topic)
> http://lwn.net/Articles/313435/
> 
> The Shlomi Fish "Better SCM" site for example is very clear that Git
> won't do a merge across a rename. It even has a citation for this
> claim. But as a Git user who has actually done a merge across a rename
> I know it works just fine, and anyone familiar with Git's internals
> will guess immediately why. Yet probably there is no line of
> documentation on the Git site or elsewhere that I can quote to justify
> adding a "Yes" to the comparison.

I have tried to add info about Git to Better SCM quite a long time
ago; it was finally added by (IIRC) Alexey Mahotkin for
http://versioncontrolblog.com and sent for inclusion in Better SCM to
Shlomi Fish.

Unfortunately it contains some factual errors. I have sent corrections
to Alexey, but didn't finish it:
  "Git at Better SCM Initiative comparison of VCS (long)"
  http://article.gmane.org/gmane.comp.version-control.git/97253
(see also other posts in this thread, and other posts with the same,
or similar, subject on git mailing list).

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: git documentation

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 390 bytes --]

On Mon, Jan 05, 2009 at 05:46:56PM -0800, david@lang.hm wrote:
> why. Yet probably there is no line of documentation on the Git site or 
> elsewhere that I can quote to justify adding a "Yes" to the comparison.

I think it's documented in Documentation/merge-strategies.txt, under the
'recursive' merge strategy:

"Additionally this can detect and handle merges involving renames."

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

git documentation

[david]

on lwn there is a comment (under the GNOME survey topic)
http://lwn.net/Articles/313435/

The Shlomi Fish "Better SCM" site for example is very clear that Git won't 
do a merge across a rename. It even has a citation for this claim. But as 
a Git user who has actually done a merge across a rename I know it works 
just fine, and anyone familiar with Git's internals will guess immediately 
why. Yet probably there is no line of documentation on the Git site or 
elsewhere that I can quote to justify adding a "Yes" to the comparison.


sounds like a missing piece of documentation that someone should be able 
to fill in fairly easily.

David Lang