Re: obnoxious CLI complaints

[Jakub Narebski <jnareb@gmail.com>]

On Thu, 10 Sep 2009, Brendan Miller wrote:
> On Wed, Sep 9, 2009 at 2:54 PM, Jakub Narebski <jnareb@gmail.com> wrote:

>> Brendan Miller <catphive@catphive.net> writes:
>> First question: which git version do you use?
> 
> It sounds like a bunch of things have been fixed in yet to be released
> versions. That's great.

Both "git init --bare" and cloning empty repository are in _released_
versions.
 
>>> This is what I want to do 90% of the time, so it should just have the
>>> proper defaults, and not make me look at the man page every time I
>>> want to use it.
>>
>> You learn those idioms.
> 
> I guess. Is that a good thing? Is the goal of interface design to make
> it difficult so I need to learn a lot of things, or easy so I can
> remain blissfully ignorant but still do what I want?

There are at least two issues:
1. What you want to do 90% of time might be not what other people want
   to do 90% of time.
2. Some thing are due to git philosophy (like e.g. "git commit -a").
 
As to git-archive example: first, git-archive _has_ default format, and
it is tar.  Second, compression is better left to separate program, but
I guess we can follow GNU tar example and add equivalents of -Z/-z/-j
and --use-compress-program options when using --output=<file>.  Third,
when using e.g. tar you have to specify files to compress, so I don't
know why you complain that git-archive requires equivalent, HEAD in your
example.

>>> 6. Where is the bug tracker? If people users can't find the bug
>>> tracker, they can't report issues, and obnoxious bugs go unfixed, or
>>> people have to whine on the mailing list. There should be a nice big
>>> link on the front page of git-scm.com. A bug tracker is really the
>>> only way for the vast majority of a community that use a tool can give
>>> feedback on the problems the tool has.
>>
>> Do you offer to maintain and manage such bug tracker?  I mean here
>> taking care of duplicated bugs, tracking which bugs are resolved and
>> which are not, checking if bug is reproductible, etc.  Do you?
>> Unmaintained bugtracker is worse than useless.
>>
>> Using mailing list for bug reports and for patches is time-honored
>> workflow, which works rather well for smaller projects such as Git.
>> Note that git mailing list is free for all; you don't need to
>> subscribe to send, and you can watch it via many archives and gateways
>> (like GMane).
> 
> Bug trackers are a hassle, believe me, I know... but I think they
> contribute to the overall quality of the product if used effectively.
> Mailing lists seem like a good way to forget about bugs after people
> have given up on getting developers to fix them.

This is a good way to separate important from unimportant bug reports
and feature requests ;-)

>>> 7. Man pages: It's nice we have them, but we shouldn't need them to do
>>> basic stuff. I rarely had to look at the man pages using svn, but
>>> every single time I use git I have to dig into these things. Frankly,
>>> I have better things to do than RTFM.
>>
>> Learn.  If you learn the philosophy behind git design, you would have
>> much easier understanding and remembering git.
> 
> I think what you mean by philosophy is the underlying data structures,
> which are discussed in the manual (how many apps do you have that do
> that!). I have read that. However, that one needs to understand
> underlying data structure is just one more hurdle to understanding
> git.

No, I didn't mean understanding underlying data structures, but 
understanding philosophy: graph of revisions; tracking contents; refs
as pointers to graph of revisions; the trifecta of working area, 
the index and repository, etc.

> If I use GCC, do I need to know that it has a recursive descent
> parser? That it is implemented with a garbage collector? No. I just
> need to know that I give it C, and it gives me a binary.

Better example would be using "make".  You need to understand 'make'
philosophy to write all but most simple of Makefiles.

> 
> Example:
> gcc main.c
> 
> Think about all the defaults that are specified here! I don't
> explicitly tell it how to find libc.so or what path the dynamic linker
> is at. I don't even really need to tell it which operation it is
> performing, i.e. generating a binary, .o, .so, .os, .a, etc because it
> has a smart default.

And if you are smart, you never use this form, but "gcc -o main main.c".
And you have to specify '-lm' if you use math routines.  Not that simple,
isn't it?

> This an order of magnitude more complex than any git operation in
> terms of implementation, but it is dead simple from the users
> perspective.

When git (or the concept of DVCS) is as old as gcc (or C compiler) is
now, then we can talk.
 
>> There is "Git User's Manual", "The Git Community Book", "Pro Git" and
>> many other references.
> 
> Yeah, I've been reading them. I'm saying that the docs are a crutch.
> RTFM is the problem not the solution. It makes the user do more work
> to avoid fixing usability issues.

When the tool is more complicated (like DVCS), you can't use it in all
but simplest cases without understanding it.

> A CLI has some inherent limitations in that it doesn't have big
> labeled buttons to press. However, that doesn't mean it has to be hard
> to use. I think a lot of the strength of the linux CLI is that most of
> the utilities have actually pretty well thought out interfaces that
> have been refined over time. That one's that aren't like that... well,
> no one uses them.
> 
> I'm not saying that a unixy approach is wrong, but that most unix
> utilities are much easier to use than git, and that git needs
> improvement on this front.

I'm not saying that git doesn't need UI (and documentation) improvements.
But first, your attitude is a bit grating, and second, your examples
are not it.

On the other hand there is inherent problems that serious git 
contributors use git for a long time and are used to (and perhaps even
attached to) git UI warts, and newbies which start to use git not always
can distinguish between things that can be changed and things that cannot
be changed.

-- 
Jakub Narebski
Poland