Subject: Re: [PATCH] Add examples section to 'git fetch' manual

From: Junio C Hamano <[email-masked]>
Date: Sun, 13 Apr 2008 18:02:45 -0700

Teemu Likonen <[email-masked]> writes:

> ... I still feel that refspecs need more
> explaining ...

Perhaps.  The basic syntax is "src colon dst" and they are used to copy
what's in src to dst, and that is pretty much what's there to it.  Some
details such as how the wildcard matching works may be missing from the
description part of the manual, and filling them in would be a good idea.

I however strongly suspect that what new people need to get explained may
not be what the mechanism does (e.g. copies the object name recorded as
the src ref to the dst ref), nor the syntax you use to tell the mechanism
what to copy where (e.g. src is LHS, dst is RHS, copying "emptyness" into
dst means deleting dst).  I actually think that is an easier part.

What is more important is the basic concepts like what a ref is, how they
can be used and what you can do with them --- understanding of which would
be essential in being able to decide when and how you maywant to keep a
copy of ref you get from elsewhere and under what name.  I think tutorial
is the best place, and then the description section of the manual the
second best one, to document that kind of things.