Re: EasyGit [Was: Re: my git problem]

[Christian Couder <chriscool@tuxfamily.org>]

Le vendredi 2 mai 2008, Elijah Newren a écrit :
>
> EasyGit (eg) is a single-file script/porcelain that looks and feels like
> core git.  In contrast to other simple-to-use porcelains, eg has all the
> same capabilities as git (in particular, it does not remove the index)
> and uses the same general syntax as core git.  Eg primarily reduces the
> learning curve associated with git and prevents common user errors.
>
> Changes:
>   Most of the changes in eg relative to git boil down to:
>     - plugging a large gap in git documentation (namely, providing a
>       tutorial-oriented built-in help system)

I had a look at it. And I have a few comments that I prefixed with '#' 
below.

$ eg help
[...]
Time saving commands
  eg bisect     Find the change that introduced a bug by binary search
[...]

# What did they do to my beloved bisect? I need to have a look.

$ eg help bisect
Sorry, bisect is not overridden or modified for eg, and no
help has been written for it.  If you're feeling brave, you may
want to try running 'git help bisect'.

# So they did nothing to it. Good ;-)
# But then why don't they ask people to use "git bisect" directly instead
# of "eg bisect" ?
#
# And they point to "git help bisect", good point.
# No need to "feel brave" to look at "git help bisect" though, because I
# think it is quite good. But I guess this is a generic message aimed at
# other commands. 

$ eg help clone
[...]
See also
  Run 'man git-clone' for a comprehensive list of options available.
  eg clone is designed to accept the same options as git clone, and
  with the same meanings unless specified otherwise in the above
  "Differences" section.

# The output is longer than my terminal's 41 lines so I don't see its top
# because there is no paging. 
# And why ask people to use "man git-clone" here, instead of "git help
# clone" ?

$ git clone -h
[...]

# "git clone -h" show more options in 18 lines only, but no examples
# and no description.
#
# I am not sure that the "Differences from git clone" part from "eg help
# clone" is really usefull for beginners.

$ eg changes --details
[...]

# Very long output but it's paged.

$ eg help help
[...]
Differences from git help:
  eg help uses its own help system, ignoring the one from git help...except
  that eg help will call git help if asked for help on a subcommand it does
  not recognize.

  "git help COMMAND" simply calls "man git-COMMAND".  The git man pages are
  really nice for people who are experts with git; they are comprehensive
  and detailed.

# It's not true that "eg help will call git help if asked for help on a
# subcommand it does not recognize", it only display the same message as
# for "eg help bisect" above.
# 
# Also it's not exactly true that '"git help COMMAND" simply calls "man
# git-COMMAND". If you use "git help -w COMMAND" or if you have
# the "help.format" set to "web", you get a HTML man page opened in a new
# tab in firefox (or something like that).
#
# And why not pointing to "git COMMAND -h" too, as it should give a "long
# usage" string that is often usefull and easier to use as the man page ? 

[...]
>
>   I would like to see the parts of eg that the community likes
>   incorporated into git core.  I do not know which changes would be
> wanted or welcome, and it may turn out that some of my changes show
> ignorance of certain aspects of git (some such cases have previously been
> uncovered already...and fixed).  But the discussion can't hurt, and a
> number of the solutions I used in eg I have not found in searches of
> previous discussions in the archives.

What I like about the built-in help system in eg is that there are lots of 
examples displayed. I think the git man pages are somewhat lacking in this 
area. (Some examples are still using the "git-COMMAND" syntax for example.) 

The built-in help text in eg also seems simpler and easier to understand, 
but it may be because there are fewer options and simpler commands to 
explain.

So here are some things that could be done to improve git help system:

- find a way to make users know that they can get long usage help using "git 
COMMAND -h"
- find a way to display some examples on the command line without the full 
man page
- add and improve examples in man pages
- add some simpler explanations to man pages and perhaps move more complex 
explanations to a "DETAILED DESCRIPTION" part of the man page
- improve man pages in other ways

Thanks,
Christian.