Git in a Nutshell guide

Git in a Nutshell guide

[Jonas Juselius]

[-- Attachment #1: Type: text/plain, Size: 1282 bytes --]

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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: Git in a Nutshell guide

[Jakub Narebski]

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
Warsaw, Poland
ShadeHawk on #git

Re: Git in a Nutshell guide

[Jonas Juselius]

Jakub Narebski <jnareb <at> gmail.com> writes:
> 
> 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.
> 

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.

Re: Git in a Nutshell guide

[Brian Downing]

On Mon, Nov 19, 2007 at 02:05:04PM +0100, Jonas Juselius wrote:
> I have also written a CVS2git transition guide, which outlines one
> possible way of converting from CVS to git.

You write:

> In order to save space you can also enable compression
> $ git config --global core.compression 1
> $ git config --global core.loosecompression 1

I think this contradicts the git-config manpage:

>  core.compression
>      An integer -1..9, indicating a default compression level. -1 is the
>      zlib default. 0 means no compression, and 1..9 are various
>      speed/size tradeoffs, 9 being slowest.

>  core.loosecompression
>      An integer -1..9, indicating the compression level for objects that
>      are not in a pack file. -1 is the zlib default. 0 means no
>      compression, and 1..9 are various speed/size tradeoffs, 9 being
>      slowest. If not set, defaults to core.compression. If that is not
>      set, defaults to 0 (best speed).

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

Re: Git in a Nutshell guide

[Brian Downing]

On Mon, Nov 19, 2007 at 09:02:09AM -0600, Brian Downing wrote:
> 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.

It's 6:

>  Z_DEFAULT_COMPRESSION requests a default compromise between speed and
>  compression (currently equivalent to level 6).

-bcd

Re: Git in a Nutshell guide

[Nicolas Pitre]

On Mon, 19 Nov 2007, Brian Downing wrote:

> On Mon, Nov 19, 2007 at 02:05:04PM +0100, Jonas Juselius wrote:
> > I have also written a CVS2git transition guide, which outlines one
> > possible way of converting from CVS to git.
> 
> You write:
> 
> > In order to save space you can also enable compression
> > $ git config --global core.compression 1
> > $ git config --global core.loosecompression 1
> 
> I think this contradicts the git-config manpage:

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

Re: Git in a Nutshell guide

[Jakub Narebski]

Jonas Juselius wrote:

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

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?).

> 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.

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?
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Git in a Nutshell guide

[Jonas Juselius]

[-- Attachment #1: Type: text/plain, Size: 896 bytes --]

On Mon, 2007-11-19 at 17:05 +0100, Jakub Narebski 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?).

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.

> 
> 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.
> 

I'll look into that :)

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

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

.j.


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: Git in a Nutshell guide

[Lars Hjemli]

On Nov 19, 2007 2:05 PM, Jonas Juselius <jonas.juselius@chem.uit.no> wrote:
> All comments
> and suggestions are welcome!

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}'

-- 
larsh

Re: Git in a Nutshell guide

[Benoit Sigoure]

[-- Attachment #1: Type: text/plain, Size: 2155 bytes --]

On Nov 19, 2007, at 5:14 PM, Jonas Juselius wrote:
> On Mon, 2007-11-19 at 17:05 +0100, Jakub Narebski wrote:
>> Do I understand correctly that you don't support cloning via git://
>> protocol?
>
> Yes, that is correct. The machine is behind a number of firewalls,  
> and I
> simply cannot be bothered to go through the bureaucracy...

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.

-- 
Benoit Sigoure aka Tsuna
EPITA Research and Development Laboratory



[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 186 bytes --]

Re: Git in a Nutshell guide

[Jonas Juselius]

[-- Attachment #1: Type: text/plain, Size: 1161 bytes --]


On Mon, 2007-11-19 at 17:45 +0100, Lars Hjemli wrote:
> 
> Very nice introduction, but I have a couple of comments.
> 
Thank you :)

> 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).
> 

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.

> 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}'
> 
This was new to me ;) I'll correct and add a note on reflogs.

.j.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: Git in a Nutshell guide

[Benoit Sigoure]

[-- Attachment #1: Type: text/plain, Size: 1876 bytes --]

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

> On Nov 19, 2007 2:05 PM, Jonas Juselius  
> <jonas.juselius@chem.uit.no> wrote:
> 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}'

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,

-- 
Benoit Sigoure aka Tsuna
EPITA Research and Development Laboratory



[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 186 bytes --]

Re: Git in a Nutshell guide

[Lars Hjemli]

On Nov 19, 2007 5:57 PM, Benoit Sigoure <tsuna@lrde.epita.fr> wrote:
> 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).

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

--
larsh

Re: Git in a Nutshell guide

[Matthieu Moy]

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

>  git reset --hard HEAD~42 and then git reset --hard A.

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 ;-).

-- 
Matthieu

Re: Git in a Nutshell guide

[Benoit Sigoure]

[-- Attachment #1: Type: text/plain, Size: 797 bytes --]

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

> On Nov 19, 2007 5:57 PM, Benoit Sigoure <tsuna@lrde.epita.fr> wrote:
>> 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).
>
> You can simply try 'git reflog', and then 'man git-reflog' ;-)

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,

-- 
Benoit Sigoure aka Tsuna
EPITA Research and Development Laboratory



[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 186 bytes --]

Re: Git in a Nutshell guide

[J. Bruce Fields]

On Mon, Nov 19, 2007 at 07:10:07PM +0100, Benoit Sigoure wrote:
> On Nov 19, 2007, at 6:04 PM, Lars Hjemli wrote:
>
>> On Nov 19, 2007 5:57 PM, Benoit Sigoure <tsuna@lrde.epita.fr> wrote:
>>> 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).
>>
>> You can simply try 'git reflog', and then 'man git-reflog' ;-)
>
> 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.

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.

Re: Git in a Nutshell guide

[Matthieu Moy]

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

> 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.

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.

-- 
Matthieu

[PATCH] Doc fix for git-reflog: mention @{...} syntax, and <ref> in synopsys.

[Matthieu Moy]

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(-)

diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index 5c7316c..aeac6f0 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -19,7 +19,7 @@ depending on the subcommand:
 git reflog expire [--dry-run] [--stale-fix] [--verbose]
 	[--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>...
 
-git reflog [show] [log-options]
+git reflog [show] [log-options] [<ref>]
 
 Reflog is a mechanism to record when the tip of branches are
 updated.  This command is to manage the information recorded in it.
@@ -32,10 +32,17 @@ directly by the end users -- instead, see gitlink:git-gc[1].
 
 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.
+`HEAD`, or of the reference provided in the command-line, which will
+cover all recent actions, including branch switches.
 It is basically an alias for 'git log -g --abbrev-commit
 --pretty=oneline', see gitlink:git-log[1].
 
+The reflog is useful in various git commands, to specify the old value
+of a reference. For example, `HEAD@\{2\}` means "where HEAD used to be
+two moves ago", `master@\{one.week.ago\}` means "where master used to
+point to one week ago", and so on. See gitlink:git-rev-parse[1] for
+more details.
+
 
 OPTIONS
 -------
-- 
1.5.3.5.724.g49d9d

Re: [PATCH] Doc fix for git-reflog: mention @{...} syntax, and <ref> in synopsys.

[Junio C Hamano]

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

> 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.

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

>  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.
> +`HEAD`, or of the reference provided in the command-line, which will
> +cover all recent actions, including branch switches.
>  It is basically an alias for 'git log -g --abbrev-commit
>  --pretty=oneline', see gitlink:git-log[1].

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.

[PATCH] Doc fix for git-reflog: mention @{...} syntax, and <ref> in synopsys.

[Matthieu Moy]

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(-)

diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index 5c7316c..aeac6f0 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -19,7 +19,7 @@ depending on the subcommand:
 git reflog expire [--dry-run] [--stale-fix] [--verbose]
 	[--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>...
 
-git reflog [show] [log-options]
+git reflog [show] [log-options] [<ref>]
 
 Reflog is a mechanism to record when the tip of branches are
 updated.  This command is to manage the information recorded in it.
@@ -32,10 +32,17 @@ directly by the end users -- instead, see gitlink:git-gc[1].
 
 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.
+`HEAD`, or of the reference provided in the command-line, which will
+cover all recent actions, including branch switches.
 It is basically an alias for 'git log -g --abbrev-commit
 --pretty=oneline', see gitlink:git-log[1].
 
+The reflog is useful in various git commands, to specify the old value
+of a reference. For example, `HEAD@\{2\}` means "where HEAD used to be
+two moves ago", `master@\{one.week.ago\}` means "where master used to
+point to one week ago", and so on. See gitlink:git-rev-parse[1] for
+more details.
+
 
 OPTIONS
 -------
-- 
1.5.3.5.724.g49d9d

Re: [PATCH] Doc fix for git-reflog: mention @{...} syntax, and <ref> in synopsys.

[Matthieu Moy]

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

> -`HEAD`, which will cover all recent actions, including branch switches.
> +`HEAD`, or of the reference provided in the command-line, which will
> +cover all recent actions, including branch switches.

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 d71c6c8e24a5a08600f3347b4ad014e459f9f3df Mon Sep 17 00:00:00 2001
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(-)

diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index 5c7316c..1bd54c5 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -19,7 +19,7 @@ depending on the subcommand:
 git reflog expire [--dry-run] [--stale-fix] [--verbose]
 	[--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>...
 
-git reflog [show] [log-options]
+git reflog [show] [log-options] [<ref>]
 
 Reflog is a mechanism to record when the tip of branches are
 updated.  This command is to manage the information recorded in it.
@@ -32,10 +32,17 @@ directly by the end users -- instead, see gitlink:git-gc[1].
 
 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.
+the reference provided in the command-line (or `HEAD`, by default).
+The log will cover all recent actions, including branch switches.
 It is basically an alias for 'git log -g --abbrev-commit
 --pretty=oneline', see gitlink:git-log[1].
 
+The reflog is useful in various git commands, to specify the old value
+of a reference. For example, `HEAD@\{2\}` means "where HEAD used to be
+two moves ago", `master@\{one.week.ago\}` means "where master used to
+point to one week ago", and so on. See gitlink:git-rev-parse[1] for
+more details.
+
 
 OPTIONS
 -------
-- 
1.5.3.5.724.g49d9d

Re: Git in a Nutshell guide

[Benoit Sigoure]

[-- Attachment #1: Type: text/plain, Size: 1188 bytes --]

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

> Benoit Sigoure <tsuna@lrde.epita.fr> writes:
>
>> 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.
>
> 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.

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 aka Tsuna
EPITA Research and Development Laboratory



[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 186 bytes --]

Re: Git in a Nutshell guide

[Matthieu Moy]

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

> 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.

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.

-- 
Matthieu

Re: Git in a Nutshell guide

[Benoit Sigoure]

[-- Attachment #1: Type: text/plain, Size: 591 bytes --]

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

> Benoit Sigoure <tsuna@lrde.epita.fr> writes:
>
>> 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.
>
> 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.

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

-- 
Benoit Sigoure aka Tsuna
EPITA Research and Development Laboratory



[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 186 bytes --]

Re: Git in a Nutshell guide

[Daniel Barkalow]

On Mon, 19 Nov 2007, Benoit Sigoure wrote:

> On Nov 19, 2007, at 5:14 PM, Jonas Juselius wrote:
> >On Mon, 2007-11-19 at 17:05 +0100, Jakub Narebski wrote:
> > >Do I understand correctly that you don't support cloning via git://
> > >protocol?
> >
> >Yes, that is correct. The machine is behind a number of firewalls, and I
> >simply cannot be bothered to go through the bureaucracy...
> 
> 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.

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*

Re: Git in a Nutshell guide

[J. Bruce Fields]

On Mon, Nov 19, 2007 at 10:51:35PM +0100, Benoit Sigoure wrote:
> On Nov 19, 2007, at 10:33 PM, Matthieu Moy wrote:
>
>> Benoit Sigoure <tsuna@lrde.epita.fr> writes:
>>
>>> 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.
>>
>> 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.
>
> By telling you to read another man page which is annoying and a recurring 
> complaint.

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.

Re: Git in a Nutshell guide

[Junio C Hamano]

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

> On Nov 19, 2007, at 10:33 PM, Matthieu Moy wrote:
>
>> Benoit Sigoure <tsuna@lrde.epita.fr> writes:
>>
>>> 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.
>>
>> 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.
>
> By telling you to read another man page which is annoying and a
> recurring complaint.

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.

Re: Git in a Nutshell guide

[Matthieu Moy]

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

> 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.

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

Re: Git in a Nutshell guide

[Junio C Hamano]

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

> 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.

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.

Re: Git in a Nutshell guide

[Jonas Juselius]

[-- Attachment #1: Type: text/plain, Size: 1648 bytes --]

On Mon, 2007-11-19 at 17:49 +0100, Benoit Sigoure wrote:
> You can create a repository on repo.or.cz then :)
I will :=)
> 
> 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.
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 ;)

> 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.
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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: Git in a Nutshell guide

[Jakub Narebski]

Benoit Sigoure wrote:

> On Nov 19, 2007, at 5:14 PM, Jonas Juselius wrote:
>> On Mon, 2007-11-19 at 17:05 +0100, Jakub Narebski wrote:
>>> Do I understand correctly that you don't support cloning via git://
>>> protocol?
>>
>> Yes, that is correct. The machine is behind a number of firewalls,  
>> and I simply cannot be bothered to go through the bureaucracy...
> 
> You can create a repository on repo.or.cz then :)

Which can then function as a mirror.

> 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 

What about "Git User's Manual"?

> 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.

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.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Git in a Nutshell guide

[Jan Hudec]

[-- Attachment #1: Type: text/plain, Size: 1800 bytes --]

On Wed, Nov 21, 2007 at 00:57:28 +0100, Jakub Narebski wrote:
> 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.

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.

>  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...

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.

>  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...

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).

-- 
						 Jan 'Bulb' Hudec <bulb@ucw.cz>

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: Git in a Nutshell guide

[Jakub Narebski]

Dnia środa 21. listopada 2007 20:45, Jan Hudec napisał:
> On Wed, Nov 21, 2007 at 00:57:28 +0100, Jakub Narebski wrote:

>>  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...

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

>>  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...
> 
> 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).

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.

-- 
Jakub Narebski
Poland

Re: Git in a Nutshell guide

[David Kågedal]

Jakub Narebski <jnareb@gmail.com> writes:

> A few comments (from what I checked so far):
>
> 1. It is "man git-checkout" (or "git checkout --help"),
>    not "man git checkout"

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

-- 
David Kågedal

Re: Git in a Nutshell guide

[Jonas Juselius]

[-- Attachment #1: Type: text/plain, Size: 1214 bytes --]

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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: Git in a Nutshell guide

[Jonathan del Strother]

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

> 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?


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?

Re: Git in a Nutshell guide

[Johannes Schindelin]

Hi,

On Thu, 22 Nov 2007, Jonas Juselius wrote:

> 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?

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

Re: Git in a Nutshell guide

[jhud7196]

> Dnia środa 21. listopada 2007 20:45, Jan Hudec napisał:
>> On Wed, Nov 21, 2007 at 00:57:28 +0100, Jakub Narebski wrote:
>
>>>  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...
>
> What I meant here that some of important documentation can be only
> found in plumbing commands man pages.

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.

>>>  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...
>>
>> 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).
>
> 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").

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.

> 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.

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>

Re: Git in a Nutshell guide

[jhud7196]

> 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?

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

--
                                              Jan Hudec <bulb@ucw.cz>

Re: Git in a Nutshell guide

[Jakub Narebski]

On Thu, 22 Nov 2007, David Kågedal wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> A few comments (from what I checked so far):
>>
>> 1. It is "man git-checkout" (or "git checkout --help"),
>>    not "man git checkout"
> 
> Or "git help checkout", which is what I usually use (for some reason).

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.

-- 
Jakub Narebski
Poland