Re: GIT vs Other: Need argument

On Thu, 19 Apr 2007, Marcin Kasperski wrote:

quoted

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