EasyGit [Was: Re: my git problem]

EasyGit [Was: Re: my git problem]

[Elijah Newren]

On Thu, May 1, 2008 at 12:01 AM, Carl Worth <cworth@cworth.org> wrote:
>  Or maybe go Elijah's route and invent a new top-level command name in
>  which issues like this can get fixed. (I've been lukewarm on the idea
>  after watching the cogito attempt eventually be abandoned. I'd really
>  much rather see Elijah's ideas get pushed down into git itself for the
>  most part. But it's tough when backwards-compatibility prevents fixing
>  some things that are obviously confusing people.)

Except my route really doesn't fix things like this since I also
pushed for backwards compatibility.  You'll note that Havoc used
EasyGit and Git interchangably (both in his description and probably
on his projects), since all I've really done so far in EasyGit is
* provide built-in tutorial-oriented documentation
* check for common user mistakes and warn about them
* add subcommand options in a way that breaks up the near cylic
knowledge dependence of git subcommands so that they can be learned in
a layered/hierarchical fashion
* add some gratuitous svn-compatibility commands to ease the
transition for svn users

I agree that it would be nice to get this stuff (other than the last
point that likely doesn't make sense for git-core) into git
itself...if the community wants it.  Starting as a separate project
simply allowed me to make mistakes and figure out what works; I've
seen lots of proposals in the past for fixing up git and lots of them
end up breaking special use cases -- I've had a number of those myself
in EasyGit (and may still have some) and had to go back and fix them
up or find other solutions.

Also, as Havoc pointed out pretty clearly, what I've done in eg is
helpful for people getting started but there's a lot more
learnability/usability issues that need to be addressed.  I thought it
made more sense to address those first, so that's my next step.

Elijah

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

[Elijah Newren]

On Fri, May 2, 2008 at 5:41 AM, Elijah Newren <newren@gmail.com> wrote:
> ... all I've really done so far in EasyGit is
>  * provide built-in tutorial-oriented documentation
>  * check for common user mistakes and warn about them
>  * add subcommand options in a way that breaks up the near cylic
>  knowledge dependence of git subcommands so that they can be learned in
>  a layered/hierarchical fashion
>  * add some gratuitous svn-compatibility commands to ease the
>  transition for svn users

I had typed up an explanation of what EasyGit is and does in more
detail and was going to wait to send it until I resolved some of the
issues Havoc brought up, but maybe it makes sense to send that out
now.  So, here it is:


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)
    - warning about or preventing many common gotchas users run into with
      git
    - enabling users to learn in a layered fashion
  A detailed explanation of the differences, rationale for the changes in
  eg, and even arguments against some of the changes I made in eg can be
  found at
    http://www.gnome.org/~newren/eg/git-eg-differences.html

Saving cvs/svn users:
  EasyGit also looks and feels like svn on the most common subset of
  functionality used in the two systems, mostly due to the addition of a
  number of gratuitous svn-compatibility commands (such as cat, resolved,
  update).  cvs and svn users may be interested in the detailed comparison
  at
    http://www.gnome.org/~newren/eg/git-for-svn-users.html

Trying it:
  I believe new users will be able to learn git faster by first using eg,
  than by starting with git directly.  Switching between using eg and git
  on the same repositories is considered perfectly normal.  There are a
  couple aids to assist users in switching back and forth between eg and
  git:
    - Each help page has a section for listing any differences between eg
      and git.
    - Users can run
        eg --translate ARGS...
      to see what git command(s) would be run by
        eg ARGS...
      without actually running them.

Goals for eg:
  Git has obtained a reputation for being difficult to learn.  I wanted to
  prove that a porcelain could be written which
    1) was easy to learn
    2) retained all the functionality in git
    3) does not hinder the workflows of longtime git users and does not
       require them to relearn the UI
  Feedback from early adopters suggest that I have made good progress
  towards achieving the first two goals; I do not have enough feedback
  to determine whether I have done well with the last one.

  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.


Elijah

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

[Christian Couder]

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.

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

[Sean Kelley]

On Fri, May 2, 2008 at 6:41 AM, Elijah Newren <newren@gmail.com> wrote:
> On Thu, May 1, 2008 at 12:01 AM, Carl Worth <cworth@cworth.org> wrote:
>>  Or maybe go Elijah's route and invent a new top-level command name in
>>  which issues like this can get fixed. (I've been lukewarm on the idea
>>  after watching the cogito attempt eventually be abandoned. I'd really
>>  much rather see Elijah's ideas get pushed down into git itself for the
>>  most part. But it's tough when backwards-compatibility prevents fixing
>>  some things that are obviously confusing people.)
>
> Except my route really doesn't fix things like this since I also
> pushed for backwards compatibility.  You'll note that Havoc used
> EasyGit and Git interchangably (both in his description and probably
> on his projects), since all I've really done so far in EasyGit is
> * provide built-in tutorial-oriented documentation
> * check for common user mistakes and warn about them
> * add subcommand options in a way that breaks up the near cylic
> knowledge dependence of git subcommands so that they can be learned in
> a layered/hierarchical fashion
> * add some gratuitous svn-compatibility commands to ease the
> transition for svn users
>
> I agree that it would be nice to get this stuff (other than the last
> point that likely doesn't make sense for git-core) into git
> itself...if the community wants it.

I agree with Carl in that my fear is that this will go the same route
as cogito if it doesn't get into git itself.  We use mercurial rather
extensively at garmin on my teams. There are a number of items I
really miss from git.  For the most part I believe Carl has enumerated
in other threads the sort of items that cause the greatest issues with
usability.

I think you addressed the first steps rather well with eg.

Sean