On Thu, 19 Apr 2007, Marcin Kasperski wrote:
> >
> > I agree. And to some degree I suspect that the documentation pushes some of
> > the advanced things a bit *too* eagerly. (...)
>
> As I am among those, who think that git *is* complicated, I decided to
> sit down, and find out why exactly I think so. Here are the top
> words/options/concepts, which I faced almost immediately while trying
> GIT, and which I find confusing:
>
> rebase
> index
> revtree
> reset
> ref / refs
> rev-list
> rev-parse
Yes. I think it might be a good idea to write some kind of tutorial aimed
for two very simple cases. Because there are really two cases that stand
out as being (a) common and (b) something you start out with!
- Case #1 would be using git basically as a "anonymous CVS" replacement
to track somebody others project.
None of the above are ever really needed for that case, and I think all
you really want to learn is:
git clone
git pull
gitk
git log HEAD@{2.days.ago}..
gitk HEAD@{1}.. some-file-or-directory
and not a whole lot more (maybe pointing them at gitweb repos and
telling them what the thing can do). In other words, you want to teach
people to just fetch the repo, and perhaps how to see what has changed
lately.
In an advanced section for this usage case might be things like
git bisect
to teach people who track other peoples repository how to help those
other people find bugs when something goes wrong. But that would
literally be an "advanced topic".
- Case #2 is the "how to start tracking your own project".
In some ways, it's even *more* trivial, becuase if you start a new
project, you usually start from scratch (or perhaps from some CVS
import), with just one branch, and your first worry is not even how to
export it yet, but how to just *use* it for development.
So for case #2, we'd never even mention "git clone/pull" or branches,
but instead we'd just talk about
git init (and "git cvsimport" or something)
git add/rm/commit
git diff/show
git reset
git checkout
and walk through an everyday problem set of just some _very_ basic
situations. Explain the whole "content" thing, so that people
understand why "git add <filename>" + "git diff" doesn't actually show
the filename at all, and what the difference between "git diff" and
"git diff HEAD" is.
Those two usage cases actually cover a lot of trivial CVS usage already. A
lot of people probably don't need to learn about branches AT ALL, or
about concurrent development, or anything like that.
And the good news is that once you are very comfy with the two trivial
cases, it's much easier to *later* explain how those two can actually be
combined. In other words, there's probably not any reason at all to even
start to talk about merging and branches until people are actually ready
for it, and start asking you "so what happens if I've made changes and
want to update to the most recent version".
Similarly, you generally don't want to actually start serving your
projects to others until long after you've started using the thing for
development, so early on, it's probably perfectly fine to tell people:
don't worry about setting up a server or gitweb, just be happy in the
knowledge that it *can* be done, and has been done for big projects, so
when you actually want to do that, you can do all these fancy things, but
you shouldn't worry about it _yet_.
Linus
-
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