Re: best git practices, was Re: Git User's Survey 2007 unfinishedsummary continued

On Wed, 2007-10-24 at 23:14 +0100, Johannes Schindelin wrote:

[snip]

This is a *very* powerful concept. Unfortunately, it is not 100% clear in the documentation, at least not when you are reading about fetch/merge/pull initially.

After reading the user's manual, I just could not understand what "fetch" does, and therefore "merge" and "pull" did not make sense. I could not understand where Git stored the new changes from upstream while also keeping my working directory in the same state it was. After 10 years of using CVS/SVN, the assumption you have is, "whenever I get changes from the remote repository, they will be visible in my working copy (and merge conflicts are a fact of life)".

Some time later, I ran into "Git for computer scientists" and then finally I got it, thanks to the nice diagrams and explanation. I realized how powerful a concept "fetch" is: THIS is the right way to examine what upstream worked on while you did your own local work.

Once you understand what's going on, however, it is not obvious how to *visualize* the state of things after you do "git fetch". Probably "gitk --all" is the correct way to do it, but the presentation is not ideal --- you have to hunt down the list of commits until you find your own "master" (or whatever branch), and *there* is where you can say, "oh, this is where we diverged; now let's see what I'll get when I rebase later".

So, a few problems so far, with possible solutions:

* The docs do not make it easy to understand what git-fetch does.  Can
we just cut&paste most of "Git for computer scientists" into the Git
user's manual?).

* It's not obvious how to visualize the state after git-fetch, i.e.
"gitk --all" is not the first thing that occurs to you.  Maybe git-fetch
should suggest you to run "gitk --all" when your remotes get changes, so
that you can see what's going on?

* It's hard to find the "divergence point" in gitk's display, since you
have to scroll down the reverse-chronological list of commits until you
find your local refs and where they started diverging.  Would there be a
way to "flatten" the display a bit, so your local stuff is always easy
to find, and yet it's easy to see what the remote changes were?

.. And after I understood what "fetch" does, "rebase" became obvious, and *this* is where I started loving Git. I understood that in the past all I had been doing with CVS was to rebase by hand; that is where I said "Git is such a powerful tool".

It's a matter of perception. CVS requires *less* steps, even if you do more manual work. To commit something, you need to

  cvs update
  <resolve conflicts by hand - they are a fact of life, remember?>
  cvs commit

Whereas with Git you need

  git fetch
  git rebase <huh, what was the name of the remote branch?>
  <fix conflicts>
  git commit
  git push

[Maybe that's not 100% the right sequence, but you know what I mean.]

So your perception is that you have to fiddle more with Git (look up the remote branch name, invoke more git commands), even if Git saved you a lot of work when rebasing.

When you start using a complex tool like CVS or Git, you do it by voodoo: you learn sequences of commands, but you don't really understand what they do. If one tool makes you use less comands, it is perceived as simpler and more powerful ("because the other one needs more babysitting").

So, Git needs to make it very clear from the beginning (in the user's manual or the distilled tutorials) that it has *very powerful* concepts at your disposal. It needs to *teach you* how it will save you a lot of work when compared to traditional tools like CVS.

  Federico