Subject: Re: Git cheat sheet

From: Zack Rusin <[email-masked]>
Date: Wed, 29 Aug 2007 08:55:39 -0400

Thanks a lot for the comments.

On Wednesday 29 August 2007 04:11:07 am Junio C Hamano wrote:
> - Recommended form for diff between 1 and 2 is "git diff $id1
>   $id2", not dotted form "$id1..$id2"

Fixed. 

> + "git log -p $file" gives a false impression that it is about a
>   single file.  Better written as "git log -p $file $dir/ec/tory/"
>   to suggest both usage.

Fixed.

> - Although they do the same thing ("annotate" is there only for
>   backward compatibility) "git blame" is recommended over "git
>   annotate", if only because that's the command name more often
>   talked about in the community.  If you are going to list only
>   one, blame is the name to keep.

Fixed.

> + To start from a particular revision, use "git blame $version $file".

I'm not quite sure where to squeeze it though :)

> - "git reset --hard HEAD"; you do not have to write HEAD there.

The reason I left HEAD in there was because I wanted to let people know they 
can reset to any id, but come to think of it, I failed at that (and only at 
that, everything else in my life is a success... cough, cough) so I removed 
HEAD.

> - "Revert" has a specific meaning to git but people from
>   different background interpret the word differently.  Both
>   "git revert HEAD" and "git revert $id" are about creating a
>   new commit to reverse the effect of the named commit.

I added a note to let people know it creates a new commit.

> * "git pull $branch1 $branch2" is wrong.  If you are merging
>   branch1 into branch2, you need to be on branch2 (i.e. have
>   done "git checkout branch2") and then say "git merge branch1".

Ah, thanks! Fixed. 

> + "git commit" is not about publishing at all.  A major point
>   about distributed SCMs is that unlike centralized systems, the
>   act of committing is separate from the act of publishing.
>   IOW, you can make commits without having to worry about
>   publishing that to the public, and that allows you to more
>   freely experiment.

The reason I put it in publishing was because if I added another section I'd 
have to resize the font to about 2pt to fit it all which in turn would imply 
that everyone trying to read the sheet would be crosseyed (and given my 
strong support for beauty in the community, I just couldn't do that). 

> + A new section "Making Progress" and include commit, merge and
>   rebase there, perhaps?

Yeah, lack of rebase in the sheet bothers me a bit, since it's quite 
important. Maybe I could remove the "useful commands" section and put 
something in there...

Also I think that it's very important to specify what a "cheat sheet" is for. 
It's not a replacement for a tutorial. I don't think it's reasonable to 
expect anyone to print this sheet without reading any tutorials/documentation 
and be riding the Git wave. It nicely complements the tutorial, especially in 
the beginning phases of learning something new. 
So what I wanted to have on this sheet is list of thingies (technical term) 
people will use on a daily basis. In cases they need a specific permutation 
of them they can always look at the documentation.
So in my opinion (and that's a wicked good opinion) the scenario we should be 
aiming at with a cheat sheet is:
1) a person hears about Git in an online dating forum
2) a person takes a deep breath and changes pants
3) a person reads the tutorial
4) a person prints a cheat sheet and begins using Git

While I think 1 and 2 will change and are fairly optional, I think 3 
absolutely has to come before 4. 
Basically I wanted this to be a road-sign that would point people in the right 
direction (and I know that people from Brooklyn, are all confused right now 
because every roadsign they've ever seen points the wrong direction, but they 
can trust me, outside Brooklyn roadsigns actually point in the right 
direction).

I'm not sure if I should put the sheet in some more visible place, so for now 
the updated svg and png's are at:
http://ktown.kde.org/~zrusin/git/git-cheat-sheet.svg
http://ktown.kde.org/~zrusin/git/git-cheat-sheet-medium.png
http://ktown.kde.org/~zrusin/git/git-cheat-sheet-large.png

z