Re: A tour of git: the basics (and notes on some unfriendly messages)

["Shawn O. Pearce" <spearce@spearce.org>]

Carl Worth <cworth@cworth.org> wrote:
> I recently "ported" the introductory chapter of Bryan O’Sullivan's
> Distributed revision control with Mercurial[1] from mercurial to
> git. The result is here:
> 
> 	A tour of git: the basics
> 	http://cworth.org/hgbook-git/tour/

Interesting.
 
>  * Is "git help" actually a builtin thing or just a way to call out to
>    "man"? Does it work at all in Windows ports of git, for example?
>    (OK, so that one's just a question, not an issue it git)

`git help` with no arguments displays a message compiled into git.
`git help init` runs `man git-init`.  If you don't have any manual
pages installed, or if they aren't available to your man installation
then it fails with "No manual entry for git-init" or whatever your
local man implementation dumps.

Brett Schwartz started an asciidoc viewer for Tcl/Tk that I am still
playing around with and trying to get working right in git-gui.
In theory one could use that to display the manual right from the
asciidoc files, thus bypassing the need for asciidoc and xmlto.

On Cygwin we have man, so `git help init` (or `git init --help`) work
just fine to display the manual entry.  No idea about the MSYS port.
 
>   * The output from a git-clone operating locally is really confusing:
> 
> 	$ git clone hello hello-clone
> 	Initialized empty Git repository in /tmp/hello-clone/.git/
> 	0 blocks
> 
>     Empty? Didn't I just clone it? What does "0 blocks" mean?

Yea.  That's because we realized its on the local disk and used
`cpio` with hardlinks to copy the files.  So cpio says it copied
0 blocks as it actually just hardlinked everything for you.  No
data was actually copied.

git-gui's new clone UI uses fancy progress meters here and tries
to shield the user from "plumbing and UNIX tools" spitting out
seemingly nonsense messages.  We probably should try harder in
git-clone to do the same here.
 
>   * git-log by default displays "Date" that is the author date, but
>     also only uses committer date for options such as --since. This is
>     confusing.

I've never thought about that.  But when you say it I think its very
obvious that it could be confusing to a new user.  Maybe we should
show the committer line and its date if it doesn't match the author
name/date.  Usually I don't care who committed a change in git.git
(its a very small handful of people that Junio pulls from directly)
but at day-job committer name is usually just as interesting as
the author name *when they aren't the same*.

>   * There's a ton of extraneous output from git-fetch. I would love to
>     see it reduced to a single-line progress bar, (even if a
>     multiple-staged progress bar). I'm imagining a final line
>     something like:
> 
> 	Computing (100%) Transferring (100%)
> 
>     But you can imagine more accurate words than those, (I'm not even
>     sure what all of the things mean that git-fetch is currently
>     reporting progress on).

Yea.  About half of that output is from pack-objects and either
unpack-objects or index-pack.  The other part is from git-fetch
itself as it updates the local tracking branches (if any are to be
updated).  Now that git-fetch is in C and reasonably stable maybe
I can look into making this prettier.  Few people really grok the
pack-objects/index-pack output, nor do they care.  They just want
to know two things:

  - Is git working or frozen in limbo?
  - Is git frozen because my network sucks, or git sucks?
  - When will this be done?  Please $DIETY, I want to go home!
    Make the fetch finish!

The C based git-fetch made the http protocol almost totally silent.
(No more got/walk messages.)  But that's actually also bad as it
now doesn't even let you know its transferring anything at all.

There are serious issues here about getting the user the progress
they really want.  The last item ("When will this be done?") is
actually not possible to determine under either the native git
protocol or HTTP/FTP.  We have no idea up front how much data must
be transferred.  In the native git case we do know how many objects,
but we don't know how many bytes that will be.  It could be under
a kilobyte in one project.  That same object count for a different
set of objects fetch could be 500M.  Radically different transfer
times would be required.
 
-- 
Shawn.