I recently "ported" the introductory chapter of Bryan O=E2=80=99Sullivan'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 ...
[ message continues ]

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

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

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































































-

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

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 ar...
[ message continues ]

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

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 ar...
[ message continues ]

`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

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

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

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 $DI...
[ message continues ]

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
-

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

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

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

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

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.

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


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

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 rem...
[ message continues ]

Hi,


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
-

good idea.

	Steffen

-

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

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
[=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D>                                    ] [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.

--=20
=C2=B7O=C2=B7  Pierre Habouzit
=C2=B7=C2=B7O                                                madcoder@debia=
n.org
OOO                                                http://www.madism.org

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

-

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.

--=20
=C2=B7O=C2=B7  Pierre Habouzit
=C2=B7=C2=B7O                                                madcoder@debia=
n.org
OOO                                                http://www.madism.org

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

-

Hi,


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 

AFAICT git-clone is a prime candidate for builtinification, after which 

--pretty=fuller

Ciao,
Dscho

-

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,


I'm hesitant... The html branch is synced with the master branch.  And we 

This will be a good temporary workaround.

Ciao,
Dscho

-

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.


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

diff --git a/share/WinGit/release.sh b/share/WinGit/release.sh
index 67d0725..5ab876a 100644
--- a/share/WinGit/release.sh
+++ b/share/WinGit/release.sh
@@ -29,7 +29,7 @@ ls.exe,md5sum.exe,mkdir.exe,msys-1.0.dll,msysltdl-3.dll,mv.exe,patch.exe,\
 patch.exe.manifest,perl.exe,printf,ps.exe,pwd,rm.exe,rmdir.exe,rxvt.exe,\
 scp.exe,sed.exe,sh.exe,sleep.exe,sort.exe,split.exe,ssh-agent.exe,ssh.exe,\
 tail.exe,tar.exe,tee.exe,touch.exe,tr.exe,true.exe,uname.exe,uniq.exe,vi,\
-vim.exe,wc.exe,which,xargs.exe,ssh-add.exe} lib/perl5/ share/git* share/vim) |
+vim.exe,wc.exe,which,xargs.exe,ssh-add.exe,start} lib/perl5/ share/git* share/vim) |
 tar xvf - &&
 mkdir lib/perl5/site_perl &&
 cp /lib/{Error.pm,Git.pm} lib/perl5/site_perl/ &&
-- 
1.5.3.mingw.1.3.g195850

-

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

diff --git a/share/WinGit/release.sh b/share/WinGit/release.sh
index 5ab876a..8a3c197 100644
--- a/share/WinGit/release.sh
+++ b/share/WinGit/release.sh
@@ -5,6 +5,8 @@ test -z "$1" && {
 	exit 1
 }
 
+test -d /doc/git/html/.git || { echo "Error: html pages in /doc/git/html/.git missing"; exit 1; }
+
 TARGET="$HOME"/WinGit-$1.exe
 OPTS7="-m0=lzma -mx=9 -md=64M"
 TARGET7=tmp.7z
@@ -21,6 +23,9 @@ mkdir "$TMPDIR" &&
  cp uninstaller.exe "$TMPDIR"/bin) &&
 cd "$TMPDIR" &&
 echo "Copying files" &&
+(git --git-dir=/doc/git/html/.git log --pretty=format:%s -1 HEAD &&
+ mkdir -p doc/git/html && cd doc/git/html &&
+ git --git-dir=/doc/git/html/.git archive HEAD | tar xf -) &&
 (cd / && tar cf - bin/{git*,awk,basename.exe,bash.exe,bunzip2,bzip2.exe,\
 cat.exe,chmod.exe,clear,cmp.exe,cp.exe,cpio,cut.exe,cvs.exe,date.exe,diff.exe,\
 du.exe,echo,egrep,env.exe,expr.exe,false.exe,find.exe,gawk.exe,grep.exe,\
-- 
1.5.3.mingw.1.3.g195850

-

Hi,


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
-

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

Hi,


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

-

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

-