Subject: Re: What's in git.git (stable)

From: Andy Parkins <[email-masked]>
Date: Wed, 13 Dec 2006 22:37:09 +0000

On Wednesday 2006, December 13 21:35, Junio C Hamano wrote:
> I am hoping that we can start a stabilization cycle for v1.5.0
> based on what we have in 'master'.  The theme is "usability and
> teachability".

This is what I have in my "niggles" list.  These are surface level things that 
I think are easy to fix.  A large part of the scariness is (I think) git's 
unfriendly output.  Too many messages require understanding of git internals.  

The major barrier to implementing these sorts of changes is, I think, worries 
about users of the output of these commands in scripts.  I say: screw them, 
porcelain is there for the breaking :-)

 * git-fetch has to be in working root.  If I can do git-push from anywhere in 
   my tree, why can't I do git-fetch?
 * git-reset has to be in working root.  If you typically sit in, say "src/", 
   it's annoying to have to change directory to do a reset.
 * git-commit doesn't (generally) have output - after a commit, it's difficult
   to know if anything happened.  Get users used to the idea of hashes to 
   identify commits by telling them which one they just made.  Tell them if 
   they made a branch as well, which branch they are now on.
 * git-init-db says "defaulting to local storage area", as if that is
   meant to be a helpful message
 * git-revert should be called git-invert.  It doesn't remove a change
   from history, it simply applies another commit that does the
   opposite of whatever commit you are "revert"ing.  That's an inversion.
 * git-merge output is horrible - this affects git-pull, git-rebase,
   and git-cherry-pick.  Issuing "fatal" errors and then carrying on is very
   confusing.  Errors in merges appear multiple times.  The files upon which
   which there is a conflict are spread throughout the output.  Most of the
   output is not relevant to an average user.
 * git-apply output is horrible.  It says a few things about whitespace on 
   stdin then just finishes.  When it succeeds.   When it fails, it just says
   failed, it doesn't say why a particular hunk failed.
 * git-branch is not verbose enough when creating a new branch, for a new user
   a little reassurance that what they meant to happen has happened would be 
   nice.
 * git-commit without "-a" and without an "update-index" says "nothing
   to commit", which isn't an adequate message to help a user who hasn't
   realised they need to update the index
 * git-rebase --skip requires that the offending file be clean with
     git-checkout HEAD file
   before the skip will work.  Why?  The fact of the skip is enough
   knowledge for rebase to know that I don't care if the merge is lost
 * git-rebase/git-cherry-pick/git-reset/etc should all tell the user that they 
   need to run git-prune to tidy up after themselves.
 * git-add has no output, whether it works or not
 * git-cat-file is badly named.  git-cat-object would be slightly
   better.
 * git-fetch output is confusing:
    remote: Generating pack...
    remote: Done counting 189146 objects.
    remote: Result has 186566 objects.
    remote: Deltifying 186566 objects.
    remote:  100% (186566/186566) done
    Unpacking 186566 objects
    24% (44792/186566) done
   Some questions from the point of view of a newbie: what is a pack?  what is 
   an object? Why is the remote counting them?  Which remote am I reading 
   from?  What am I fetching?  What is "Deltifying"?  How much data do I have 
   to download (number of objects doesn't tell me).  How long has this taken?  
   How long is left to go?
 * Similar things can be said about git-clone
 * Similar things can be said about git-push
 * git-show-branch output is cryptic.
 * In general the principle for messages should be the same as for 
   presentations:
    - say what you're going to do
    - do it
    - say what you did
   So for example, "git-branch newbranch existingbranch" would say
    Branching at "existingbranch", hash XXXXXXXXXXXXXXXXXX
     - created branch "newbranch"
     - your working branch is "existingbranch"
   Rather than the nothing that it currently outputs.
 * It would be really nice to be able to do an arbitrary checkout, rather than
   having to make a branch for it.  Then I could do
    git-checkout remotes/origin/master && make
   (obviously committing with a non-branch HEAD would be prevented)
 * git-verify-tag would be nicer as a switch to git-tag

Andy
-- 
Dr Andrew Parkins, M Eng (Hons), AMIEE