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

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/

I did this as an attempt to demonstrate that git and mercurial are fundamentally equally "easy to learn", and definitely not as an effort to try to leech Bryan's hard work, (nor would I even want to encourage that kind of thing). More of my rationale is available here:

	Git is easy to learn
	http://cworth.org/hgbook-git/

I have two reasons for sharing this with the list. First, I'd appreciate any feedback that the knowledgable readers on this list might have. If anything could be made more clear, or if I have factual mistakes in the text, I'd definitely like to fix those. Please let me know.

Second, the process of porting the document highlighted a few issues in git that I think would be nice to fix. I only noticed fairly cosmetic issues, but I included them as XXX comments in the text. I'll share them here as well: (all of these are with git 1.5.3.2).

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

 * Would it make sense to put much smaller amounts of text into "git
   help" than the entire man page? For example, maybe just the
   description and the most common options or maybe an example? Maybe
   do something like "git -v help" for more details? See my text for
   more on this, or compare "git help init" to "hg help init" and "hg
   -v help init".

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

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

  * It would be nice if all short-format options, (like "git log -p"), were
    also available in a long-format option, (like "git log --patch").

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

Obviously some of these would be pretty easy, and I should jump into the git implementation to try them out, but I've just been typing this stuff as fast as I could, and I'm about to go campout in the rain and hail now, (fun, fun!), so I wanted to get this out before I forgot anything.

Thanks in advance for any of your time, attention, or feedback, (and especially any patches!).

-Carl

[1] http://hgbook.red-bean.com/
	

Carl Worth <cworth@cworth.org> wrote:

Interesting.
 

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

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.
 

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

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.
 

Hi,

On Fri, 28 Sep 2007, Shawn O. Pearce wrote:

We open the html pages. That is, we don't yet, since we do not generate the html pages just yet; asciidoc is a Python program, and Python is not available as an MSys program as far as I know (and asciidoc insists on finding files in a Unix-like file structure, so we _do_ need an MSys Python).

... but all this would be easier if we succeeded in having a minimal asciidoc lookalike in git.git...

AFAICT git-clone is a prime candidate for builtinification, after which issues like this should be easy to address.

--pretty=fuller

Ciao, Dscho

On Sep 29, 2007, at 2:49 AM, Johannes Schindelin wrote:

I propose to clone the html pages from git.git's html branch and include them in the installer. I continue to believe that this is the simplest and fastest solution for providing html pages.

I'll provide a patch (hopefully next week).

	Steffen

Hi,

On Sat, 29 Sep 2007, Steffen Prohaska wrote:

I'm hesitant... The html branch is synced with the master branch. And we deviate from the master branch quite a lot ATM.

This will be a good temporary workaround.

Ciao, Dscho

On Sep 29, 2007, at 5:06 PM, Johannes Schindelin wrote:

We could choose a specific commit from the html branch for the WinGit release. I don't think we'll need modifications to the documentation in msysgit. Selecting an older version that matches the state of msysgit should be sufficient.

Fixes to the documentation could be committed directly to git.git.

The patch following soon will assume that html is available. Maybe we could add it as a submodule of msysgit?

I haven't looked into the submodule mechanisms and therefore will not include it in the patch. I just manually cloned the html branch. For now, this may be sufficient to create a WinGit installer.

	Steffen

/bin/start is needed to tell Windows to open html pages.

Signed-off-by: Steffen Prohaska <prohaska@zib.de>
---
 share/WinGit/release.sh |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

It is assumed that a matching version of the html documentation is available as the HEAD of /doc/git/html/.git. If not an error will be reported.

This patch doesn't include a mechanism to fetch the html pages to /doc/git/html/.git. You should manually clone them. Maybe this could handled as a submodule of msysgit?

Signed-off-by: Steffen Prohaska <prohaska@zib.de>
---
 share/WinGit/release.sh |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)

Hi,

On Sat, 29 Sep 2007, Steffen Prohaska wrote:

I'd rather handle it as in git.git, as another branch, and not check it out in /git/html/, but rather use "git read-tree --prefix=/tmp/WinGit/share/git/html origin/html", or some such.

Ciao, Dscho

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

This is starting to smell like an opportunity to use the gitlink stuff, isn't it?

Hi,

On Sat, 29 Sep 2007, Junio C Hamano wrote:

I'd agree that we could have a submodule in /doc/git/html/. This way, even users of msysGit and GitMe would benefit.

Ciao, Dscho

On Sep 30, 2007, at 1:23 AM, Johannes Schindelin wrote:

And we could completely tag a WinGit release. The version of the html docs included would be defined by the submodule's head in /doc/git/html. This is what I had in mind when submitting the patch. Maybe I didn't express this clearly.

I do not yet understand submodules sufficiently. Therefore I didn't add a patch that actually sets up the submodule in /doc/git/html. Maybe I'll do so later today.

	Steffen

On Sat, Sep 29, 2007 at 12:00:56AM +0000, Shawn O. Pearce wrote:

  I'm not sure you need the ETA thing. I've used bzr only a couple of
time, I don't think it shows any kind of ETA, but I think I remember sth
like:

Stage 3/4 [==========================> ] [43%]

  And that's all is needed. It's sober, and informative enough I think.

  Many git commands output are still messy and indeed, having them in C
should help in that regard. The usual culprit are I think:

  * git fetch/clone/pull/.. ;
  * git push ;
  * git repack/gc/... ;
  * git merge (even with the merge.verbosity set to the minimum it's
    still not very readable and confusing).

  I do believe that the quite verbose output git commands sometimes have
is quite confusing, and let the user think it's messy. I believe that
porcelains should be more silent, it's OK for the plumbing to spit
progress messages and so on, because people using the plumbing are able
to understand those, but porcelains should not.

El 29/9/2007, a las 11:01, Pierre Habouzit escribió:

I think that most people just want to know, "Did it work or not?" and so when the commands chatter too much they go into filter mode, don't really read the output, let alone try to understand it, and just skim it. Ideally Git would be much less "chattery" in general when things work, and only be more verbose when things go wrong; of course, finding that balance point is where the art lies.

Wincent

On Sun, Sep 30, 2007 at 12:45:34PM +0000, Wincent Colaiuta wrote:

  That's true for git merge that is fast. But people also want to know
the command is not stuck in an infinite loop, and for that progress bars
or little \|/- animation.

El 30/9/2007, a las 15:49, Pierre Habouzit escribió:

Yes, I agree. I probably should have said that they either want to know "*Did* it work?" for near-instant operations (most Git operations, hopefully), and "*Is* it working?" for long-running ones (network ops, for example) and in those cases you're right that a progress bar would be a nice enhancement.

Cheers, Wincent

On Sep 29, 2007, at 2:00 AM, Shawn O. Pearce wrote:

Often you know that you have a good connection and you are not interested in any progress reporting at all. _No_ output would be perfect. A return code of 0 would already tell you all you need to know. If you'd like to know more you could pass something like '--verbose' or '--progress'.

Quite often git prints a lot of very technical information that
is not very interesting as long as things succeed without error.
Some examples are
- git fetch (see above)
- git rebase: prints a lot of details that I'm not interested in
   unless the rebase fails.
- git push: prints updates of remote heads. A message about
   failing to update a remote head may get lost.
- git merge: the fact that a merge is a fast forward merge gets
   printed at the very top, followed by (often a lot of) diffstat.
   I know diffstat can help to judge if the merge did what you
   expected. But even more important is the fact that the merge
   was just a fast forward, which may get buried under lots of output.

Maybe git should become more quiet, as other unix tools are, and per default only report problems. Technical details and progress could be requested explicitly by '--verbose' or similar. We could pipe all the technical output to a per-repository logfile, which can be consulted in case of errors. The log could be cropped during 'git gc'.

	Steffen

Steffen Prohaska <prohaska@zib.de> writes:

Probably.

Yes. Most of the clutter is coming from "am" which also should be squelched.

Saying

	Switched to branch <blah>

is good when the branch to rebase is specified.

	"HEAD is now at ..."
is not useful -- it is a side effect of rewinding the head to
the --onto commit.

	<blank line>
        Applying <patch subject>
	<blank line>
        Wrote tree <tree object>
        Committed: <commit object>

are coming from "am" for each patch. We could squelch these into just one "Applying <patch subject>" and nothing else, which would also help making "am" quieter.

Please do not remove the report of successful update, as people often say "git push" or "git push $there" without explicitly saying which refs to push. When pushing out to publish, I say "git push ko" (to mean k.org) and I _want_ my positive feedback.

I do not think fast-forwardness is particularly interesting. If you find fast-forwardness interesting, I suspect you would even want to know what _your_ change that were not in the other side of the merge, which is something that we do not even report right now.

I'd agree with this sentiment in principle, and many of the things you propose to remove above fall into the "unnecessary clutter" category. But some of the existing output fall into the "necessary info" category --- diffstart after merge and report of successful remote ref updates are such things, so we should be careful not to go overboard.

On Sep 30, 2007, at 12:25 AM, Junio C Hamano wrote:

Yes but it's pretty technical.

A much simpler output could be easier to scan by a human

updating 'refs/heads/master' .. fast forward .. ok.
updating 'refs/heads/pu' .. forced non-fast forward .. ok.
updating 'refs/heads/next' ..
ERROR: 'refs/heads/next' not updating to non-fast forward
exit(1) here.

If we exit after the very first problem it can't get lost. After fixing the issue you can just 'git push' again.

I use it to advance a branch to a temporary integration branch. At that point I expect that the merge is a fast forward. Here's what I do.

    git checkout -b for/master master
    git merge branch-with-good-topics
    git branch -f scratch
    git push compileservers # pushes scratch for automatic builds

Now I wait for compiles to finish. Typically I continue not before the next morning. If everything's ok I do.

    git checkout master
    git merge for/master
    git push

The last merge must be a fast forward. This is the only fact I'm interested in. I could do 'git reset' or 'git branch -f' but then I'd loose the check if it's a fast forward.

I don't merge directly to master to avoid any accidentally push. I can also easily revert by just deleting 'for/master'.

Maybe there's a better workflow?

I agree. Could we print the note about fast forward _after_ the diffstat? Maybe there are more useful oneline information that could be output there.

But the output could be less technical and more human readable.

Also diffstat's output and "git push" are different. diffstats change with the content of your repo. "git push" just succeeds or fails. If is succeeds it updates remote refs according to your configuration. There is no new information in the output beyond success or failure [which is not quite true if you depend on git push finding matching refs automatically -- I don't]. I don't think the sha1's printed are needed by anyone. And if someone needs them, he could call push with '--verbose'.

I asked about a '--dry-run' switch to "git push" some time ago, which would only report what "git push" would do without actually changing anything on the remote side. I'd use this to check what I expect to do. Just in case I messed up my configuration. At the time "git push" is actually pushing it's too late to fix a broken configuration. I know '--dry-run' it's not trivial to implement and I'll likely have no time to look into it.

	Steffen

Steffen Prohaska <prohaska@zib.de> writes:

Last week I saw somebody (I think it was Shawn) mentioned a trick:

	git push . thisbranch:thatbranch

will moves thatbranch to thisbranch iff thisbranch is a descendant of thatbranch. So doing

	git push . for-master:master

instead of that checkout + merge command sequence would obviously be a good solution for your particular use case.

Having said that it may make sense to swap the order so that the diffstat is shown first and then a single line "Merge made by recursive" or "Updatting A..B, Fast Forward" concludes the report. At least, I do not think such a swapping would hurt the usability, although people used to the UI may first feel uneasy. I would not object to such a patch in principle.

Hi,

On Sun, 30 Sep 2007, Steffen Prohaska wrote:

No, please no.  This is way too short.

If at all, please let 8c3275abcacb83ea3f4c4f4ceb2376799fc282bd be an example, and make git respect several different output levels, but not changing the default (at first).

Ciao, Dscho

On Sep 30, 2007, at 2:44 PM, Johannes Schindelin wrote:

good idea.

	Steffen

Thanks for starting this.  It was an interesting read.

----------------------------------------------------------------

#2.2.1

"git help init" would give man page. The time when the short help is given is when you mistype options, as in:

	$ git init --huh?

#2.4

	By default this command prints a brief paragraph of output...

Not really. The default is to give you the entire log message, unless you somehow made --pretty=short the default with your copy of git.

	The "git log" tool doesn't display the Committer...

You can ask it to, so "by default" is missing.

#2.7.1

	But some poepl, (notably Linus...

typo.

#2.7.6

	for which "git commit --amend" was

was what?  "invented" perhaps?

#2.8.3

	Using "git remote" to pull changes other repositories

"changes from other repositories".

----------------------------------------------------------------

On Fri, 28 Sep 2007 17:45:30 -0700, Junio C Hamano wrote:

You're welcome. I hope it's useful for people.

The original goal was to demonstrate that git is no harder to learn than mercurial. So that attempt is done, now, (whether successful or not, I can't really judge).

Now, after getting some initial feedback, it's clear that the document could further be improved by focusing on the "git way" of doing things that aren't as natural in hg, (like multiple branches in a single repository).

Rather than extending the current document, though, I think I'll just draw up on outline based on what I think would be a good order to introduce the topics. And then I'll see what text in the current user's guide could plug into that outline, and what pieces might be missing or could be improved.

At least, that's my thoughts for now. I don't know if I'll get around to it though, (we'll have to see if I get annoyed into doing that work like I got annoyed into this first project).

Oh, and that's *really* short output. Just a summary of the command-line options and no description. If you look at "hg help" it has a middle-ground option which is little more than a brief description and a very small number of options. I think that's a useful thing to consider for "git help". Or, perhaps just carefully construct the man page so that this most important information is first. See "git help clone" for example which does have a better order than "git help init" in my opinion.

Meanwhile, "git init --huh?" is totally appropriate in just printing usage information. That's really all you want to see if you forget the exact name of a particular command-line option.

Trying a couple of random examples though, git could be better in some cases:

	$ git log --pretty=complete
	fatal: invalid --pretty format: complete

That's a fairly specific error message, but no information on what I might have meant to say. A fix should be be quite simple, (presumably there's a list of --pretty options it just looped through and it might as well print them out).

	$ git log --format=fuller
	fatal: unrecognized argument: --format=fuller

There's no usage given in this case at all. It should print some usage statement, hopefully containing --pretty. Admittedly, this one is *really* hard to fix entirely since there is a ridiculously large number of possible options to a command like "git log". But a aummary of the most common stuff should still help.

Thanks for the various typo fixes. I've implemented those, (and the things submitted by others). There were some particularly bad markup problems where "git commit <file>" was being misinterpreted and presented as "git commit" which was fairly disastrous for my intended meaning.

Hopefully it's much better now.

-Carl

On Fri, 28 Sep 2007 17:45:30 -0700, Junio C Hamano wrote:

You're welcome. I hope it's useful for people.

The original goal was to demonstrate that git is no harder to learn than mercurial. So that attempt is done, now, (whether successful or not, I can't really judge).

Now, after getting some initial feedback, it's clear that the document could further be improved by focusing on the "git way" of doing things that aren't as natural in hg, (like multiple branches in a single repository).

Rather than extending the current document, though, I think I'll just draw up on outline based on what I think would be a good order to introduce the topics. And then I'll see what text in the current user's guide could plug into that outline, and what pieces might be missing or could be improved.

At least, that's my thoughts for now. I don't know if I'll get around to it though, (we'll have to see if I get annoyed into doing that work like I got annoyed into this first project).

Oh, and that's *really* short output. Just a summary of the command-line options and no description. If you look at "hg help" it has a middle-ground option which is little more than a brief description and a very small number of options. I think that's a useful thing to consider for "git help". Or, perhaps just carefully construct the man page so that this most important information is first. See "git help clone" for example which does have a better order than "git help init" in my opinion.

Meanwhile, "git init --huh?" is totally appropriate in just printing usage information. That's really all you want to see if you forget the exact name of a particular command-line option.

Trying a couple of random examples though, git could be better in some cases:

	$ git log --pretty=complete
	fatal: invalid --pretty format: complete

That's a fairly specific error message, but no information on what I might have meant to say. A fix should be be quite simple, (presumably there's a list of --pretty options it just looped through and it might as well print them out).

	$ git log --format=fuller
	fatal: unrecognized argument: --format=fuller

There's no usage given in this case at all. It should print some usage statement, hopefully containing --pretty. Admittedly, this one is *really* hard to fix entirely since there is a ridiculously large number of possible options to a command like "git log". But a summary of the most common stuff should still help.

Thanks for the various typo fixes. I've implemented those, (and the things submitted by others). There were some particularly bad markup problems where "git commit <file>" was being misinterpreted and presented as "git commit" which was fairly disastrous for my intended meaning.

Hopefully it's much better now.

-Carl

On 9/29/07, Carl Worth <cworth@cworth.org> wrote:

Minor thing. On Gentoo you should do "emerge dev-util/git" instead of "emerge git" because there is another program with the same name.