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

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

[Carl Worth]

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

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/
	

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

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

[Shawn O. Pearce]

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.

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

[Johannes Schindelin]

Hi,

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

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

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

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

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

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

--pretty=fuller

Ciao,
Dscho

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

[Steffen Prohaska]

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

>
> On Fri, 28 Sep 2007, Shawn O. Pearce wrote:
>
>> 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.
>
> 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).
>

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

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

[Johannes Schindelin]

Hi,

On Sat, 29 Sep 2007, Steffen Prohaska wrote:

> On Sep 29, 2007, at 2:49 AM, Johannes Schindelin wrote:
> 
> > 
> > On Fri, 28 Sep 2007, Shawn O. Pearce wrote:
> > 
> > > 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.
> > 
> > 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).
> 
> 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'm hesitant... The html branch is synced with the master branch.  And we 
deviate from the master branch quite a lot ATM.

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

This will be a good temporary workaround.

Ciao,
Dscho

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

[Steffen Prohaska]

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

> Hi,
>
> On Sat, 29 Sep 2007, Steffen Prohaska wrote:
>
>> On Sep 29, 2007, at 2:49 AM, Johannes Schindelin wrote:
>>
>>>
>>> On Fri, 28 Sep 2007, Shawn O. Pearce wrote:
>>>
>>>> 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.
>>>
>>> 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).
>>
>> 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'm hesitant... The html branch is synced with the master branch.   
> And we
> deviate from the master branch quite a lot ATM.

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.


>> I'll provide a patch (hopefully next week).
>
> This will be a good temporary workaround.

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

[PATCH] WinGit: included /bin/start in the installer

[Steffen Prohaska]

/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

[PATCH] WinGit: include html pages from official git.git's html branch

[Steffen Prohaska]

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

Re: [PATCH] WinGit: include html pages from official git.git's html branch

[Johannes Schindelin]

Hi,

On Sat, 29 Sep 2007, Steffen Prohaska wrote:

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

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

Re: [PATCH] WinGit: include html pages from official git.git's html branch

[Junio C Hamano]

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

> Hi,
>
> On Sat, 29 Sep 2007, Steffen Prohaska wrote:
>
>> 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?
>
> 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.

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

Re: [PATCH] WinGit: include html pages from official git.git's html branch

[Johannes Schindelin]

Hi,

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

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > On Sat, 29 Sep 2007, Steffen Prohaska wrote:
> >
> >> 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?
> >
> > 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.
> 
> This is starting to smell like an opportunity to use the gitlink stuff, 
> isn't it?

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

Re: [PATCH] WinGit: include html pages from official git.git's html branch

[Steffen Prohaska]

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

> Hi,
>
> On Sat, 29 Sep 2007, Junio C Hamano wrote:
>
>> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>>
>>> On Sat, 29 Sep 2007, Steffen Prohaska wrote:
>>>
>>>> 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?
>>>
>>> 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.
>>
>> This is starting to smell like an opportunity to use the gitlink  
>> stuff,
>> isn't it?
>
> I'd agree that we could have a submodule in /doc/git/html/.  This way,
> even users of msysGit and GitMe would benefit.

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

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

[Pierre Habouzit]

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

On Sat, Sep 29, 2007 at 12:00:56AM +0000, Shawn O. Pearce wrote:
> 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.

  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.

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

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

[RFC] patch series to sketch a less verbose and frightening output

[Pierre Habouzit]

  Follow 4 patches that rework progress.c a bit so that one stage only
takes one line of output with a progress bar.

  Some of the patch fix (IMHO) pointless lines to print on screen (even
for debugging purposes).

  With those patches, running git gc looks like:

    $ git gc
    Counting objects    : 10095
    Deltifying objects  : [===================================================] 100%
    Writing objects     : [==========================>                        ] 50%

    [...]

    Counting objects    : 10095
    Deltifying objects  : [===================================================] 100%
    Writing objects     : [===================================================] 100%
    Pruning objects     : [===================================================] 100%

I don't believe those patches are 100% okay yet, because it doesn't
plays that nice during a clone (it's not horribly broken, merely
surprising). But it sketches what it could look like.

Re: [RFC] patch series to sketch a less verbose and frightening output

[Pierre Habouzit]

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

On Sat, Sep 29, 2007 at 10:45:54AM +0000, Pierre Habouzit wrote:
>   Follow 4 patches that rework progress.c a bit so that one stage only
> takes one line of output with a progress bar.
> 
>   Some of the patch fix (IMHO) pointless lines to print on screen (even
> for debugging purposes).
> 
>   With those patches, running git gc looks like:
> 
>     $ git gc
>     Counting objects    : 10095
>     Deltifying objects  : [===================================================] 100%
>     Writing objects     : [==========================>                        ] 50%
> 
>     [...]
> 
>     Counting objects    : 10095
>     Deltifying objects  : [===================================================] 100%
>     Writing objects     : [===================================================] 100%
>     Pruning objects     : [===================================================] 100%
> 
> I don't believe those patches are 100% okay yet, because it doesn't
> plays that nice during a clone (it's not horribly broken, merely
> surprising). But it sketches what it could look like.

  Okay, sorry this was supposed to answer to
<20070929090121.GA4216@artemis.corp>

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

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

Re: [PATCH 1/4] Rework progress module so that it uses less screen lines, with progress bars.

[Nicolas Pitre]

On Sat, 29 Sep 2007, Pierre Habouzit wrote:

> Signed-off-by: Pierre Habouzit <madcoder@debian.org>

NAK.

I don't mind the progress bar, but please don't supress the printing of 
the number of objects.  This is the only indication we have to 
guesstimate the time needed for given operation.


Nicolas

Re: [PATCH 1/4] Rework progress module so that it uses less screen lines, with progress bars.

[Pierre Habouzit]

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

On Sat, Sep 29, 2007 at 02:33:44PM +0000, Nicolas Pitre wrote:
> On Sat, 29 Sep 2007, Pierre Habouzit wrote:
> 
> > Signed-off-by: Pierre Habouzit <madcoder@debian.org>
> 
> NAK.
> 
> I don't mind the progress bar, but please don't supress the printing of 
> the number of objects.  This is the only indication we have to 
> guesstimate the time needed for given operation.

  As said, I don't intend this series to be integrated as is, it's just
a basis for some discussion :)

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

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

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

[Wincent Colaiuta]

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

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

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

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

[Pierre Habouzit]

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

On Sun, Sep 30, 2007 at 12:45:34PM +0000, Wincent Colaiuta wrote:
> El 29/9/2007, a las 11:01, Pierre Habouzit escribió:
> 
> >  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.
> 
> 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.

  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.

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

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

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

[Wincent Colaiuta]

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

> On Sun, Sep 30, 2007 at 12:45:34PM +0000, Wincent Colaiuta wrote:
>>
>> 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.
>
>   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.

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

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

[Steffen Prohaska]

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

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

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

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

[Junio C Hamano]

Steffen Prohaska <prohaska@zib.de> writes:

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

Probably.

> - git rebase: prints a lot of details that I'm not interested in
>   unless the rebase fails.

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.

> - git push: prints updates of remote heads. A message about
>   failing to update a remote head may get lost.

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.

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

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.

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

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.

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

[Steffen Prohaska]

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

> Steffen Prohaska <prohaska@zib.de> writes:
>
>> - git push: prints updates of remote heads. A message about
>>   failing to update a remote head may get lost.
>
> 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.

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.


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


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

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.

> and report of successful remote ref updates are such things, so we
> should be careful not to go overboard.

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

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

[Junio C Hamano]

Steffen Prohaska <prohaska@zib.de> writes:

> ... If everything's ok I do.
>
>    git checkout master
>    git merge for/master
>    git push
>
> The last merge must be a fast forward.

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.

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

[Johannes Schindelin]

Hi,

On Sun, 30 Sep 2007, Steffen Prohaska wrote:

> 
> On Sep 30, 2007, at 12:25 AM, Junio C Hamano wrote:
> 
> > Steffen Prohaska <prohaska@zib.de> writes:
> > 
> > > - git push: prints updates of remote heads. A message about
> > >   failing to update a remote head may get lost.
> > 
> > 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.
> 
> 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.

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

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

[Steffen Prohaska]

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

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

good idea.

	Steffen

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

[Junio C Hamano]

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

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

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

[Carl Worth]

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

On Fri, 28 Sep 2007 17:45:30 -0700, Junio C Hamano wrote:
> Thanks for starting this.  It was an interesting read.

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

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

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

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

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

[Carl Worth]

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

On Fri, 28 Sep 2007 17:45:30 -0700, Junio C Hamano wrote:
> Thanks for starting this.  It was an interesting read.

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

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

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

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

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

[Nguyen Thai Ngoc Duy]

On 9/29/07, 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/

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