J. Bruce Fields wrote:
On Mon, Jan 08, 2007 at 09:03:05AM -0500, Theodore Tso wrote:
I would add a QuickStart Chapter before you start going into the
"read-only" oeperations. It would show how to create a completely
empty repository, and add a few commits. It would also demonstrate
how to clone an example repository (with a fixed set of contents,
stored at git://git.kernel.org/pub/scm/git/example and add a commit
using "git commit -a".
The basic idea is to show the user that git really isn't that hard,
*before* you start diving into a lot of details. If you don't tell a
user how to make a commit until Chapter 3, he/she will assume it's
because it's Really Hard, and you may end up losing them before that.
Yeah, I agree. I just haven't been able to decide quite what to choose
for that purpose. Some choices:
- We could just pare down the tutorial a bit and drag it in as
chapter one.
- I tried writing something modeled loosely on the hg quick
start. It's a little out of date now, but that could be
fixed:
http://www.fieldses.org/~bfields/git-quick-start.html
I like this, although fetch should probably have "--force" instead of
the "+branch" notation. --force stands out more and users are familiar
with --force possibly destroying things (rm -rf, anyone?).
- Or maybe a revised everyday.txt would do the job?
Any opinions?
I think the document is fine as it is, but could probably start off with
a link to the tutorial, quickstart or a revised version of everyday.txt,
stating that "here's something you might want to read if you prefer to
experiment. If you think something goes wrong, come back here and find
out why".
At least some discussions of branches needs to happen here;
The basic nuts-and-bolts (how to create and delete branches, etc.)
should all be covered, of course, but....
I found it quite sufficient. Perhaps it would be nice to include some
more advanced examples, like octopus merges and things like that,
although I feel such things could well live in an appendix to keep all
the easy operations up front. Most people I know will most likely
*never* use octopus merges. 90% of the merges we do here at work result
in fast-forwards, so a real merge is already considered a bit odd.
it's really important to talk about different workflows, and how you
use branches as part of your read-write operations. Some folks might
or might not use topic branches, but the concept of using temporary
branches to try things out is critical.
.... Maybe it'd be fun to have a section called just "examples" at the
end of each chapter. The sort of thing you're describing could fit in
well there. I'd need some help collecting interesting examples.
Indeed. I for one like examples that tell me
# type this
# this will happen
# you can see what you just did with this, this, and this command
# this is because...
Not only is it good for learning the how and the why, but it also trains
the fingers right from the start. Hopefully the UI is stabilized enough
by now that we can reliably tell users how to accomplish a certain
thing. UI changes must almost certainly be listed at whatever official
site git has. As Junio has already pointed out, the members of the git
mailing list are now in minority among the git users, so some other
place has to hold the user-visible changes as well and the location of
that site must probably be published along with the tools.
--
Andreas Ericsson andreas.ericsson@xxxxxx
OP5 AB www.op5.se
Tel: +46 8-230225 Fax: +46 8-230231
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html