Git Books

Git Books

[Scott Chacon]

Hey all,

I have been talked into helping write a real, paper-based book on Git
for a publisher big enough that you may even see it in your local
Borders or whatnot.  (And, it appears that Junio has been as well:
http://gitster.livejournal.com/21616.html)

So, since I'm near the beginning of this process, I was wondering if
the group had any feedback as to what might be super helpful to
include.  I mean, I have a pretty good layout and all, but if you
wanted to point me to some threads that tend to crop up in the mailing
list and IRC channel from relative newcomers that I might be able to
nip in the bud, I would like to.  I'm addressing the stuff that _I_
hear a lot, and I'm scanning the IRC logs and list for topics, but I
figured many of you must answer the same questions all the time, too.

Thanks,
Scott

Re: Git Books

[Thomas Adam]

2008/12/6 Scott Chacon <schacon@gmail.com>:
> So, since I'm near the beginning of this process, I was wondering if
> the group had any feedback as to what might be super helpful to
> include.  I mean, I have a pretty good layout and all, but if you
> wanted to point me to some threads that tend to crop up in the mailing
> list and IRC channel from relative newcomers that I might be able to
> nip in the bud, I would like to.  I'm addressing the stuff that _I_
> hear a lot, and I'm scanning the IRC logs and list for topics, but I
> figured many of you must answer the same questions all the time, too.

Perhaps you're able to share this layout?  Whilst I am not about to go
trawling through the archives, one thing I do know that comes up a
lot, isn't so much how to use git to mimick coming from another SCM,
but more workflows -- that's the big stumbling point for people using
Git.  I know I'd like to see that aspect in a Git book heavily
addressed.

-- Thomas Adam

Re: Git Books

[Christian MICHON]

On Sat, Dec 6, 2008 at 12:58 PM, Scott Chacon <schacon@gmail.com> wrote:
> Hey all,
>
> I have been talked into helping write a real, paper-based book on Git
> for a publisher big enough that you may even see it in your local
> Borders or whatnot.  (And, it appears that Junio has been as well:
> http://gitster.livejournal.com/21616.html)
>
> So, since I'm near the beginning of this process, I was wondering if
> the group had any feedback as to what might be super helpful to
> include.  I mean, I have a pretty good layout and all, but if you
> wanted to point me to some threads that tend to crop up in the mailing
> list and IRC channel from relative newcomers that I might be able to
> nip in the bud, I would like to.  I'm addressing the stuff that _I_
> hear a lot, and I'm scanning the IRC logs and list for topics, but I
> figured many of you must answer the same questions all the time, too.
>
> Thanks,
> Scott
> --

workflows, workflows, workflows...

gitconfig/aliases best practices

tips and tricks in branches (ex: parentless...) and in setting up git servers

my 3 cents :)

-- 
Christian
--
http://detaolb.sourceforge.net/, a linux distribution for Qemu with Git inside !

Re: Git Books

[Dilip M]

On Sat, Dec 6, 2008 at 5:57 PM, <christian.michon@gmail.com> wrote:
> workflows, workflows, workflows...
>
> gitconfig/aliases best practices
>
> tips and tricks in branches (ex: parentless...) and in setting up git servers

Work flows, setting up the GIT server, publishing codes,....would be
_really_ helpful to great extent....and help a lot in deploying GIT

The work flow something like...http://source.android.com/submit-patches/workflow


--
Dilip

Re: Git Books

[Jakub Narebski]

"Scott Chacon" <schacon@gmail.com> writes:

> I have been talked into helping write a real, paper-based book on Git
> for a publisher big enough that you may even see it in your local
> Borders or whatnot.  (And, it appears that Junio has been as well:
> http://gitster.livejournal.com/21616.html)
> 
> So, since I'm near the beginning of this process, I was wondering if
> the group had any feedback as to what might be super helpful to
> include.  I mean, I have a pretty good layout and all, but if you
> wanted to point me to some threads that tend to crop up in the mailing
> list and IRC channel from relative newcomers that I might be able to
> nip in the bud, I would like to.  I'm addressing the stuff that _I_
> hear a lot, and I'm scanning the IRC logs and list for topics, but I
> figured many of you must answer the same questions all the time, too.

What I really would like to see in a paper book is _diagrams_, in the
form of simple graphs (and not UML-like diagrams, of flow-control like
diagrams).  You can find them in various slides for presentations
(among others Junio's talks), and sometimes in blog posts[1], but
usually only as ASCII-diagrams[2] in git documentation.  (And the
examples in"The Git Comminity Book" I've seen so far are a bit too
complicated).

For example explaining git object model, explaining refs: local
branches, remote-tracking branches and tags, explaining pulling and
pushing, explaining merging and 3-way merge algorithm are difficult to
do without diagrams; diagrams make it much easier to understand.

Others have emphasized workflows enough...

Footnotes:
==========
[1] http://www.gnome.org/~federico/news-2008-11.html#pushing-and-pulling-with-git-1
[2] This is understandable, as while AsciiDoc format makes it quite
    good on promise to be easy to edit for non-tech users, AFAIK there
    is no such format for diagrams and pictures.  PIC and Asymptote
    nonwithstanding.
-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: Git Books

[nadim khemir]

On Saturday 06 December 2008 13.54.06 Jakub Narebski wrote:
> "Scott Chacon" <schacon@gmail.com> writes:
> > I have been talked into helping write a real, paper-based book on Git
> > ...
>
> What I really would like to see in a paper book is _diagrams_, in the
> form of simple graphs (and not UML-like diagrams, of flow-control like
> diagrams).

I was thinking about buying the pdf below. The little I can see looks like 
there are a bunch of diagrams in it.

http://peepcode.com/products/git-internals-pdf

> You can find them in various slides for presentations 
> (among others Junio's talks), and sometimes in blog posts[1], but
> usually only as ASCII-diagrams[2] in git documentation.  (And the
> examples in"The Git Comminity Book" I've seen so far are a bit too
> complicated).

I like doing my ASCII-diagrams with Asciio, unsurprizingly.


                                         ********
                                         * HEAD *
                                         ********
                                             |
                                             v
                           .-----.      .--------.
                           | tag |      | branch |
                           '-----'      '--------'
                              |              |
                              v              v
..........               ..........     ..........
. commit .<--------------. commit .<----. commit .
..........               ..........     ..........
     |                        |              |
     v                        v              v
 .------.                 .------.       .------.
 | tree |--------.--------| tree |       | tree |
 '------'        |        '------'       '------'
     |           v            |              |
     v       .------.         v              v
 .------.    | blob |     .------.       .------.
 | tree |--. '------'  .--| tree |       | blob |
 '------'  |           |  '------'       '------'
           '-----.-----'      |
                 |            v
                 v        .------.
             .------.     | tree |
             | blob |     '------'
             '------'         |
                              v
                          .------.
                          | blob |
                          '------'

cheers, Nadim.

Re: Git Books

[Paolo Ciarrocchi]

On 12/6/08, Scott Chacon <schacon@gmail.com> wrote:
> Hey all,
>
> I have been talked into helping write a real, paper-based book on Git
> for a publisher big enough that you may even see it in your local

> Borders or whatnot.  (And, it appears that Junio has been as well:
> http://gitster.livejournal.com/21616.html)
>
> So, since I'm near the beginning of this process, I was wondering if
> the group had any feedback as to what might be super helpful to
> include.  I mean, I have a pretty good layout and all, but if you
> wanted to point me to some threads that tend to crop up in the mailing
> list and IRC channel from relative newcomers that I might be able to
> nip in the bud, I would like to.  I'm addressing the stuff that _I_
> hear a lot, and I'm scanning the IRC logs and list for topics, but I
> figured many of you must answer the same questions all the time, too.

Please spend lot of words about fetch and pull. These are the most
hard to ùnderstand commands for people that are used to cvs and svn.

Btw, i would love to see a git in a nutshell book in my native
language (italian).
I'm willing to help writing and translating.


Ciao,
-- 
Paolo
http://paolo.ciarrocchi.googlepages.com/
http://mypage.vodafone.it/

Re: Git Books

[Björn Steinbrink]

On 2008.12.06 03:58:28 -0800, Scott Chacon wrote:
> So, since I'm near the beginning of this process, I was wondering if
> the group had any feedback as to what might be super helpful to
> include.  I mean, I have a pretty good layout and all, but if you
> wanted to point me to some threads that tend to crop up in the mailing
> list and IRC channel from relative newcomers that I might be able to
> nip in the bud, I would like to.  I'm addressing the stuff that _I_
> hear a lot, and I'm scanning the IRC logs and list for topics, but I
> figured many of you must answer the same questions all the time, too.

Just some random thoughts:

Please explain HEAD early on, and what it actually means. I've seen
quite a number of people understanding HEAD as, for example, a magic
keyword, a branch property, or a _direct_ reference to the latest commit
on the branch they have checked out. Especially the last one has really
confused the hell out of some people when they came across the concept
of a detached HEAD.

Explaining remote tracking branches early on, say after the first
"clone" is also important I guess. A number of readers will probably
just "dive in" when they learned a few commands and clone some random
repo to start playing. Unless Murphy lets us down, they'll clone a repo
that has multiple branches and will sit there, wondering how to get one
of the branches that only exist as remote tracking branches in their
repo.

And for commands, it's IMHO best to always start with the "full blown"
form, and only then, after introducing the command and what it does,
start to talk about short forms and how you can leave out some arguments
and fall back to defaults.

For example:

rebase:
Start with "rebase --onto <onto> <upstream> <branch>" and how that takes
the commits from <upstream>..<branch> and "replays" them on top of
<onto>. In my experience, starting with that version and showing how it
affects the commit DAG helps people to actually understand what happens,
while a plain "git rebase master" seems like pure magic to some, because
you can't even use the arguments to explain why and where things are
placed, or you start telling how those are all defaults, and then have
to explain everything all over again, when you use the explicit form for
more complicated things and people seem to get confused by that.

fetch:
Include refspecs in the first examples and show how a missing rhs causes
the fetched stuff to be stored in FETCH_HEAD. And only then go on to
tell that remotes usually have a default refspec in their config, and
that you can thus omit the refspecs when you fetch from a remote.

push:
refspecs again. Maybe start with pushing a single branch/tag/whatever,
explicitly, eg. "git push origin refs/heads/master:refs/heads/master",
and only then introduce the DWIM stuff like "git push origin master".
Same thing for the default ":" refspec, please mention what that refspec
means and that it is the default when no refspec is given (either on the
command line or in the config). A lot of people don't seem to know about
refspecs at all, and the "matching branch names" refspec is IMHO worth
being mentioned, as I've seen a bunch of questions lately that could be
answered by explaining that. For example, updating matching branches and
pushing a new tag at once, or having a push config that pushes one or
more branches to differently named branches on the remote, but using the
name matching for all other. And personally, I also like "git push
origin : v1.2.3" better than pushing twice or naming my branches
explicitly :-)

Björn

Re: Git Books

[Deskin Miller]

On 2008.12.06 03:58:28 -0800, Scott Chacon wrote:
> So, since I'm near the beginning of this process, I was wondering if
> the group had any feedback as to what might be super helpful to
> include.  I mean, I have a pretty good layout and all, but if you
> wanted to point me to some threads that tend to crop up in the mailing
> list and IRC channel from relative newcomers that I might be able to
> nip in the bud, I would like to.  I'm addressing the stuff that _I_
> hear a lot, and I'm scanning the IRC logs and list for topics, but I
> figured many of you must answer the same questions all the time, too.

I agree with pretty much all of the other suggestions made thus far.
One I'd vote for is to explain why pushing to a non-bare repository
doesn't magically update the working tree as well; I'd say it's easily
one of the most repeated questions on #git.

I also vote for addressing workflows heavily.  Also, I think a reference
section akin to Tv's 'Git for Computer Scientists' page[1] would be
handy; I find understanding how git represents the project to inform
almost every interesting question about how to accomplish one's goals in
a particular situation.

Deskin Miller

[1] http://eagain.net/articles/git-for-computer-scientists/