Subject: Re: [PYRITE] Status update and call for information.

From: Jakub Narebski <[email-masked]>
Date: Sun, 25 May 2008 13:35:35 +0200

Dnia sobota 24. maja 2008 23:50, Govind Salinas napisał:
> On Sat, May 24, 2008 at 3:47 PM, Jakub Narebski <[email-masked]> wrote:
>> On Sat, 24 May 2008, Dmitry Potapov wrote:
>>> On Sat, May 24, 2008 at 12:16:17AM -0500, Govind Salinas wrote:
>>>> On Fri, May 23, 2008 at 8:07 PM, Jakub Narebski <[email-masked]> wrote:
>>>>> "Govind Salinas" <[email-masked]> writes:
>>>>>
>>>>>> 1) Reduce the number of commands.
[...]
>>>>
>>>> Sure, removing commands is not about removing features, its about
>>>> reducing the learning curve and reducing confusion.

IMHO pushing too much into single commands do not reduce confusion
but increases it.

[Searching for a good example...] For example 'mv' could be modified
to include functionality of 'rm' in the form of 'mv file-to-delete',
but nobody sane would think of doing it.  Another example: you can
use 'less' to view contents of directory, but you usually use 'ls'
to do that; and nobody sane would think of extending 'less' to accept
all 'ls' switches, to have all 'ls' functionality.

I also think that having 30+ commands does not steep learning curve
make.  For example GNU coreutils only consist of 90 commands, but base
CLI is not that hard to use.

>>> I don't see how hiding creating branch functionality behind some other
>>> command will help with learning curve or reduce confusion. If I started
>>> to use any new SCM and had to create a new branch, I would look for the
>>> "branch" command. If there is something wrong with the git-branch then
>>> it is that this command does not checkout the newly created branch by
>>> default. So, I usually create branches using git-checkout, which is
>>> counterintuitive.
> 
> If you will allow me to respond to both items in this mail...
> 
> In bzr both clone and branch are in the 'branch' command because every
> branch is its own clone.  Hg defaults to a similar way of doing things and
> You clone into a new directory to get a new branch.
> 
> From the bzr user reference:
> 
> Branch:
> ...
> 
>   Aliases:
>      get, clone
> ...

Do not cater to least common denominator, please. 

> In truth, the git notion of a branch is pretty unique among SMCs.  In old
> systems a branch was just a copy of a set of files at a certain point.  In
> other DSCMs it is more likely to be a new copy of the repo.

I think git notion of branch is clean, and clearly superior to the crap
othe SCMs use ;-P.  I'd like to remind you that multiple branches in
single repository were something added at user request, at least
according to Junio's FLOSS weekly #19 follow-up in his blog
  http://gitster.livejournal.com/9970.html

> To answer your question a little better, I am looking at it like this:
> The predominant action is, as you say, going to be "I want to create a
> branch so that I can start working on something."  While I respect that
> you might want to create a branch and not start doing something
> *right away*, I think this is less likely.  So...
> 
> pyt co
>   this lists stuff you can checkout by which we mean local branches.

Note that "git checkout" defaults to HEAD.

> pyt co -r
>   this lists remote stuff you can check out, such as remote tracking
>   branches and the remotes themselves.
> 
> pyt co -a
>   lists both of the above, maybe tags too.

These three are all about listing metadata, refs to be more exact.
'checkout' is IMHO all about getting given state recorded in repository
(or, in git case, also from index) into working area, i.e. in a way
opposite to 'commit' or 'checkin', at least as far as it is possible.
So I think this is in the same league as using 'less' to view contents
(listing) of a directory.  This IMHO does not reduce confusion, but
adds to it.

Also note that git-branch is used to create and list branches
(unfortunately it uses -l for --enable-reflog and not for --list as
other commands like git-tag do), but can be also used to delete and
rename branches.  Do you want to stuff this functionality in "pyt co"?

> pyt co <branch>
>   checkout the branch, looking at refs

It is the default.

> pyr co <uri> <remote-name> <branch>
>    the user wants to checkout something that isn't local.  So we do
>    a git remote add -t <branch> -f <remote-name> <uri> followed by
>    checkout <remote-name>/<branch>
>    There would probably be variations/flags to get different functionality.

Please note that result of this is very, very different from ordinary
checkout.  Either it doesn't touch working area if it is equivalent
of git-fetch, or can result in conflicts and not a clean state if
it is equivalent of git-pull.

> pyt co -n mynewbranch [start=HEAD]
>   creates and checks out a new branch.

Simply different name for option, I think.

> pyt co [something=HEAD] [--] <files>...
>   should be obvious

But it isn't obvious.  

Let me explain.  Because in git commits are always whole-tree
snapshots, and usually (read: almost always) it makes sense to have
whole-tree commits in an SCM, this cannot switch branches.  So for
example there is a question if it is a separate mode (yet another
oveloading of 'pyt co' operator) of checkout changing working area
without changing current branch (something like svn-revert,
or hg-undo), or would it make HEAD detached and result in something
like not yet implemented "git cherry-pick <rev> -- <files>".

> The following are a little less intuitive, because they don't actually
> result in new stuff being put in the working directory.  These things are
> not really a checkout activity, I will stipulate that.  However, I don't think
> we need one interface to do stuff with branches and remotes, one to
> manage branches and one to mange remotes.  And I think that users
> will be able to grasp this pretty quickly.
> 
> pyt co --create-only mynewbranch
>   just creates without switching, it is a long option because this is not
>   a normal function and the user needs to understand what they are
>   doing.

This is not 'checkout', mind you.

> pyt co -d [-f] <branch-name> | <uri> | <remote>
>   delete a branch or stop tracking a remote.

Oh, so you do plan to stuff at least deleting branches and remotes
in 'pyt co'?

What was the UNIX motto: do one thing, and do it well?

>>> I don't think any commonly used SCM unites 'clone', 'branch', and
>>> 'checkout' functionality under the same name. This approach seems
>>> to be more confusing than helpful.
[...]
> See above, they in fact do.  It struck me as odd too, because I had
> started with git.  After thinking about it for a while, I saw advantages
> to it.

And it looks like you gone to far in the reducing number of commands
direction and do not see disadvantages of heavily overloaded, DWIM-ming,
doing multiple different things depending on options commands.  If you
don't like large number of commands (is 30+ large number?), use GUI!

What you need is to have some _users_ to tell you if you do with
Pyrite in good direction.  Or at least analysis of common git workflows
and how they could be improved...

-- 
Jakub Narebski
Poland