Git in a Nutshell guide

Hi everybody,

I have been involved in a somewhat painful process of trying to convert a bunch of scientific programmers from being CVS users to becoming git users. In this process I ended up writing a sort of git in a nutshell guide for non-technical users. It struck me that this might be of interest to others as well. I'm not a grand git wizard myself, so the guide is probably not entirely correct in every respect. All comments and suggestions are welcome! I have also written a CVS2git transition guide, which outlines one possible way of converting from CVS to git. This guide has some overlap with the Git in a Nutshell guide, since I started with the CVS2git guide and then realised it was not quite enough. It would probably be a good idea to slim down the CVS2git guide, and move some of the discussion to the Nushell guide instead. Let me know what you think. Both guides still need quite a bit of polishing, but I hope they can be useful and interesting in the crusade against CVS/SVN ;)If you think the guides could benefit other users, they could maybe be posted (or at least linked) on the git site.

The guides, including the LaTeX source, are available via gitweb: http://git.jonas.iki.fi/gitweb.cgi?p=git_guides.git;a=summary

.jonas.

A few comments (from what I checked so far):

1. It is "man git-checkout" (or "git checkout --help"),
   not "man git checkout"

2. Instead of using 'verbatim' environment directly to show example CLI
   session it would be I think better to define verbatim-like environment
   for this ('example', 'commands', 'CLI', 'session'); perhaps replacing
   verbatim by lstlisting from the listings/lstlisting package for syntax
   highlighting.

I'll send more comments after reading it in full...

Jakub Narebski <jnareb <at> gmail.com> writes:

First, it seems that it was not entirely clear to everybody that it's possible to clone the repository:

git clone http://git.jonas.iki.fi/git_guides.git

Thanks for the comments: 

1. I did a global subst from the git-command to git
command instead form, and forgot about the man pages ;)

2. You are entirely right of course, but I was a bit lazy. I'll fix it at some
point. lstlistings is a very nice package.

Jakub Narebski <jnareb@gmail.com> writes:

Or "git help checkout", which is what I usually use (for some reason).

On Thu, 22 Nov 2007, David Kågedal wrote:

Or, at least for now "git checkout --help", which requires only adding "--help" at the end. At least for now because some commands return short summary for "--help" and I think it is considered that it should be done that way for all porcelain commands.

On Mon, Nov 19, 2007 at 02:05:04PM +0100, Jonas Juselius wrote:

You write:

I think this contradicts the git-config manpage:

The default, -1, is the zlib default, which is probably something like 3-6. Setting these to 1 will probably result in less compression, not more.

-bcd

On Mon, Nov 19, 2007 at 09:02:09AM -0600, Brian Downing wrote:

It's 6:

-bcd

On Mon, 19 Nov 2007, Brian Downing wrote:

Also, compression is always enabled by default with the adequate setting for most usages anyway, so I think it is probably best not to talk about those settings at all in a nutshell guide.

Nicolas

Jonas Juselius wrote:

By the way, the description of this repository (for gitweb) is "CVS to git migration guide", the same as for CVS2git.git (shouldn't it be CVS2git_guide.git?).

Thanks.

Perhaps you should have make gitweb.cgi with 
  GITWEB_BASE_URL="http://git.jonas.iki.fi"
then, or configure @git_base_url_list in gitweb_config.perl.

Do I understand correctly that you don't support cloning via git:// protocol?

On Mon, 2007-11-19 at 17:05 +0100, Jakub Narebski wrote:

Well, it's the same repository. When I started out, I only planned to write the CVS2git manual. Then I wrote the Nutshell guide, and changed the name of the repo, but I had already given the link to a bunch of people so I kept the link.

I'll look into that :)

Yes, that is correct. The machine is behind a number of firewalls, and I simply cannot be bothered to go through the bureaucracy...

.j.

On Nov 19, 2007, at 5:14 PM, Jonas Juselius wrote:

You can create a repository on repo.or.cz then :)

As it is often the case different people happen to work on similar things without knowing each other. I started http://repo.or.cz/w/ tutorial.git which is meant to be a big Beamer presentation that presents Git thoroughly. I wrote some ideas but didn't start to write the slides. Just in case you want to have a look.

One of the things you said in your guide is that Git is easy to learn. I think this is wrong. Git is way more complicated than most other SCMs, especially compared to SVN. Its documentation is far behind, compared to what other SCMs have. There is no real user guide and the man pages are incomplete, at best. I know saying this is a bit harsh, especially to the people out there that are working and sending patches to improve the documentation, but I think we have to admit that it's true, even though Git is making progress on this aspect.

What I hope to achieve, when I'll have time to write my slides, is to have some sort of equivalent of the wonderful Autotools tutorial (http://www-src.lip6.fr/homepages/Alexandre.Duret-Lutz/ autotools.html) which is definitely the only thing you need to read when you want to learn the Autotools (which are also quite complicated, let's admit it).

Please don't flame me by saying that Git isn't hard to use and everything. It's the typical reaction of people who know how the things work. Git is pretty simple to use once you know how it works. But compared to SVN (for instance) it's hard to learn. People have to change the way they work to take all the benefits of Git, and to do this, they have to understand why that new way of working differently is better for them.

On Mon, 19 Nov 2007, Benoit Sigoure wrote:

I convinced my little company to switch to git (from arch, so take this with a grain of salt). I'd previously written a document explaining how to use arch, and I wrote a version for git, which said practically nothing, because everything I'd been able to do in arch is trivial to do in git. But I used the same format, anyway, to be sure to cover everything. I also told them to ask me if they were trying to do something and couldn't. I believe that all of the questions I've gotten were on how to use "advanced features" (i.e., things not included in my document because I never figured out how to do them with arch and decided to just live without), and people are using git successfully.

The main difference I see is that "save" and "publish" are separate operations with git and the same with other SCMs, but the separate concepts are obvious to anybody who's emailled a word processor document to somebody, and the distinction just has to be mentioned.

The challenge in writing a good introduction to git is leaving out explanations of all of the wonderful things that git can do that people don't expect to be within the abilities of an SCM. If you limit yourself to saying how to do things that SCMs can traditionally do, and therefore only explain how to do what people know they want to do, it's not to hard for people to learn. Of course, that's not enough to make good use of git, but it's enough to declare a transition from SVN or CVS successful.

I personally think it would be worth having a pair of documents, with the first being "everything you need to know", and the second being "things you'll find helpful that aren't strictly necessary".

	-Daniel
*This .sig left intentionally blank*

On Mon, 2007-11-19 at 17:49 +0100, Benoit Sigoure wrote:

I will :=)

Thanks, there are certainly some things in that document that I ought to consider incorporating in the guide. But for now I'll let it rest for a little while, because I don't have time to mess with it. Patches are always welcome ;)

Well, you are right to some extent. But it's this gap I would like to fill with the nutshell guide. The "for normal people" slogan is meant to refer to non-technical developers (like scientists). I should probably include a little section in the intro describing distributed vs. centralised SCMs in general.

Thanks for the input,

.jonas.

Benoit Sigoure wrote:

Which can then function as a mirror.

What about "Git User's Manual"?

That's sadly true, and confirmed (somewhat) by the fact that both in 2006 user's survey and in 2007 survey (see Git Wiki for summaries) one of more common requests are for "better documentation" and "The Git Book" (showing svnbook and hgbook as examples).

[cut]

I think that writing proper "Git Guide" aka "The Git Book" is hard because of some things:

 1. Git has many useful advanced features. Describing those advanced
    features is not easy. For example git uses multiple branches in single
    repository paradigm freely, which makes learning curve a bit steeper;
    IIRC hgbook describes one branch per repos situation (at least at
    beginning), which is easier.

 2. Git has some historical cruft, including the fact that it began as
    series of low level tools (plumbing) and became proper SCM (acquired
    proper porcelain) later, what can be even now seen in documentation...

 3. Explanation of some features (like object model) would be much easier
    with some graphics (diagrams etc.), but chosen documentation format,
    AsciiDoc, doesn't make it easy...

Yust my 2 eurocents.

On Wed, Nov 21, 2007 at 00:57:28 +0100, Jakub Narebski wrote:

I think I saw the "sharp curve" and "double sharp curve" paragraphs in other places besides the the TeXbook. I even have an impression (without actually looking) that it was documentation of some version control system.

That deals with difficult to read, but it does make it more difficult to write.

Most plumbing can be safely ignored through most of the book or covered by those "double sharp curve" paragraphs. It unfortunately does make it harder to write, because the author has to consider what to cover and what to hide.

I dare to disagree here. Asciidoc supports generating image tags for respective output formats and it really does not look hard. We could have PNGs and if we wanted higher press quality even SVG or EPS and convert them to PNGs for the HTML version (and use EPS for latex output).

Dnia środa 21. listopada 2007 20:45, Jan Hudec napisał:

What I meant here that some of important documentation can be only found in plumbing commands man pages.

The problem is that 1) language used to generate images must be easy to understand and readable in text form (so sources are enough to understand); 2) one of the main formats is manpage (although that would not matter for "Git Guide" / "The Git Book").

Should we choose PIC? Or perhaps DOT? I can write little MetaPost, but I don't think that would be good format for git diagrams, even if it can be converted to PDF, SVG and PNG.

Yes, that's true. And does indeed make /writing/ the book harder, because the information is harder to compile. Fortunately it should not make it so much harder to read.

Ad 1), I don't think we have to generate the images. For most images it is easier to just draw them in a vector image editor.

As you say, 2) does not matter for "Git Guide"/"The Git Book". The man pages will have to do without graphics or with Ascii-art replacements.

I'd use DOT for things that can be done with it (ie. visualizing histories) and just hand-draw the rest in SVG (prefered) or PNG (for illustrations).

--
                                               Jan Hudec <bulb@ucw.cz>

I'm planning to write a section in the "Nutshell guide" on rewriting history and rebasing. I have a question related to rewriting history. As usual, I'll assume that the part of the history I'm mucking with has not been pushed or pulled by anyone. Suppose I have been working on some topic branch for a while and been overly trigger happy, i.e. I have produced a ridiculous number of commits along the way. At some point when I'm done I want to publish my changes, but doing so would create an insanely obese history full of near nonsense commits. What I want to do is to slim down the commit log into pieces that actually makes sense. What is the preferred (or best, most convenient) way of doing this? The way I have done this previously is essentially:

1.  git branch -m mytopic tmp_mytopic  # rename
2.  git branch mytopci tmp_mytpoic~42  # go back in history
Loop:
3.1 git log; git diff; git annotate...
3.2 git diff tmp_mytopic~42..tmp_mytopic~33 | git-apply
3.3 git commit -m "sane commit message" -a
4.  git branch -d tmp_mytopic

If I need to reorder commits I can first use git-rebase -i to get everything streamlined. There must be a better way of doing this, right?

.jonas.

On 22 Nov 2007, at 13:15, Jonas Juselius wrote:

I may be missing something here, but you know that you can edit commits and squash commits together (using something like "git rebase --interactive mytopic~42"), right?

Hi,

On Thu, 22 Nov 2007, Jonas Juselius wrote:

Yes, you can squash commits into previous commits with rebase -i. Just replace the second "pick" command (and if you want to squash more than two, the later commands, too) with "squash".

Hth, Dscho

IIRC rebase -i is also capable of merging the commits. So you can use it for the whole thing.

--
                                              Jan Hudec <bulb@ucw.cz>

On Nov 19, 2007 2:05 PM, Jonas Juselius <jonas.juselius@chem.uit.no> wrote:

Very nice introduction, but I have a couple of comments.

In "Specifying revisions" you say that '^' and '~' are equal, but that is not true. ^ is used to select the first parent of a commit, ^2 selects the second parent of a merge commit (and ^3 selects the third parent of an octopus merge), while the '~' is used to go back any number of generations, following the first parents of each commit (~ selects the first parent, ~2 selects the first grand-parent etc).

Also, I think you might scare users away from 'git reset':

  git reset resets the branch to a specified state invisibly and
  without possibility to go back. Ever. Your call.

That's not true, since any "modern" git has reflogs enabled. If you do 'git reset --hard HEAD^^^' and then realize it was a mistake you can just 'git reset --hard HEAD@{1}'

On Mon, 2007-11-19 at 17:45 +0100, Lars Hjemli wrote:

Thank you :)

Thanks for the the clarification. I've never done an octopus, so I simply ignored the matter. I'll correct the text and add a footnote.

This was new to me ;) I'll correct and add a note on reflogs.

.j.

On Nov 19, 2007, at 5:45 PM, Lars Hjemli wrote:

Yes, I've always been very scared of git-reset until I had a somewhat better understanding of Git internals. In fact the only danger of `git reset --hard' is that you loose dirty changes (not yet in the index) and staged changes (in the index). git-reset will never, ever delete objects from your repo. Thus, you can perfectly well remember the current revision sha1 (let's call it `A') and then git reset -- hard HEAD~42 and then git reset --hard A. In between the two Git commands, it's possible that all the objects of the history from HEAD~42..A be unreachable. Nothing wrong with this, it just that if run, say, git gc --prune (note the --prune) you will loose them.

Understanding this is very important because ``error humanum est'', and people happen to screw up their hard work and they don't realize that they can go back without even knowing what the hell the reflog is or how to use it (I personally don't know -- but I'd like to, give me pointers please :D). For instance, I once rebased a dozen of commits on a given branch and I realised that I completely screwed my nice patch series by collapsing changes, introducing changes at the wrong revision etc. I could start over again by simply doing a git reset --hard <HEAD_sha1_before_rebase>.

Cheers,

On Nov 19, 2007 5:57 PM, Benoit Sigoure <tsuna@lrde.epita.fr> wrote:

You can simply try 'git reflog', and then 'man git-reflog' ;-)

-- larsh

On Nov 19, 2007, at 6:04 PM, Lars Hjemli wrote:

Did you only read the man? It doesn't explain how to use the reflog or I must have a very hard time understanding it. I don't know where the HEAD@{N} syntax is documented, but surely not in man git-reflog.

Cheers,

On Mon, Nov 19, 2007 at 07:10:07PM +0100, Benoit Sigoure wrote:

My copy at least has this paragraph:

	The subcommand "show" (which is also the default, in the absence of any
       subcommands) will take all the normal log options, and show the log of
       HEAD, which will cover all recent actions, including branch switches.
       It is basically an alias for git log -g --abbrev-commit
       --pretty=oneline, see git-log(1).

But, yeah, HEAD@{N} isn't documented there or in git-log(1), it's in git-rev-parse(1). I agree that the git-reflog manpage should at least reference all of this, as it's the obvious first place people will go to learn about reflogs....

--b.

Benoit Sigoure <tsuna@lrde.epita.fr> writes:

http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html

I'll post a patch adding a link to that in the reflog man page.

The HEAD@{...} syntax was documented in git-rev-parse manpage, which is hard to find by someone looking for the documentation of porcelain. git-reflog is probably the place where one expects to find this.

While I'm there, "git revlog show whatever" was also undocumented.
---
 Documentation/git-reflog.txt |   11 +++++++++--
 1 files changed, 9 insertions(+), 2 deletions(-)

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

Thanks.  The new HEAD@{N} description is concise and nice.

But the wording added with "While I'm there" change seems wrong to me. "..., which will cover all recent actions" is about the reflog attached to HEAD but the new phrase inserted in the middle makes it unclear.

The HEAD@{...} syntax was documented in git-rev-parse manpage, which is hard to find by someone looking for the documentation of porcelain. git-reflog is probably the place where one expects to find this.

While I'm there, "git revlog show whatever" was also undocumented.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-reflog.txt |   11 +++++++++--
 1 files changed, 9 insertions(+), 2 deletions(-)

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

Ooops, appologize. I didn't commit my change, this patch isn't any better than the previous.

The one below should be correct (the sentence was getting long, I've splitted it):

From: Matthieu Moy <Matthieu.Moy@imag.fr>
Date: Mon, 19 Nov 2007 19:25:11 +0100
Subject: [PATCH] Doc fix for git-reflog: mention @{...} syntax, and <ref> in synopsys.

The HEAD@{...} syntax was documented in git-rev-parse manpage, which is hard to find by someone looking for the documentation of porcelain. git-reflog is probably the place where one expects to find this.

While I'm there, "git revlog show whatever" was also undocumented.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-reflog.txt |   11 +++++++++--
 1 files changed, 9 insertions(+), 2 deletions(-)

On Nov 19, 2007, at 7:13 PM, Matthieu Moy wrote:

No please stop adding links from on man page to another. If you read man git-reflog, you surely want to learn the HEAD@{N} syntax and see practical uses cases. One of the complaints against Git (which also came up in the Git Users' Survey) is that man pages are harder to use because they often refer to each other and they tend to list their numerous arguments out of order. Many arguments are clearly plumbing and should be mentioned in a different section (I guess it would be better to list the most useful arguments in alphabetical order first and then list the remaining arguments in another section, still in alphabetical order).

Benoit Sigoure <tsuna@lrde.epita.fr> writes:

I don't understand your point.

Yes, if I read man git-reflog, I do surely want to learn HEAD@{N} syntax, but that is _precisely_ what my patch does.

On Nov 19, 2007, at 10:33 PM, Matthieu Moy wrote:

By telling you to read another man page which is annoying and a recurring complaint.

On Mon, Nov 19, 2007 at 10:51:35PM +0100, Benoit Sigoure wrote:

Are we looking at the same patch? It both gives examples of the syntax *and* refers to another page. I thought it was the lack of the former, rather than the presence of the latter, that was the recurring complaint....

--b.

Benoit Sigoure <tsuna@lrde.epita.fr> writes:

Which is a valid point. We could move that part into a separate source file and include it from different places appropriately, just we have done for the common diff options.

However, you need to think about what's appropriate. Any command that potentially takes a ref as (one of) its parameter? That means almost everybody.

I think the ref naming syntax is so commonly used and fundamental that we could treat it as prerequiste for individual manual pages. Maybe move the section to git(7)? That would certainly be better than having it in git-rev-parse(1), but does not reduce the cross referencing complaints.

Junio C Hamano <gitster@pobox.com> writes:

Well, obviously, something which isn't addressed by my patch is the fact that some of the documentation an average user needs is in the plumbing man pages.

(Gosh, I was going to cite the manpage for git-log and git-rev-parse as an example, but it has already been fixed :-). Good job !)

git-rev-parse(1) is full of terribly usefull information, and that information is definitely not in the place an average user would look at.

I have no ideal solution for that. git(7) is already really long. Perhaps some "topic man pages" would be good. By "topic man page", I mean "man git-something" where "something" isn't a git command, but a crosscutting concept. For example, here, "man git-refspec" to document reference specifiers like HEAD@{42}, master~55, d71c6c8e24a and friends. "man git-i18n" would be another candidate.

Anyway, my patch is definitely a step forward, even if it's just the first, small one ;-).

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

Yeah, gitattributes(5), gitignore(5) and gitmodules(5) can take advantage of the fact that they define file formats and describe the underlying concepts in their own corner while describing the file format. But there are many other things (e.g. syntax for refspec, ref naming) that would benefit from having their own topic-centric documents, without defining their own file format, so git-refspec(5) trick is not an option for them.

Benoit Sigoure <tsuna@lrde.epita.fr> writes:

And if you don't "remember" A, the reflog is here for you.

$ git reflog show HEAD
$ git reset --hard HEAD@{42} # not "the 42th ancestor"
                             # but "where HEAD was 42 moves ago".

By default, the reflog will expire after IIRC, 3 months, and git-prune will not prune the objects while they are reachable.

So, it's even safer than you say ;-).