Re: Cleaning up git user-interface warts

Re: Cleaning up git user-interface warts

[linux]

>> 1) make "git init" an alias for "git init-db".

> Or even better, have "gh init".

If you're going to be inspired by hg, pick a cleverer name. :-)

If you want to add a thin attractive layer, silver-plate the thing and
call it "ag".  Since it contains the letter g as well, I'm sure that
someone can come up with a good backronym for it.


Latin element names:

Ag - Argentum
Au - Aureum
Cu - Cuprum
Fe - Ferrum
Hg - Hydrargyrum
K - Kalium
Na - Natrium
Pb - Plumbum
Sb - Stibium

Re: Cleaning up git user-interface warts

[Shawn Pearce]

linux@horizon.com wrote:
> >> 1) make "git init" an alias for "git init-db".
> 
> > Or even better, have "gh init".
> 
> If you're going to be inspired by hg, pick a cleverer name. :-)
> 
> If you want to add a thin attractive layer, silver-plate the thing and
> call it "ag".  Since it contains the letter g as well, I'm sure that
> someone can come up with a good backronym for it.

Is "more Attractive Git" not good enough?

-- 

[PATCH] commit: Steer new users toward "git commit -a" rather than update-index

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 733 bytes --]

As has been discussed recently, update-index isn't intended as a
"porcelain" command so the mention of it in the output of git-commit
does lead to some user confusion.
---
 wt-status.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/wt-status.c b/wt-status.c
index 7dd6857..4edabcd 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -126,7 +126,7 @@ static void wt_status_print_changed_cb(s
 	int i;
 	if (q->nr)
 		wt_status_print_header("Changed but not updated",
-				"use git-update-index to mark for commit");
+				"use \"git commit <files>\" to commit or \"git commit -a\" for all");
 	for (i = 0; i < q->nr; i++)
 		wt_status_print_filepair(WT_STATUS_CHANGED, q->queue[i]);
 	if (q->nr)
--
1.4.3.3.gf040


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [PATCH] commit: Steer new users toward "git commit -a" rather than update-index

[Andy Whitcroft]

Carl Worth wrote:
> As has been discussed recently, update-index isn't intended as a
> "porcelain" command so the mention of it in the output of git-commit
> does lead to some user confusion.
> ---
>  wt-status.c |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
> 
> diff --git a/wt-status.c b/wt-status.c
> index 7dd6857..4edabcd 100644
> --- a/wt-status.c
> +++ b/wt-status.c
> @@ -126,7 +126,7 @@ static void wt_status_print_changed_cb(s
>  	int i;
>  	if (q->nr)
>  		wt_status_print_header("Changed but not updated",
> -				"use git-update-index to mark for commit");
> +				"use \"git commit <files>\" to commit or \"git commit -a\" for all");
>  	for (i = 0; i < q->nr; i++)
>  		wt_status_print_filepair(WT_STATUS_CHANGED, q->queue[i]);
>  	if (q->nr)
> --
> 1.4.3.3.gf040

Are we sure this isn't porcelain-ish?  We need to use it in merge
conflict correction and the like?  You can't use git-commit there as a
replacement.  I'd expect it to be 'git update-index' rather than
'git-update-index' of course.

Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 3070 bytes --]

On Tue, 14 Nov 2006 18:55:51 +0000, Andy Whitcroft wrote:
> Carl Worth wrote:
> > As has been discussed recently, update-index isn't intended as a
> > "porcelain" command so the mention of it in the output of git-commit
> > does lead to some user confusion.
>
> Are we sure this isn't porcelain-ish?  We need to use it in merge
> conflict correction and the like?  You can't use git-commit there as a
> replacement.  I'd expect it to be 'git update-index' rather than
> 'git-update-index' of course.

It was Junio that recently said update-index is plumbing, not
porcelain.

So, the fact that conflict resolution still requires the use of
update-index would just be the next thing to fix. A name for a
replacement to use there could be "git resolve <paths>", (since the
old git-resolve is now officially deprecated). That's a name that
matches what hg uses in this situation, (another option is "resolved"
which is what stg uses, but I think verbs for commands work better in
general).

It would be really nice if none of the "common" commands had a hyphen
in them, for example.

And then, the next phase of my evil plan would be to introduce a -i
option for git-commit making it commit the state in the index. Then
git-commit with no options could work like "git-commit -a" does now,
(with the additional protection of not committing any unmerged
files---that is the new "git resolve" would be required before "git
commit" would work after a conflict). Users who really, really like
the current behavior of git-commit could use the new alias support to
pass the new -i option in order to maintain compatible behavior.

Then, the last thing I'd really like to fix is to allow a usage of
"git merge <branch>" instead of the awkward "git pull . <branch>".

With that, most of the user-interface warts that I regularly run into
with git would be solved. Oh, except it would also be nice to
eliminate the "plumbing" commands in a couple of places:

 1) From the "man git" man page

 2) From git-<TAB>, (maybe the solution for this is to make
    "git <TAB>" work and only do tab-completion for the commands
    blessed enough to appear in "git --help"? Also push the tab
    completion stuff out as a standard part of packages.

Anyway, now I've just gone and blown all my secret plans for changing
git in ways to make it less intimidating for new users.

For reference, the latest potential batch of new users that I'm
dealing with is the set of Fedora package maintainers who are looking
at replacing CVS for their tree of package-building scripts. They are
currently evaluating systems and liking the interface of hg. Here's
the top of the current thread:

https://www.redhat.com/archives/fedora-maintainers/2006-November/msg00030.html

Here's the report about "git commit -a" confusion that led to my patch
above:

https://www.redhat.com/archives/fedora-maintainers/2006-November/msg00141.html

And here's my reply where I suggest that git UI might still be
improved in these areas:

https://www.redhat.com/archives/fedora-maintainers/2006-November/msg00149.html

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Carl Worth <cworth@cworth.org> wrote:
>  2) From git-<TAB>, (maybe the solution for this is to make
>     "git <TAB>" work and only do tab-completion for the commands
>     blessed enough to appear in "git --help"? Also push the tab
>     completion stuff out as a standard part of packages.

Uh, see contrib/completion/git-completion.bash.

"git <TAB>" completes commands.  It offers too many completions
for your taste it sounds like, as it also offers plumbing... but
that's fixable.  :-)

-- 

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 1662 bytes --]

On Tue, 14 Nov 2006 14:29:14 -0500, Shawn Pearce wrote:
> Uh, see contrib/completion/git-completion.bash.

Oops. I had seen this and thought I had installed it properly a while
ago, (copied it to /etc/bash_completion.d/git), but I hadn't realized
it wasn't active in the shell I used to test while composing that
email.

> "git <TAB>" completes commands.  It offers too many completions
> for your taste it sounds like, as it also offers plumbing... but
> that's fixable.  :-)

Yes, I think we'd all be better off if we could designate some subset
of the current git commands as not being intended for users to type on
the command line and pulled them out of the completion scripts.

It is tough though. Looking through what's available in the short list
from "git --help" I notice that update-index isn't there, and that's
currently still required, (as we've been discussing here). But even
things as "core plumbing" as git rev-list I find extremely useful on
the command like with simple pipelines.

On the other hand, there are definitely some commands I've never
typed, and are not intended to be typed by the user. Here are a few I
see as fairly obvious just from skimming the list:

	merge-*
	http-*
	ssh-*
	upload-*
	mktag
	mktree
	check-ref-format
	...

There are a bunch of others as well. Maybe it would be easier to start
with the list in git --help and see what should be added to that.

The documentation for some of the above commands have phrases such as
"Invoked by <other command>" and "usually not invoked by the end user"
which does make the distinction quite clear. So it would be nice if
git could keep these away from the user more.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Tue, Nov 14, 2006 at 08:22:39PM CET, Carl Worth wrote:
> For reference, the latest potential batch of new users that I'm
> dealing with is the set of Fedora package maintainers who are looking
> at replacing CVS for their tree of package-building scripts. They are
> currently evaluating systems and liking the interface of hg. Here's
> the top of the current thread:
> 
> https://www.redhat.com/archives/fedora-maintainers/2006-November/msg00030.html
> 
> Here's the report about "git commit -a" confusion that led to my patch
> above:
> 
> https://www.redhat.com/archives/fedora-maintainers/2006-November/msg00141.html
> 
> And here's my reply where I suggest that git UI might still be
> improved in these areas:
> 
> https://www.redhat.com/archives/fedora-maintainers/2006-November/msg00149.html

Hmm, did they (not) consider Cogito? They wouldn't have those issues.
;-)

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 2691 bytes --]

On Tue, 14 Nov 2006 20:47:07 +0100, Petr Baudis wrote:
> Hmm, did they (not) consider Cogito? They wouldn't have those issues.

I didn't ask.

Frankly, I don't see a lot of value in the git/cogito split right now.

When I first learned git and cogito (January 2006) and switched cairo
from cvs to git (the repository storage), I recommended cogito to
cairo programmers as a "more cvs-like" way to work with the new
repository.

Since then, having worked with git (the command-line program)
exclusively for my own work, and having introduced it to dozens of new
users, I don't bother recommending cogito anymore. It's just not that
hard to learn git itself, so there's not that much value in learning
cogito instead.

And this is particularly true since there's quite a large cost to
having to learn cogito _in addition to_ git. And I think that's what
most people would have to do anyway. For example, cogito doesn't wrap
all git commands. So users have to dip down into git for things like
git-bisect or else miss out an important functionality.

And for something like the Fedora transition, where I'm working with
the people who will be training the community in the new tools, the
trainers would have to learn both if they want to support a community
using both git and cogito. These trainers are already complaining
about the ~140 git commands, so adding 40 more cogito commands as well
doesn't make the story better.

It's great that git is written in a script-friendly way so that new
interfaces can be built on top of it. And I think the benefits of new
user interfaces are clear when they work in fundamentally different
ways, (say, being operated through a GUI). But where git and cogito
are both command-line utilities and have the same basic functionality,
I don't see how its helpful to maintain both tools. (Certainly some of
my attitude here is due to the timing of my introduction to git
contrasted with the timing of the inception of cogito. I'm sure git
improved a lot between those two events.)

There are some things that cogito does that git does not that I would
like to have in git. One is having a "commit" command that commits
everything by default without an extra command-line option. Another
(that I _think_ cogito has) is a way to switch away from a branch with
dirty changes to a clean branch, do work there, and come back to the
original branch with the dirty stuff still there.

I don't see any defining difference that justifies cogito's
existence ("hide the index" maybe? let's just hide it a tiny bit more
in git). And I would like to help work to get the remaining good
stuff that has been proven in cogito---to get it pushed down into git
itself.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> On Tue, 14 Nov 2006 20:47:07 +0100, Petr Baudis wrote:
>> Hmm, did they (not) consider Cogito? They wouldn't have those issues.
>
> I didn't ask.
>
> Frankly, I don't see a lot of value in the git/cogito split right now.
> ...
> It's great that git is written in a script-friendly way so that new
> interfaces can be built on top of it. And I think the benefits of new
> user interfaces are clear when they work in fundamentally different
> ways, (say, being operated through a GUI). But where git and cogito
> are both command-line utilities and have the same basic functionality,
> ...
> There are some things that cogito does that git does not that I would
> like to have in git.
> ...
> I don't see any defining difference that justifies cogito's
> existence ("hide the index" maybe? let's just hide it a tiny bit more
> in git). And I would like to help work to get the remaining good
> stuff that has been proven in cogito---to get it pushed down into git
> itself.

I am of two minds here.

I do not think the Porcelain-ish UI that is shipped with git
should be taken with the same degree of "authority" as git
Plumbing.  The plumbing needed to have something that worked for
one particular workflow (namely, workflow of the people in the
integrator role of kernel-style project) and that is where the
current set of Porcelain-ish originates.  Linus works primarily
as an integrator so the toolsets he did tend to be more pleasant
to use for integrators and less so for contributors.  I started
as a contributor and added some commands like format-patch and
rebase that Linus never would have felt the need for.  I think
single isolated developers, contributors and CVS style shared
repository usage could be a lot improved because neither of us
were concentrating in their workflows.  This needs somebody
motivated enough to improve things in that area.  For example,
StGIT with its 'float' command is a great improvement over what
rebase does for people in the contributor role.

By now, perhaps git may be good enough for the kernel folks,
even for those not in the integrator role, but I have no doubt
that they have many dislikes to the way some commands work.
They and X.org folks are using git primarily because Linus and
Keith forced them to ;-), and being interoperable is more
important than having to tolerate sucky UI here and there.
Everybody knows that git Porcelain-ish sucks, and making it more
usable is a worthy goal.

But making it more usable for whom is a big question.  

Quite frankly, I do not think there can be _the_ single UI that
would satisfy different types of workflows for some of the
commands.  The commands related to software archaeology, in
which my main interest and strength lie, would easily be usable
across workflows, but commands to build commits locally and
propagate them to and from other repositories would be affected
by the workflow.

For example, fetching and merging from many places without
necessarily having corresponding tracking branches is a great
thing for people in the integrator role.  On the other hand, for
people doing CVS-style centralized repository interaction, it is
often more useful to have tracking branches.  You could support
both but it has been painful.

For another example, having a commit command to commit
everything by default is disastrous for people who allow their
workflows to often be interrupted.  When I respond to a message
from the list with an example patch, my repository is often in
the middle of doing something completely unrelated, and I edit
and make diff to send the message out and I do not necessarily
revert that change afterwards immediately.  For more organized
people it may not be a problem so you either support both types
of workflows or do a specialized toolset.

It is not just command line syntax and the defaults, but
concepts as well.  People in the integrator role often need to
deal with merges and you would need to be aware of the role of
the index and need to be able to manipulate the index, a lot
more often than people in the contributor role.  To satisify
both kinds of workflows, you would either have switches, or do a
specialized toolset, like Cogito, that tries to hide the index.

A Porcelain that does a very similar thing in slightly different
way is obviously a waste, but otherwise I do not think it is a
problem to have different Porcelains.  StGIT does not compete
with the "sucky" Porcelain-ish shipped with git but makes the
user's life a lot more pleasant by complementing what the sucky
one does not do well.  It is not very useful while I am playing
the integrator role, but when I am doing my own thing it is a
great addition to my toolchest.

I am from the camp that does _not_ want to hide the index, so
obviously I do not see any value in its effort to hide the
index.  But other aspects of it, most notably being friendly to
simpler workflows, is a very good thing.

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 01:31:50AM CET, Junio C Hamano wrote:
> Carl Worth <cworth@cworth.org> writes:
> 
> > On Tue, 14 Nov 2006 20:47:07 +0100, Petr Baudis wrote:
> >> Hmm, did they (not) consider Cogito? They wouldn't have those issues.
> >
> > I didn't ask.
> >
> > Frankly, I don't see a lot of value in the git/cogito split right now.
> > ...
> > It's great that git is written in a script-friendly way so that new
> > interfaces can be built on top of it. And I think the benefits of new
> > user interfaces are clear when they work in fundamentally different
> > ways, (say, being operated through a GUI). But where git and cogito
> > are both command-line utilities and have the same basic functionality,
> > ...
> > There are some things that cogito does that git does not that I would
> > like to have in git.
> > ...
> > I don't see any defining difference that justifies cogito's
> > existence ("hide the index" maybe? let's just hide it a tiny bit more
> > in git). And I would like to help work to get the remaining good
> > stuff that has been proven in cogito---to get it pushed down into git
> > itself.
> 
> I am of two minds here.
> 
> I do not think the Porcelain-ish UI that is shipped with git
> should be taken with the same degree of "authority" as git
> Plumbing.
..snip passage about workflows..

Controversy's fun, so...

<Cogito maintainer hat _off_> (But yeah, it still looks silly that I'm
saying this.)

 From the current perspective, I think it has been a mistake that the
porcelain and plumbing was not kept separate in independent packages,
and perhaps even maintained separately (and perhaps not; at least having
a single tree with plumbing/ and porcelain/ directories and separate
packages in distributions might already help something), so that "git"
would be kept as a kind of library and then there would be a separate
package providing an interface to it. Or you could select one of several
packages. Not only would that make Cogito prevail in the world and bring
me a flood of marriage proposals, but look at how would it help the
general public:

  (i) Clearly divided porcelain/plumbing interface, so that you can
really isolate the two UI-wise; endless confusion reigns there now. Is
git-update-index porcelain or plumbing? _You_ call git-merge a proper
porcelain? From my perspective, git-update-ref is as plumbing as it
gets, but it's classified as porcelain. Etc, etc. This would be by far
the most important advantage.

  (ii) The plumbing and porcelain would not share the same namespace,
leading to clearer UI. (I'm just inflating (i).)

  (iii) The documentation would not be a strange mix of porcelain and
plumbing. (More (i) inflation.)

  (iv) (i) is troublesome because I have a feeling that Junio declared
several times that he doesn't care that much about stable API for
porcelain compared to the plumbing. But with the current mix it's
desirable to use some porcelain even in other porcelains and in scripts.

  (v) Git would be properly libified by now. If you wanted to convert
bits of porcelain to C, it would be at least much higher priority.

  (vi) You wouldn't need to make the gruesome choice on what is the
canonical workflow the _the_ Git porcelain supports (see the snipped
passage). Or you would, but it would have less impact.

  (vii) The world would be a happier place.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

> On Wed, Nov 15, 2006 at 01:31:50AM CET, Junio C Hamano wrote:
>> 
>> I am of two minds here.
>> 
>> I do not think the Porcelain-ish UI that is shipped with git
>> should be taken with the same degree of "authority" as git
>> Plumbing.
> ..snip passage about workflows..
>
> Controversy's fun, so...
>
> <Cogito maintainer hat _off_> (But yeah, it still looks silly that I'm
> saying this.)

It appears that you are not grumpy as you were anymore ;-).  I
mostly agree with what you said in your message.

> (i) Clearly divided porcelain/plumbing interface, so that you can
> really isolate the two UI-wise; endless confusion reigns there now. Is
> git-update-index porcelain or plumbing? _You_ call git-merge a proper
> porcelain? From my perspective, git-update-ref is as plumbing as it
> gets, but it's classified as porcelain. Etc, etc. This would be by far
> the most important advantage.

Yes.  The current "merge" started its life as Linus's porcelain
(we did not have fetch and pull infrastructure back then) but
quickly has become just a helper for pull to produce a merge
commit.  If anybody thinks its UI is good as a general end-user
level command, there is a need for "head examination".

As you say, update-ref is as plumbing as it gets and it should
not be listed as Porcelain; I am a bit surprised that it is
labelled as such myself.

No disagreement here, nor (ii) nor (iii).

>   (ii) The plumbing and porcelain would not share the same namespace,
> leading to clearer UI. (I'm just inflating (i).)
>
>   (iii) The documentation would not be a strange mix of porcelain and
> plumbing. (More (i) inflation.)
>
>   (iv) (i) is troublesome because I have a feeling that Junio declared
> several times that he doesn't care that much about stable API for
> porcelain compared to the plumbing. But with the current mix it's
> desirable to use some porcelain even in other porcelains and in scripts.

This is true and it is a problem.

While we encourage Porcelain writers to use plumbing in order to
give git Porcelain-ish more freedom to evolve to give better UI
for humans, not having a clear distinction between the two makes
it harder.

>   (v) Git would be properly libified by now. If you wanted to convert
> bits of porcelain to C, it would be at least much higher priority.

I am not sure about "libified" part and I do not know what bits
of porcelain wants to become C right now.  But I do not think
this point is important part of your list.

>   (vi) You wouldn't need to make the gruesome choice on what is the
> canonical workflow the _the_ Git porcelain supports (see the snipped
> passage). Or you would, but it would have less impact.

Yes.  This is really important.

Linus and me having done Porcelain-ish that supports integrator
role workflow better than other workflows such as contributor
role should not discourage people from working on alternative or
complementary Porcelains to help other workflows better (see the
snipped passage).

StGIT sets a great example, and efforts like it is encoraged
more.

I think both Linus and myself tried to make it clear that the
purpose of Porcelain-ish that comes with core git is 50% to make
plumbing (perhaps minimally) usable and the other 50% to serve
as an example for Porcelain writers to learn how to use the
plumbing, but we should probably have stressed the latter
better.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Junio C Hamano wrote:

> Yes.  The current "merge" started its life as Linus's porcelain
> (we did not have fetch and pull infrastructure back then) but
> quickly has become just a helper for pull to produce a merge
> commit.  If anybody thinks its UI is good as a general end-user
> level command, there is a need for "head examination".

If you mean "git merge" it sure needs to be brought forward.  It can't 
be clearer than:

	git-merge the_other_branch

or

	git-merge git://repo.com/time_machine.git

to instantaneously understand what is going on.

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Nicolas Pitre wrote:

> On Tue, 14 Nov 2006, Junio C Hamano wrote:
> 
>> Yes.  The current "merge" started its life as Linus's porcelain
>> (we did not have fetch and pull infrastructure back then) but
>> quickly has become just a helper for pull to produce a merge
>> commit.  If anybody thinks its UI is good as a general end-user
>> level command, there is a need for "head examination".
> 
> If you mean "git merge" it sure needs to be brought forward.  It can't 
> be clearer than:
> 
>       git-merge the_other_branch
> 
> or
> 
>       git-merge git://repo.com/time_machine.git
> 
> to instantaneously understand what is going on.

You mean

      git merge git://repo.com/time_machine.git#branch

don't you (perhaps with 'master' as default branch)?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Santi Béjar]

On 11/15/06, Jakub Narebski <jnareb@gmail.com> wrote:
> Nicolas Pitre wrote:
>
> > On Tue, 14 Nov 2006, Junio C Hamano wrote:
> >
> >> Yes.  The current "merge" started its life as Linus's porcelain
> >> (we did not have fetch and pull infrastructure back then) but
> >> quickly has become just a helper for pull to produce a merge
> >> commit.  If anybody thinks its UI is good as a general end-user
> >> level command, there is a need for "head examination".
> >
> > If you mean "git merge" it sure needs to be brought forward.  It can't
> > be clearer than:
> >
> >       git-merge the_other_branch
> >
> > or
> >
> >       git-merge git://repo.com/time_machine.git
> >
> > to instantaneously understand what is going on.
>
> You mean
>
>       git merge git://repo.com/time_machine.git#branch
>
> don't you (perhaps with 'master' as default branch)?

perhaps with remote 'HEAD' as default branch?

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Santi Béjar wrote:

> On 11/15/06, Jakub Narebski <jnareb@gmail.com> wrote:

>> You mean
>>
>>       git merge git://repo.com/time_machine.git#branch
>>
>> don't you (perhaps with 'master' as default branch)?
> 
> perhaps with remote 'HEAD' as default branch?

No! HEAD might change without your notice, and you want to know
which branch you merge. With remotes the default could be first
branch in the pull/fetch list, but with bare URL...
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 11:28:27AM CET, Jakub Narebski wrote:
> Santi Béjar wrote:
> 
> > On 11/15/06, Jakub Narebski <jnareb@gmail.com> wrote:
> 
> >> You mean
> >>
> >>       git merge git://repo.com/time_machine.git#branch
> >>
> >> don't you (perhaps with 'master' as default branch)?
> > 
> > perhaps with remote 'HEAD' as default branch?
> 
> No! HEAD might change without your notice, and you want to know
> which branch you merge. With remotes the default could be first
> branch in the pull/fetch list, but with bare URL...

No! If HEAD changed without your notice, it means that the remote
repository admin _wants_ you to start fetching another branch now.
Imagine a setup of these branches:

	phooey-1.2	legacy lineage
	phooey-2.0	last stable
	phooey-3.0	current development (no releases yet)
	phooey-4.0	stash for futuristic functionality, heavily
			experimental

In this case, HEAD now points to phooey-3.0 but when it becomes stable,
it would change to phooey-4.0.

The common practice of having 'master' pointing on whatever you
currently have now and and "cutting out" the branches from it at random
times is something heavily influenced by CVS where this is the only sane
way of branching (the cutting out even hardcoded in numbering scheme).
In more advanced systems, you may want to be much more flexible wrt. this
(note that I'm not saying you necessarily _should_ be).

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Jakub Narebski wrote:

> Nicolas Pitre wrote:
> 
> > On Tue, 14 Nov 2006, Junio C Hamano wrote:
> > 
> >> Yes.  The current "merge" started its life as Linus's porcelain
> >> (we did not have fetch and pull infrastructure back then) but
> >> quickly has become just a helper for pull to produce a merge
> >> commit.  If anybody thinks its UI is good as a general end-user
> >> level command, there is a need for "head examination".
> > 
> > If you mean "git merge" it sure needs to be brought forward.  It can't 
> > be clearer than:
> > 
> >       git-merge the_other_branch
> > 
> > or
> > 
> >       git-merge git://repo.com/time_machine.git
> > 
> > to instantaneously understand what is going on.
> 
> You mean
> 
>       git merge git://repo.com/time_machine.git#branch
> 
> don't you (perhaps with 'master' as default branch)?

Something like that.  I wantee to enphasize on the "merge" command that 
should deal with, hey, merges.

I don't know if # is a good choice for branch indicator though.

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 05:33:03AM CET, Junio C Hamano wrote:
> Petr Baudis <pasky@suse.cz> writes:
> >   (v) Git would be properly libified by now. If you wanted to convert
> > bits of porcelain to C, it would be at least much higher priority.
> 
> I am not sure about "libified" part and I do not know what bits
> of porcelain wants to become C right now.  But I do not think
> this point is important part of your list.

Merge strategies. Or wait, is that already plumbing?

Or git-status. git-add. Plenty more.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Petr Baudis wrote:

>   (i) Clearly divided porcelain/plumbing interface, so that you can
> really isolate the two UI-wise; endless confusion reigns there now. Is
> git-update-index porcelain or plumbing? _You_ call git-merge a proper
> porcelain? From my perspective, git-update-ref is as plumbing as it
> gets, but it's classified as porcelain. Etc, etc. This would be by far
> the most important advantage.

The problem is that one man's plumbing is another man porcelain.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Karl Hasselström]

On 2006-11-15 11:05:26 +0100, Jakub Narebski wrote:

> The problem is that one man's plumbing is another man porcelain.

No; that way lies insanitation.

-- 
Karl Hasselström, kha@treskal.com

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 6788 bytes --]

On Tue, 14 Nov 2006 16:31:50 -0800, Junio C Hamano wrote:
> I do not think the Porcelain-ish UI that is shipped with git
> should be taken with the same degree of "authority" as git
> Plumbing.

I think we should fix this. "This is great technology with a crap
interface on top" really isn't a good story. I don't actually agree
with that---I don't think the git interface is really all that bad,
it's just got a few little things that tend to trip up new users in my
experience.

And what git does really well, (history exploring, allowing for
pipeline on-liners to iterate over revisions in A..B), are things that
don't even exist in other tools, nor even in the "alternate"
porcelains for git. This stuff is where git's interface is really
fantastic, and it would be a shame to write it off.

>                                                        I think
> single isolated developers, contributors and CVS style shared
> repository usage could be a lot improved because neither of us
> were concentrating in their workflows.  This needs somebody
> motivated enough to improve things in that area.  For example,
> StGIT with its 'float' command is a great improvement over what
> rebase does for people in the contributor role.

Yes, there are some specific workflow-oriented operations that git
doesn't handle as well as it could. Things like commit --amend are
certainly improvements. One that is still totally broken is "follow
all the development in another repository" where clone followed by
repeated fetch doesn't do the job as soon as the remote adds or
deletes a branch.

> But making it more usable for whom is a big question.
>
> Quite frankly, I do not think there can be _the_ single UI that
> would satisfy different types of workflows for some of the
> commands.

I strongly disagree. Or at least, I don't think we've tried hard
enough yet that we should give up on this.

I do agree that people in different roles will have different lists of
"most used operations" and that some operations won't appear on some
users lists at all, (someone who's just "watching" development won't
commit or merge, for example---[or so they thing when they start]).

But I really don't think that for any given operation that different
roles impose a different desire on the behavior of the operation. We
have different people with different background and disagreement on
names and silly things like that, but I don't think that's related to
the roles in which they are working with the tool.

> For example, fetching and merging from many places without
> necessarily having corresponding tracking branches is a great
...

I don't think we've ever had this right in git. The new
--use-separate-remotes stuff or similar will start to help as it
becomes the default. I don't see how this won't benefit everybody.

> For another example, having a commit command to commit
> everything by default is disastrous for people who allow their
> workflows to often be interrupted.

Workflow-interruption is an important thing to support, but separating
update-index and commit really doesn't address it nearly as much as I
would like. The lack of really good workflow-interruption support has
been one of my longest-running annoyances with git, (perhaps because I
have a problem with trying to do too many things at once). Git can
create and change branches fast enough that it really should be able
to help me better with this. The only missing piece is being able to
stash the dirty stuff on the current branch, to be able to come back
to it later. I've talked a bit about what I would like in this area
before, and I really just need to code it up.

> It is not just command line syntax and the defaults, but
> concepts as well.  People in the integrator role often need to
> deal with merges and you would need to be aware of the role of
> the index and need to be able to manipulate the index, ...

Again, I think it's more that the specific operations bring in
concepts, (merge bringing in the index here). As such, someone never
doing a merge could easily get by not having to understand the index.

> A Porcelain that does a very similar thing in slightly different
> way is obviously a waste, but otherwise I do not think it is a
> problem to have different Porcelains.  StGIT does not compete
> with the "sucky" Porcelain-ish shipped with git but makes the
> user's life a lot more pleasant by complementing what the sucky
> one does not do well.  It is not very useful while I am playing
> the integrator role, but when I am doing my own thing it is a
> great addition to my toolchest.

But even here, there's a bunch of waste in StGit. For example, there
are a lot of commands in StGit whose only purpose is to translate back
and forth between the StGit and non-StGit views of the world, (init,
assimilate, commit, uncommit). Those could all be discarded if the
functionality of StGit were brought down into git itself. Then there
are a myriad of StGit commands which are basically just the same as
their git counterparts.

Now, StGit is a great tool, and I know that it works really well for
some people in the role of just maintaining a stack of changes against
some upstream, and can use StGit alone and never touch "git" the
command-line.

But for someone like me who already uses git regularly, and
occasionally just wants to pop back a few commits, amend it, and then
push again, StGit is not helpful, (the series of init, assimilate, and
uncommits just to get started is prohibitive compared to just working
out the awkward steps needed to make a temporary branch and
rebase). So I'd love to see just a couple of commands added to "git"
to support these kinds of operations more smoothly.

> I am from the camp that does _not_ want to hide the index, so
> obviously I do not see any value in its effort to hide the
> index.  But other aspects of it, most notably being friendly to
> simpler workflows, is a very good thing.

I don't think "hide or not-to-hide" is the right way to frame the
discussion about the index. I regularly use update-index to stage
partial commits, and I find that very useful. And obviously the index
is involved in resolving merge conflicts.

But I don't think the user-interface for either of those operations
(partial commit, resolve conflicts), is ideal, and the current
requirement to use either "update-index <paths>" or "commit -a" after
modifying a file for the first time is demonstrably a hangup for a lot
of new users. So I really think it's possible to address both of these
at once.

Anyone, that's enough generic rambling from me without any specific
content. I'll try to keep future messages focused on specific
desirable operations that have problematic interfaces in git right
now, along with proposals for improving them.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Carl Worth wrote:
>On Tue, 14 Nov 2006 16:31:50 -0800, Junio C Hamano wrote:
>>
>> For another example, having a commit command to commit
>> everything by default is disastrous for people who allow their
>> workflows to often be interrupted.
> 
> Workflow-interruption is an important thing to support, but separating
> update-index and commit really doesn't address it nearly as much as I
> would like. The lack of really good workflow-interruption support has
> been one of my longest-running annoyances with git, (perhaps because I
> have a problem with trying to do too many things at once). Git can
> create and change branches fast enough that it really should be able
> to help me better with this. The only missing piece is being able to
> stash the dirty stuff on the current branch, to be able to come back
> to it later. I've talked a bit about what I would like in this area
> before, and I really just need to code it up.

There is git-stash/git-unstash floating somewhere in the archive.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Jakub Narebski <jnareb@gmail.com> wrote:
> Carl Worth wrote:
> >On Tue, 14 Nov 2006 16:31:50 -0800, Junio C Hamano wrote:
> >>
> >> For another example, having a commit command to commit
> >> everything by default is disastrous for people who allow their
> >> workflows to often be interrupted.
> > 
> > Workflow-interruption is an important thing to support, but separating
> > update-index and commit really doesn't address it nearly as much as I
> > would like. The lack of really good workflow-interruption support has
> > been one of my longest-running annoyances with git, (perhaps because I
> > have a problem with trying to do too many things at once). Git can
> > create and change branches fast enough that it really should be able
> > to help me better with this. The only missing piece is being able to
> > stash the dirty stuff on the current branch, to be able to come back
> > to it later. I've talked a bit about what I would like in this area
> > before, and I really just need to code it up.
> 
> There is git-stash/git-unstash floating somewhere in the archive.

I find that a "git commit -a -m parked; git checkout -b ..." works
well to stash my current stuff off.  Then I just amend the commit
when I come back to that branch.


The problem I just ran into today was "git checkout" doesn't double
check the file stat data against the index before switching branches.
If the file is unchanged between the two branches there's no error.
So I switched branches with dirty files that I forgot to park on
the old branch.

-- 

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 1136 bytes --]

On Wed, 15 Nov 2006 17:00:54 -0500, Shawn Pearce wrote:
> > There is git-stash/git-unstash floating somewhere in the archive.

Yes, I did write those once upon a time. ;-)

It's the manual stash/unstash that I don't want though. I want to be
able to make this happen automatically when switching branches.

> I find that a "git commit -a -m parked; git checkout -b ..." works
> well to stash my current stuff off.  Then I just amend the commit
> when I come back to that branch.

Yes, I do stuff like that as well. And often "reset HEAD~" instead of
amend, (always with a moment's pause as reset justly deserves).

> The problem I just ran into today was "git checkout" doesn't double
> check the file stat data against the index before switching branches.
> If the file is unchanged between the two branches there's no error.
> So I switched branches with dirty files that I forgot to park on
> the old branch.

Right, so that's just more evidence that this approach is a little
awkward.

Anyway, the stashing thing I want is a minor thing that should be easy
to fix in git, (as is everything we're talking about here I think).

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Steven Grimm]

Jumping into this a day late, but:

Carl Worth wrote:
> I don't see any defining difference that justifies cogito's
> existence ("hide the index" maybe? let's just hide it a tiny bit more
> in git). And I would like to help work to get the remaining good
> stuff that has been proven in cogito---to get it pushed down into git
> itself.
>   

Agreed totally on the second point. It would be great if git natively 
supported everything people use in Cogito.

I find myself using native git commands for the most part, except for 
one Cogito command: "cg-update". It is vastly more convenient than 
git-pull in large part because it automatically merges upstream changes 
with uncommitted working-copy changes. I suppose you could classify this 
as "hide the index" in some sense.

Maybe I should give an example of what I mean. Suppose I have two child 
repositories (owned by different developers, say):

cg-clone repo child1
cg-clone repo child2

Now I go into both of them and make different (hopefull non-conflicting) 
edits to the same file.

echo foo >> child1/testfile
perl -pi -e 's/tree/shrub/' child2/testfile

I push the change from child1 into the integration repo.

cd child1
git-commit -a
git-push

Now I want to incorporate the change into child2, where I'm still doing 
work. With Cogito, I go to child2 and run:

cg-update

and afterwards, the upstream changes are merged into testfile and "git 
diff" still shows my local edits. With Git native commands, updating 
child2 if I'm not ready to commit yet is more like:

git-diff --binary > /tmp/patch
git-reset --hard
git-pull
git-apply /tmp/patch

I might have gotten that slightly wrong, but I think I have the general 
idea right; in any event, it's not nearly as convenient! The alternative 
is to commit then pull, but then when I want to look at my local edits, 
I have to remember to diff my working copy against the correct revision, 
which gets increasingly annoying if I update more than once.

Like others on this list, I'm also trying to sell an existing user base 
(in this case, they're using Subversion) on Git. The lack of a built-in 
equivalent to "svn update" is actually a pretty big UI annoyance for 
people whose workflow doesn't require git's more sophisticated feature 
set at a given point in time. Even a sophisticated user doesn't need the 
full power of the tool 100% of the time, so this isn't just a novice vs. 
expert thing in my opinion.

Absent Cogito, would the lack of a simple "svn update" equivalent be a 
deal-killing "throw your hands up in disgust and give up" thing? Maybe 
not, but it's a daily "ugh, why am I having to type extra commands to do 
something that only took one command in svn?" thing. So it's nice to 
have Cogito to paper over that particular wart.

If there is a native git equivalent to cg-update including the 
working-copy automatic merges, I'll be delighted to stand corrected!

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Steven Grimm <koreth@midwinter.com> writes:

> echo foo >> child1/testfile
> perl -pi -e 's/tree/shrub/' child2/testfile
>...
> git-diff --binary > /tmp/patch
> git-reset --hard
> git-pull
> git-apply /tmp/patch
>
> I might have gotten that slightly wrong, but I think I have the
> general idea right.

stg pull would help you in such a situation as well, but I see
what you mean.

Just like we have an explicit -m option to "checkout" to allow
file-level merging of local changes, I think it is reasonable to
hav an option that allows file-level merging of local changes
when doing a pull that you _know_ will not conflict.

When there will be a conflict between your HEAD and MERGE_HEAD
even without your local changes, you somehow need to sort out
the resulting mess that come from conflicts due to the branch
diversion (i.e. log HEAD...MERGE_HEAD) and conflicts between
your local change and what the other branch did.  The resulting
merge commit obviously needs to record resolutions only to the
former and should not even record anything you did locally,
conflicted or not.  Which is a pain for the end user and giving
them a way to revert to the state before this three-and-half
way merge started also needs to be there.

Unfortunately the only way to know if there will be a file-level
conflict is to try one, and stashing away the current state just
in case it conflicted is a performance penalty, so this probably
should stay as an option just like "-m" to the "checkout".

But the basic mechanism to do this three-and-half way merge is
simple and I have no objection if somebody wanted to add such an
option to "git pull".

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Fri, Nov 17, 2006 at 10:35:04PM CET, Junio C Hamano wrote:
> Unfortunately the only way to know if there will be a file-level
> conflict is to try one, and stashing away the current state just
> in case it conflicted is a performance penalty, so this probably
> should stay as an option just like "-m" to the "checkout".

I think it would be just great if it worked at least for fast-forwarding
case; I think this is where it is actually most useful. Cogito tries to
support even the three-way case as long as the changes touch different
files, but I'm not sure if it was a good idea to begin with.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Karl Hasselström]

On 2006-11-14 11:22:39 -0800, Carl Worth wrote:

> So, the fact that conflict resolution still requires the use of
> update-index would just be the next thing to fix. A name for a
> replacement to use there could be "git resolve <paths>", (since the
> old git-resolve is now officially deprecated). That's a name that
> matches what hg uses in this situation, (another option is
> "resolved" which is what stg uses, but I think verbs for commands
> work better in general).

Yes, "resolve" sounds better than "resolved". The latter is arguably
more correct, since you're telling git that you have already resolved
the file and not asking it to resolve it for you, but I still prefer
"resolve".

> And then, the next phase of my evil plan would be to introduce a -i
> option for git-commit making it commit the state in the index. Then
> git-commit with no options could work like "git-commit -a" does now,
> (with the additional protection of not committing any unmerged
> files---that is the new "git resolve" would be required before "git
> commit" would work after a conflict). Users who really, really like
> the current behavior of git-commit could use the new alias support
> to pass the new -i option in order to maintain compatible behavior.

Seems very sane. Default to simple behavior, and provide a switch to
get more complicated behavior.

> Then, the last thing I'd really like to fix is to allow a usage of
> "git merge <branch>" instead of the awkward "git pull . <branch>".

This should reduce newbie confusion a lot.

-- 
Karl Hasselström, kha@treskal.com

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Carl Worth wrote:

> Anyway, now I've just gone and blown all my secret plans for changing
> git in ways to make it less intimidating for new users.

I just cannot do otherwise than cheer this with applause.

Even if I have a clear preference for GIT's _technology_, I still think 
that the HG user interface is more convivial.  I even been thinking 
about writing something like an hg-like frontend to GIT from time to 
time just so that GIT could then be better compared to (and actually 
just used like) HG.

I still think that the GIT user interface sucks in many ways.  The 
confusion between pull, fetch and push is still my favorite, along with 
the locale vs remote branch issue.  Maybe we'll better handle the branch 
issue eventually, but it would be so much intuitive to split branch 
merging out of git-pull, and make git-pull be the same as git-fetch 
(maybe deprecating git-fetch in the process) so push and pull are really 
_only_ opposite of each other.

If the fetch+merge behavior (which I think should really be refered as 
pull+merge) is still desirable, then it should be called git-update and 
be no more than a single shell script line such as

	git_pull && git_merge"

This is really what most people expect from such a command name based 
on obvious historical reasons.  The lack of any branch argument to 
git-pull and git-merge could be defined as using the first defined 
remote branch by default.  But having git-pull performing merges is IMHO 
overloading the word and goes against most people's expectations.

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Nicolas Pitre wrote:

> If the fetch+merge behavior (which I think should really be refered as 
> pull+merge) is still desirable, then it should be called git-update and 
> be no more than a single shell script line such as
> 
>         git_pull && git_merge"
> 
> This is really what most people expect from such a command name based 
> on obvious historical reasons.  The lack of any branch argument to 
> git-pull and git-merge could be defined as using the first defined 
> remote branch by default.  But having git-pull performing merges is IMHO 
> overloading the word and goes against most people's expectations.

By the way, is anyone doing _remote_ octopus pull (true pull, not with . as
repository)?

We can always have --merge arguments to git-pull, and --fetch argument to
git-merge.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1241 bytes --]

On Tue, 14 Nov 2006, Jakub Narebski wrote:

> Nicolas Pitre wrote:
> 
> > If the fetch+merge behavior (which I think should really be refered as 
> > pull+merge) is still desirable, then it should be called git-update and 
> > be no more than a single shell script line such as
> > 
> >         git_pull && git_merge"
> > 
> > This is really what most people expect from such a command name based 
> > on obvious historical reasons.  The lack of any branch argument to 
> > git-pull and git-merge could be defined as using the first defined 
> > remote branch by default.  But having git-pull performing merges is IMHO 
> > overloading the word and goes against most people's expectations.
> 
> By the way, is anyone doing _remote_ octopus pull (true pull, not with . as
> repository)?
> 
> We can always have --merge arguments to git-pull, and --fetch argument to
> git-merge.

That would be a complete abomination if you want my opinion.

Please let git-pull actually pull stuff from a remote place, and 
git-merge actually merge stuff only.  Let's keep simple concepts mapped 
to simple commands please.  Nothing prevents _you_ from scripting more 
involved operations with a single command of your liking afterwards.


Nicolas

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Nicolas Pitre wrote:
> On Tue, 14 Nov 2006, Jakub Narebski wrote:

>> We can always have --merge arguments to git-pull, and --fetch argument to
>> git-merge.
> 
> That would be a complete abomination if you want my opinion.
> 
> Please let git-pull actually pull stuff from a remote place, and 
> git-merge actually merge stuff only.  Let's keep simple concepts mapped 
> to simple commands please.  Nothing prevents _you_ from scripting more 
> involved operations with a single command of your liking afterwards.

Do we want to abandon completely "single-branch" workflow, where you
don't use tracking branch, only merge directly into your working branch?
That is the cause to (unused by most) future git-merge (replacement for
git-pull .) --fetch=<remote>[#<branch>] option.

I'm not that sure about --merge option, but it could be useful, at least
to have current automatic "Merge branch '<branch>' of <URL>" commit message.
-- 
Jakub Narebski

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Jakub Narebski wrote:

> Nicolas Pitre wrote:
> > On Tue, 14 Nov 2006, Jakub Narebski wrote:
> 
> >> We can always have --merge arguments to git-pull, and --fetch argument to
> >> git-merge.
> > 
> > That would be a complete abomination if you want my opinion.
> > 
> > Please let git-pull actually pull stuff from a remote place, and 
> > git-merge actually merge stuff only.  Let's keep simple concepts mapped 
> > to simple commands please.  Nothing prevents _you_ from scripting more 
> > involved operations with a single command of your liking afterwards.
> 
> Do we want to abandon completely "single-branch" workflow, where you
> don't use tracking branch, only merge directly into your working branch?

I really think we should.  Let's admit it: such a work flow has nothing 
to do with the tool.  It would certainly be much easier to teach new 
users about "this is a read-only view of the remote content that you can 
merge into your working branch" than trying to explain why the tool is 
so weird for the sake of supporting different work flows directly.

Again I think it is easier to grasp two simple commands than a single 
but complex one with multiple ramifications.

> That is the cause to (unused by most) future git-merge (replacement for
> git-pull .) --fetch=<remote>[#<branch>] option.
> 
> I'm not that sure about --merge option, but it could be useful, at least
> to have current automatic "Merge branch '<branch>' of <URL>" commit message.

A "remote" branch should obviously have a corresponding URL.  So if you 
do "git-merge remote" then you may as well prepare a commit message with 
that URL given the local name for that branch if you want.

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 2611 bytes --]

On Tue, 14 Nov 2006 15:52:47 -0500 (EST), Nicolas Pitre wrote:
> Even if I have a clear preference for GIT's _technology_, I still think
> that the HG user interface is more convivial.  I even been thinking
> about writing something like an hg-like frontend to GIT from time to
> time just so that GIT could then be better compared to (and actually
> just used like) HG.

I've actually been tempted to do the same myself. I really think that
the technology is a more important criterion than the UI so the
imagined hg-on-git interface would be an attempt to get people to look
past the interface differences and look at the technology when
deciding.

But, then, I'd be guilty of creating another cogito, and I just argued
against its existence in a separate thread. So I think we're better
off just fixing the git interface.

> I still think that the GIT user interface sucks in many ways.  The
> confusion between pull, fetch and push is still my favorite, along with
> the locale vs remote branch issue.  Maybe we'll better handle the branch
> issue eventually,

The --use-separate-remotes thing is technology in the right direction
here. But I think it's another example of very useful stuff being
improperly hidden behind another command-line option. Getting rid of
the "remote-tracking branches" as user-visible branches possible for
committing should be a priority. And that should be the default for
everyone, not just people who happen to clone with this obscure
option.

Similarly, the reflog stuff was often trumpeted in the recent git
vs. bzr debate. Why is that very useful functionality buried in a
config file option and not just stored by default?

> This is really what most people expect from such a command name based
> on obvious historical reasons.  The lack of any branch argument to
> git-pull and git-merge could be defined as using the first defined
> remote branch by default.

Once again, there's lots of useful work on "branch configuration" that
allows for commands to be able to get the "right" default repository
for push and pull. I hope that that stuff can be enabled by default
and not require --use-separate-remotes or manual configuration for
people to benefit from it.

I apologize if I sound like I'm ranting here. I love to see the many
good improvements being made to git. It's just that there seems to be
a sort of shyness about new features, (perhaps a fear of changing
existing behavior?). When it improves the user experience, let's make
the improvement the default and not add any more

	--make-this-command-do-what-it-really-should-have-always-done

options.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Jakub Narebski]

The git interface refactoring should be I think the cause for git 2.0.0
release...

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Jakub Narebski wrote:

> The git interface refactoring should be I think the cause for git 2.0.0
> release...

Good idea indeed.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> On Tue, 14 Nov 2006, Jakub Narebski wrote:
>
>> The git interface refactoring should be I think the cause for git 2.0.0
>> release...
>
> Good idea indeed.

We need to avoid user confusion, so making a command that used
to do one thing to suddenly do something completely different is
a no-no.  However, I do not think it needs to wait for 2.0.0.
We can start with a separate namespace (or even a separate
"Improved git UI project") and introduce the "improved UI set"
in 1.5.0 timeframe.

If managed properly, the "improved git UI" can coexist with the
current set of tools and over time we can give an option not to
even install the older Porcelain-ish commands.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > On Tue, 14 Nov 2006, Jakub Narebski wrote:
> >
> >> The git interface refactoring should be I think the cause for git 2.0.0
> >> release...
> >
> > Good idea indeed.
> 
> We need to avoid user confusion, so making a command that used
> to do one thing to suddenly do something completely different is
> a no-no.  However, I do not think it needs to wait for 2.0.0.
> We can start with a separate namespace (or even a separate
> "Improved git UI project") and introduce the "improved UI set"
> in 1.5.0 timeframe.

Dunno.  I feel this is a bit overboard.  Actually the naming problem is 
rather localized to one command, namely git-pull.  In my opinion going 
with yet another namespace which would rather add to the confusion not 
clear it.

The best way to avoid user confusion is to remove the source of the 
confusion not let it live.  In other words I think we should _fix_ 
git-pull instead of replacing it.  People are already confused about it 
so simply fixing this command will have a net confusion reduction.  Yet 
we're not talking about "suddenly doing something completely different" 
either.  If git-pull doesn't merge automatically anymore it is easy to 
tell people to use git-merge after a pull.

"You pull the remote changes with 'git-pull upstream,, then you can 
merge them in your current branch with 'git-merge upstream'."

Isn't it much simpler to understand (and to teach) that way?

Also I don't think using git-upload and git-download is much better.  
This adds yet more commands that do almost the same as existing ones but 
with a different name which is yet not necessarily fully adequate.  I 
for example would think that "download" is more like git-clone than 
git-fetch or git-pull.

Let's face it: HG got it right with pull and push and newbies have much 
less difficulty grokking it.  We screwed it by not using the most 
intuitive semantic of a pull and locking the word "pull" away is not the 
better solution given all considerations. Why just not admit it and 
avoid being different than HG just for the sake of it?

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> "You pull the remote changes with 'git-pull upstream,, then you can 
> merge them in your current branch with 'git-merge upstream'."
>
> Isn't it much simpler to understand (and to teach) that way?

If it were "you download the remote changes with 'git download
upstream' and then merge with 'git merge'", then perhaps, but if
you used the word "pull" or "fetch", I do not think so.

I would be all for changing the semantics of "pull" from one
thing to another, if the new semantics were (1) what everybody
welcomed, (2) what "pull" traditionally meant everywhere else.
In that case, we have been misusing it to be confusing to
outsiders and I agree it makes a lot of sense to remove the
source of confusion.  But I do not think CVS nor SVN ever used
the term, and I was told that BK was what introduced the term,
and the word meant something different from what you are
proposing.

You have to admit both pull and fetch have been contaminated
with loaded meanings from different backgrounds. I was talking
about killing the source of confusion in the longer term by
removing fetch/pull/push, so we are still on the same page.

That's where my "you download from the upstream and merge" comes
from.

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

I would kind of like to see "git poll" -- visit all remote branches,
fetching objects and tags into the local repository, so that I can
inspect changes off-line and merge, cherry-pick, etc. to my heart's
content.  That would fit the platform integrator's workflow nicely --
"git poll" into a tracking tree, do some merges there (such as
backporting a subsystem to a "stable" base kernel), then merge this
backport branch to each platform working copy and cherry-pick other
changes as necessary.

Cheers,

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > "You pull the remote changes with 'git-pull upstream,, then you can 
> > merge them in your current branch with 'git-merge upstream'."
> >
> > Isn't it much simpler to understand (and to teach) that way?
> 
> If it were "you download the remote changes with 'git download
> upstream' and then merge with 'git merge'", then perhaps, but if
> you used the word "pull" or "fetch", I do not think so.
> 
> I would be all for changing the semantics of "pull" from one
> thing to another, if the new semantics were (1) what everybody
> welcomed, (2) what "pull" traditionally meant everywhere else.
> In that case, we have been misusing it to be confusing to
> outsiders and I agree it makes a lot of sense to remove the
> source of confusion.  But I do not think CVS nor SVN ever used
> the term, and I was told that BK was what introduced the term,
> and the word meant something different from what you are
> proposing.
> 
> You have to admit both pull and fetch have been contaminated
> with loaded meanings from different backgrounds. I was talking
> about killing the source of confusion in the longer term by
> removing fetch/pull/push, so we are still on the same page.
> 
> That's where my "you download from the upstream and merge" comes
> from.

But the fact is that HG (which has a growing crowd of happy campers, 
maybe even larger than the BK crowd now) did work with and got used to a 
sensible definition of what a "pull" is.  This means that their 
definition is becoming rather more relevant with time than what it used 
to, and because it is a saner definition than what GIT has for the same 
word which HG users really have no issue with, I think we really should 
leverage the "common wisdom" and consider aligning ourselves with them 
in this case rather than trying to go into a totally different 
direction.  We simply won't gain anything trying to teach people "a pull 
in HG is a download in GIT".  If a pull becomes the same thing for both 
then it's one less oddball in the GIT interface.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> ...  We simply won't gain anything trying to teach people "a pull 
> in HG is a download in GIT".  If a pull becomes the same thing for both 
> then it's one less oddball in the GIT interface.

I personally do not have any issue with that, as long as you
would help us convert existing users that what was known as pull
is not available and new pull means fetching only.

If I recall correctly in this thread, you also advocated to
always have tracking branches.  I am a bit worried about losing
the promiscuous pull usage, which can easily become a regression
for people like Linus in the integrator role unless done with an
escape hatch.

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Tue, 14 Nov 2006, Nicolas Pitre wrote:
> 
> But the fact is that HG (which has a growing crowd of happy campers, 
> maybe even larger than the BK crowd now) did work with and got used to a 
> sensible definition of what a "pull" is.

Guys, before you start thinking this way, the fact is, there's a lot of 
happy git users. 

So the reason for using "git pull" is

 - bk did it that way, and like it or not, bk was the first usable 
   distributed system. hg is totally uninteresting.

 - git itself has now done it that way for the last 18 months, and the 
   fact is, the people _complaining_ are a small subset of the people who 
   actually use git on a daily basis and don't complain.

So don't fall for the classic "second system syndrome". The classic reason 
for getting the second system wrong is because you focus on the issues 
people complain about, and not on the issues that work well (because the 
issues that work fine are obviously not getting a lot of attention).

If you think "pull" is confusing, I can guarantee you that _changing_ the 
name is a hell of a lot more confusing. In fact, I think a lot of the 
confusion comes from cogito, not from git - the fact that cogito used 
different names and different syntax was a mistake, I think.

And that '#' for branch naming in particular was (and is) total 
braindamage. The native git branch naming convention is just fundamentally 
much better, and allows you to very naturally fetch multiple branches at 
once, in a way that cogito's syntax does not.

So when I see suggestions of using that brain-damaged cogito syntax as an 
"improvement", I know for a fact that somebody hasn't thought things 
through, and only thinks it's a better syntax beause of totally bogus 
reasons.

I do agree that we probably could/should re-use the "git merge" name. The 
current "git merge" is an esoteric internal routine, and I doubt a lot of 
people use it as-is. I don't think it would be a mistake to make "git 
merge" basically be an alias for "git pull", for example, and I doubt many 
people would really even notice.

But the fact is, git isn't really that hard to work out, and the commands 
aren't that complicated. There's no reason to rename them. We do have 
other problems:

 - default branch selection for merging is broken (it should definitely 
   take the current branch into account). When I do "git pull" with no 
   branch specification, and I happen to be on a branch that is associated 
   with something else than "master" in the remote, I shouldn't merge with 
   master.

 - I agree that having to create temporary branches to just look at a tag 
   that you don't want to actually develop on is just unnecessarily 
   bothersome.

But trying to rename "pull" (or the "git" name itself) is just going to 
cause more confusion than you fix.

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Linus Torvalds wrote:

> But the fact is, git isn't really that hard to work out, and the commands 
> aren't that complicated. There's no reason to rename them. We do have 
> other problems:
> 
>  - default branch selection for merging is broken (it should definitely 
>    take the current branch into account). When I do "git pull" with no 
>    branch specification, and I happen to be on a branch that is associated 
>    with something else than "master" in the remote, I shouldn't merge with 
>    master.

This problem is _slightly_ migitated by branch.<name>.merge config variable.
Slightly because you have to specify branch to merge, instead of forbidding
merge if you are not on specific branch (and you don't override it).

>  - I agree that having to create temporary branches to just look at a tag 
>    that you don't want to actually develop on is just unnecessarily 
>    bothersome.

Agreed.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Josef Weidendorfer]

On Wednesday 15 November 2006 19:28, you wrote:
> Linus Torvalds wrote:
> 
> > But the fact is, git isn't really that hard to work out, and the commands 
> > aren't that complicated. There's no reason to rename them. We do have 
> > other problems:
> > 
> >  - default branch selection for merging is broken (it should definitely 
> >    take the current branch into account). When I do "git pull" with no 
> >    branch specification, and I happen to be on a branch that is associated 
> >    with something else than "master" in the remote, I shouldn't merge with 
> >    master.
> 
> This problem is _slightly_ migitated by branch.<name>.merge config variable.
> Slightly because you have to specify branch to merge, instead of forbidding
> merge if you are not on specific branch (and you don't override it).

We should change this.

The problem is that whatever is the first Pull line in remotes config gets
merged by default into current branch, which most often is not the right
thing to do.

Often, I find myself doing "git branch" just to make sure that I am on
"master", so that a following pull does not do a bogus merge.

Can we please disable this behavior, e.g. by allowing a fake first
Pull line like "Pull: (not-for-merge)" to prohibit any merge?

This even could be written by default in git-clone somewhere in the future,
and we suddenly get the behavior of pull being symmetric to push - at least
by default. And still, it is fully compatible to existing repositories.

To make pull do the right thing, we _have_ to configure branch.<name>.merge
whenever we create a new branch (which matters for git-clone, too).

Josef

> 
> >  - I agree that having to create temporary branches to just look at a tag 
> >    that you don't want to actually develop on is just unnecessarily 
> >    bothersome.
> 
> Agreed.

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 09:31:13PM CET, Josef Weidendorfer wrote:
> Often, I find myself doing "git branch" just to make sure that I am on
> "master", so that a following pull does not do a bogus merge.
> 
> Can we please disable this behavior, e.g. by allowing a fake first
> Pull line like "Pull: (not-for-merge)" to prohibit any merge?

Wait, if you don't want pull to merge, why do you pull and not fetch?

(Disclaimer: I'm not intimately familiar with git pull/fetch and I
didn't read the whole thread yet.)

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Josef Weidendorfer]

On Wednesday 15 November 2006 21:35, Petr Baudis wrote:
> On Wed, Nov 15, 2006 at 09:31:13PM CET, Josef Weidendorfer wrote:
> > Often, I find myself doing "git branch" just to make sure that I am on
> > "master", so that a following pull does not do a bogus merge.
> > 
> > Can we please disable this behavior, e.g. by allowing a fake first
> > Pull line like "Pull: (not-for-merge)" to prohibit any merge?
> 
> Wait, if you don't want pull to merge, why do you pull and not fetch?

I am not really opposed to pull doing a merge. It only should work in
a useful way: ie. only do the merge of updated origin branch when
current branch is master (given "Pull: master:origin").

I want "git pull" being harmless if I find myself accidently on a
branch != master. I always can do "git checkout master; git pull . origin"
afterwards.

For this to work, I currently need to specify a "branch.<name>.merge"
config for _every_ branch I have, as otherwise I get this bogus pull
merge behavior. This is not needed if there was a way to configure no
merge at all as default pull behavior.

I just noted that allowing such a config option would be kind of a
working compromise for all the people which want
pull to be the opposite of push.

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Josef Weidendorfer wrote:
> 
> I am not really opposed to pull doing a merge. It only should work in
> a useful way: ie. only do the merge of updated origin branch when
> current branch is master (given "Pull: master:origin").

I absolutely agree.

We should _only_ use the default head when pulling from the default head 
("master"). If we don't pull from within the default branch, we should 
either require an explicit head _or_ we should require that an explicit 
mapping has been set up in .git/config or in .git/remotes/..

So doing a "git pull" from any other branch than "master" should probably 
by default say "which branch do you want to pull from today"?

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Linus Torvalds wrote:

> 
> 
> On Tue, 14 Nov 2006, Nicolas Pitre wrote:
> > 
> > But the fact is that HG (which has a growing crowd of happy campers, 
> > maybe even larger than the BK crowd now) did work with and got used to a 
> > sensible definition of what a "pull" is.
> 
> Guys, before you start thinking this way, the fact is, there's a lot of 
> happy git users. 
> 
> So the reason for using "git pull" is
> 
>  - bk did it that way, and like it or not, bk was the first usable 
>    distributed system. hg is totally uninteresting.
> 
>  - git itself has now done it that way for the last 18 months, and the 
>    fact is, the people _complaining_ are a small subset of the people who 
>    actually use git on a daily basis and don't complain.

Those arguments are somewhat flawed.  If we stick to "BK did it that way 
and it was first", then following that logic we would also carry a lot 
of CVS baggage because "CVS did it that way, and it was the most 
successful of its kind".  Still, we decided not to follow CVS nor BK in 
many ways already.

As for the fraction of people complaining being a small fraction of 
current GIT users: that is easily explainable by the fact that most 
people who would have grown the complainers group are simply not GIT 
users anymore since they were turned away by GIT's current user 
interface issues.  The only complainers remaining are those who see 
value in the GIT technology but who would like to bring more 
intuitiveness to the GIT interface instead of going for the alternative 
technology.  And those kind of people are always few.

> So don't fall for the classic "second system syndrome". The classic reason 
> for getting the second system wrong is because you focus on the issues 
> people complain about, and not on the issues that work well (because the 
> issues that work fine are obviously not getting a lot of attention).

The counter part of that is the possibility to fall for the "ivory tower 
syndrome" where seasoned GIT users feel they are well satisfied with 
what is currently available and unwilling to consider changes that would 
reduce the barrier to entry for new users... simply because they are so 
used to the way things work that they can't see why others have problems 
with it.

> If you think "pull" is confusing, I can guarantee you that _changing_ the 
> name is a hell of a lot more confusing.

Agreed.  This is why the current discussion led to a proposition that 
allows for "pull" to remain as is but to have a "get" version that would 
be the alternate (saner) version.

> In fact, I think a lot of the 
> confusion comes from cogito, not from git - the fact that cogito used 
> different names and different syntax was a mistake, I think.
> 
> And that '#' for branch naming in particular was (and is) total 
> braindamage. The native git branch naming convention is just fundamentally 
> much better, and allows you to very naturally fetch multiple branches at 
> once, in a way that cogito's syntax does not.
> 
> So when I see suggestions of using that brain-damaged cogito syntax as an 
> "improvement", I know for a fact that somebody hasn't thought things 
> through, and only thinks it's a better syntax beause of totally bogus 
> reasons.

Do you have comments on my proposed syntax (that would be implemented 
with a git-get command) which I think doesn't really look like cogito?

> I do agree that we probably could/should re-use the "git merge" name. The 
> current "git merge" is an esoteric internal routine, and I doubt a lot of 
> people use it as-is. I don't think it would be a mistake to make "git 
> merge" basically be an alias for "git pull", for example, and I doubt many 
> people would really even notice.

Agreed.

> But the fact is, git isn't really that hard to work out, and the commands 
> aren't that complicated.

I agree with you in general, except for the "pull" behavior which is 
really really odd.  Maybe it made sense in the BK context, maybe it is 
fine _once_ you get used to it, but otherwise it is really overloaded.

> But trying to rename "pull" (or the "git" name itself) is just going to 
> cause more confusion than you fix.

Agreed again.

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Nicolas Pitre <nico@cam.org> wrote:
> As for the fraction of people complaining being a small fraction of 
> current GIT users: that is easily explainable by the fact that most 
> people who would have grown the complainers group are simply not GIT 
> users anymore since they were turned away by GIT's current user 
> interface issues.  The only complainers remaining are those who see 
> value in the GIT technology but who would like to bring more 
> intuitiveness to the GIT interface instead of going for the alternative 
> technology.  And those kind of people are always few.

Or they are by proxy.

*I* don't see that much of a problem with git pull; I can use it
without trouble at this point.  But I find it difficult to teach
to others.

My complaints about git pull/fetch/push are by proxy for about 10
other users who aren't on the mailing list but whom I interact with
through Git.  They don't like pull/fetch/push very much.

So count my complaints 10 times.  :)

Ok, that's still a drop in the bucket of current Git users.
But still, I'm sure there are others.  I think Carl was recently
talking about complaints from some Fedora folks...

-- 

Re: Cleaning up git user-interface warts

[Marko Macek]

Shawn Pearce wrote:
> Nicolas Pitre <nico@cam.org> wrote:
>> As for the fraction of people complaining being a small fraction of 
>> current GIT users: that is easily explainable by the fact that most 
>> people who would have grown the complainers group are simply not GIT 
>> users anymore since they were turned away by GIT's current user 
>> interface issues.  The only complainers remaining are those who see 
>> value in the GIT technology but who would like to bring more 
>> intuitiveness to the GIT interface instead of going for the alternative 
>> technology.  And those kind of people are always few.
> 
> Or they are by proxy.
> 
> *I* don't see that much of a problem with git pull; I can use it
> without trouble at this point.  But I find it difficult to teach
> to others.
> 
> My complaints about git pull/fetch/push are by proxy for about 10
> other users who aren't on the mailing list but whom I interact with
> through Git.  They don't like pull/fetch/push very much.
> 
> So count my complaints 10 times.  :)
> 
> Ok, that's still a drop in the bucket of current Git users.
> But still, I'm sure there are others.  I think Carl was recently
> talking about complaints from some Fedora folks...

Agreed. Personally, the first thing that I notice when trying to switch
 from Subversion to git is the behavior of 'index', mainly in git-diff, git-status and 
git-commit.

For people switching from CVS and SVN it would be much better if the index was hidden 
behind the scenes by using different defaults:

git-commit -a
git-status -a
git-diff HEAD

BTW, currently there's a minor bug: git-diff HEAD doesn't work before you 
make the first commit. Perhaps this should be special cased.

I could personally get used to this, but I'd surely get blank 
stares from people when teaching them the difference.

I guess this is the reason that the GIT Tutorial for CVS/SVN users is talking about _cogito_ instead.
(which is very confusing for someone coming to _git_ home page, trying to learn git).

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Marko Macek <marko.macek@gmx.net> writes:

> For people switching from CVS and SVN it would be much better if the
> index was hidden behind the scenes by using different defaults:
>
> git-commit -a
> git-status -a
> git-diff HEAD
>
> BTW, currently there's a minor bug: git-diff HEAD doesn't work before
> you make the first commit. Perhaps this should be special cased.

That's only a _bug_ in your implementation of the synonym for
"svn diff" which blindly used "git diff HEAD".

"git diff HEAD" is not a synonym for "svn diff" when HEAD does
not exist yet, because you are asking "please give me a diff
between the tree in the HEAD commit and my working tree files
through the index".  So if you are doing "git-svnish-diff"
Porcelain script, it should notice that HEAD does not exist yet
and take an appropriate action.  We do something similar in
git-status; the porcelain notices and acts differently when HEAD
is not there yet.

This "there is no HEAD yet" is not related to the index, but I
am skeptical about trying to hide the index from the end user.

You can make some things map more naturally to systems like SVN
and CVS than other things.  For example, Nico's proposal to
always use remote tracking branches and defaulting to use
refs/remotes/ would be a way to match UI of pull/push to another
existing system and that would work well (I am not agreeing to
the change to make 'pull' not to do the merge which would break
existing users -- I am just saying that the result would be self
consistent).  But things that have difference at the concept
level, I suspect no clever mapping to hide the differences would
work well.

The index is quite central to the way git works at the concept
level, and I think it is doing disservice to the end user to try
hiding it forever from them and failing to do so, rather than
being honest and teaching them the concept upfront.

But me thinking so does not necessarily mean you are forbidden
from trying.  Your efforts may result in a system where the
index is totally invisible and the end user never has to know
about it.

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> The index is quite central to the way git works at the concept
> level, and I think it is doing disservice to the end user to try
> hiding it forever from them and failing to do so, rather than
> being honest and teaching them the concept upfront.
> 
> But me thinking so does not necessarily mean you are forbidden
> from trying.  Your efforts may result in a system where the
> index is totally invisible and the end user never has to know
> about it.

I agree with what you are saying about the index.

But in git-gui I found myself writing code on Monday which tries to
hide the index from the user unless he/she requested that the index
be made visible.

The reason is there are some users who I'd like to give git-gui to
who I'm not sure I trust to make sure their index is in sync with
their working directory before they commit.  In some cases I'm lucky
that the user even knows what directory their file is stored in.  :-(
Yes, there really are computer users who are afraid of directories
and command lines.

I probably could try to teach them to make sure the final file
is included in the index before committing, but I think that for
most of them they would find this to be just another couple of
mouse clicks they have to perform before every commit, meaning its
something that the #$@!*@!*@$# tool should just do for them.

-- 

Re: Cleaning up git user-interface warts

[Marko Macek]

Junio C Hamano wrote:
> Marko Macek <marko.macek@gmx.net> writes:
> 
>> For people switching from CVS and SVN it would be much better if the
>> index was hidden behind the scenes by using different defaults:
>>
>> git-commit -a
>> git-status -a
>> git-diff HEAD
>>
>> BTW, currently there's a minor bug: git-diff HEAD doesn't work before
>> you make the first commit. Perhaps this should be special cased.
> 
> That's only a _bug_ in your implementation of the synonym for
> "svn diff" which blindly used "git diff HEAD".


My "implementation" is taken from git-diff man page. It seems obvious
that the situation before the first commit is just a special case if 
we consider git-diff to be Porcelain (which I do).

 
> This "there is no HEAD yet" is not related to the index, but I

I agree, this is a separate issue.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Marko Macek <marko.macek@gmx.net> writes:

>>> BTW, currently there's a minor bug: git-diff HEAD doesn't work before
>>> you make the first commit. Perhaps this should be special cased.
>>
>> That's only a _bug_ in your implementation of the synonym for
>> "svn diff" which blindly used "git diff HEAD".
>
> My "implementation" is taken from git-diff man page. It seems obvious
> that the situation before the first commit is just a special case if
> we consider git-diff to be Porcelain (which I do).

Yes, "git diff" is a Porcelain.  No question about it.

I do not consider the current behaviour of "git diff HEAD" that
complains instead of giving runs of "foo is a new file and no
diff is available for it" a bug; you asked for diff from some
commit but the commit you gave was bogus (does not exist yet).
But if you feel strongly about it, it should be trivial to
special case the yet-to-be-born HEAD case and run the
equilvalent of:

	git ls-files | sed -e 's/$/ is a new file, no diff is available./'

in such a case.  Or you could even go fancier and do an
equivalent of:

	git ls-files |
        while read path
        do
		l=`wc -l <"$path"`
        	echo "diff --git a/$path b/$path"
                echo "--- a/$path"
                echo "--- b/$path"
                echo "@@ -0,0 +1,$l @@"
                sed -e 's/^/+/' <"$path"
	done

and you can claim that it makes it consistent with the case
where you already have commits.

But I happen to think that consistency is only of academic
interest.  After all, how often would one create a true "root"
commit?  We are not talking about creating a new repository that
starts its life as a clone of something else, but a truly empty
one in which the initial commit is made.  And how often would
one want to view "diff" from void while preparing for that
initial commit?  Both that low frequency _and_ general
uselessness of the output from either of the above shell
scripts, would it be worth "fixing" it?

I do not think it adds any real practical value, and does not
even have much to do with being user friendly.  I would put it
in the "when somebody is really bored and has nothing better to
do, then this _could_ be done" category.

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Junio C Hamano wrote:

> Marko Macek <marko.macek@gmx.net> writes:
> 
>>>> BTW, currently there's a minor bug: git-diff HEAD doesn't work before
>>>> you make the first commit. Perhaps this should be special cased.
>>>
>>> That's only a _bug_ in your implementation of the synonym for
>>> "svn diff" which blindly used "git diff HEAD".
>>
>> My "implementation" is taken from git-diff man page. It seems obvious
>> that the situation before the first commit is just a special case if
>> we consider git-diff to be Porcelain (which I do).
> 
> Yes, "git diff" is a Porcelain.  No question about it.
> 
> I do not consider the current behaviour of "git diff HEAD" that
> complains instead of giving runs of "foo is a new file and no
> diff is available for it" a bug; you asked for diff from some
> commit but the commit you gave was bogus (does not exist yet).

git diff --root HEAD, perhaps?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Sean]

On Wed, 15 Nov 2006 20:05:27 +0100
Marko Macek <marko.macek@gmx.net> wrote:

> I guess this is the reason that the GIT Tutorial for CVS/SVN users is talking about _cogito_ instead.
> (which is very confusing for someone coming to _git_ home page, trying to learn git).

IMHO this is really bad.  Pasky runs the Git web site and feels
that Cogito comes hand in hand with Git.  When I asked him about
it he mentioned that Junio had approved.  But it's very confusing
to click a link that purports to show you how to use Git and get
shown a bunch of Cogito stuff.

Git is confusing enough for new users without "Git" and "Cogito"
being mixed without comment on the Git webpage.  At the very
least, the links should be changed to "Cogito for CVS/SVN users".

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 11:28:34PM CET, Sean wrote:
> Git is confusing enough for new users without "Git" and "Cogito"
> being mixed without comment on the Git webpage.  At the very
> least, the links should be changed to "Cogito for CVS/SVN users".

It's not being mixed without comment, in the very first paragraph I'm
trying to explain what the difference is and why is Cogito used for
introduction to Git. I've tried to clear it up even more now.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Andy Parkins]

On Wednesday 2006, November 15 18:03, Linus Torvalds wrote:

> Guys, before you start thinking this way, the fact is, there's a lot of
> happy git users.

I'm a happy user, doesn't mean I wouldn't like changes.  In fact, by that 
argument, that there are happy users means that there is no need to ever make 
changes.

>  - git itself has now done it that way for the last 18 months, and the
>    fact is, the people _complaining_ are a small subset of the people who
>    actually use git on a daily basis and don't complain.

That's awfully like the argument I hear off my bank whenever I complain to 
them too - "well lots of other people don't complain so we must be right".  
The people who complain are a subset of the people who have complaints.  I 
don't think never changing is a good argument - leaving aside the actual 
changes under discussion - in another 18 months lets say there are double the 
number of git users, and 18 months after that double again - in that case the 
potential new users needs outweigh the current users needs.

> If you think "pull" is confusing, I can guarantee you that _changing_ the
> name is a hell of a lot more confusing. In fact, I think a lot of the

> But the fact is, git isn't really that hard to work out, and the commands

On the one hand you're arguing that git syntax is easy to learn, and on the 
other that no one will be able to learn a new syntax just as easily.

> aren't that complicated. There's no reason to rename them. We do have
> other problems:

That there are other problems doesn't negate these problems.

> But trying to rename "pull" (or the "git" name itself) is just going to
> cause more confusion than you fix.

I don't think so.  Mainly because the proposed new git pull would be a subset 
of the existing git pull.  It's not changing function, it's just reducing in 
function.


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

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Andy Parkins wrote:
>
> On the one hand you're arguing that git syntax is easy to learn, and on the 
> other that no one will be able to learn a new syntax just as easily.

I'm saying that people who are new to git will _have_ to learn new 
concepts ANYWAY.

I don't think the naming is the hard part. 

The fact is, git is one of the very few (essentially _only_) SCM's that 
make it very clear that all real operations are local and that if you want 
to work with other repositories, you have to "fetch" those into local 
branches first. The fact that "pull" exists at all is really just 
shorthand.

If people have trouble explaining this to others, and have trouble 
grasping "pull", then I will bet that the _real_ issue has nothing at all 
to do with naming at all, and the real issue is that people are being 
_taught_ the concepts in the wrong order.

Before you learn "pull", you should learn "fetch". Don't even _mention_ 
"pull" until the person got what "fetch" means. Because the fact is, 
"fetch" is really the much more fundamental operation, and once you 
really understand what "fetch" does, "pull" is obvious.

So I'll argue that the problem isn't naming, the "problem" is really that 
git has a few fundamnetal concepts that people aren't used to. The most 
fundamnetal of those is the notion of the local branch-space. EVERY other 
(broken) SCM has branches as being some kind of totally idiotic separate 
subdirectories, or doesn't really support branches at all (ie neither BK 
nor CVS really support "branches" - even if a concept of that name exists 
in CVS, it has nothing at all in common with the git model of branches).

But once you understand branches, and understand "fetch" (and it really 
isn't _that_ complicated: fetch really does exactly what the name says, so 
if you understand local branches, you will understand "fetch"), then it's 
a much smaller step to explain "pull = fetch + merge".

But I bet people don't teach it that way. They _start_ by teaching "pull". 
Right?

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

On 11/15/06, Linus Torvalds <torvalds@osdl.org> wrote:
> But once you understand branches, and understand "fetch" (and it really
> isn't _that_ complicated: fetch really does exactly what the name says, so
> if you understand local branches, you will understand "fetch"), then it's
> a much smaller step to explain "pull = fetch + merge".
>
> But I bet people don't teach it that way. They _start_ by teaching "pull".
> Right?

"git fetch" is certainly the right thing for the platform integration
role, in which one is trying to maintain a series of integration
branches which track the bleeding edge of some subsystems while
keeping the core stable on each branch.  This is not as impossible as
people make it out to be, but there certainly isn't much place for
automatic merges to _persistent_ branches.

It's fundamentally a backporting and cherry-picking effort, and the
git workflow puts it where it belongs: in the local repository, where
_transient_ branches can and should be created and destroyed casually
to track exploratory efforts.  These may include automatic merges and
even cruder techniques (git diff, hack on patch, apply patch).  Once
you figure out which bits you actually want to backport, you go back
to a fresh branch and cherry-pick the same bits with the tool instead
of manually, so that there is less noise in future merges.  When
you've tested a little, you merge this branch to the persistent branch
that other repositories track.

Cheers,

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Michael K. Edwards wrote:
> > 
> > But I bet people don't teach it that way. They _start_ by teaching "pull".
> > Right?
> 
> "git fetch" is certainly the right thing for the platform integration
> role

I'm saying that even if you _never_ end up using "git fetch" ever again 
(because in practice you always want to do a "fetch + merge == pull"), 
people who teach others the concepts and usage of git should probably 
start by talking about "git fetch".

Then, when the user says (and he obviously will say this) "but I don't 
want to just fetch the other persons work into some local branch, I want 
to actually get it into _my_ branch", you say "Ahhah!" and talk about how 
"pull" is a shorthand for first fetching and then merging the result into 
the current branch.

See? Once you explain "fetch" to somebody, I can pretty much guarantee 
that they'll explain "pull" to themselves without you having to even work 
at it. And then they'll probably happily use "pull" ever after, and never 
worry about fetch, but now they'll understand the _concepts_.

It's only if you start the other way around that "pull" vs "fetch" vs 
"push" become confusing. If you _start_ by explaining branches (and you 
might use "gitk --all" on a small project as a visualization tool), 
suddenly the concepts aren't all that complicated.

Sure, then you have to remember two words ("pull" vs "fetch"), but I'm 
pretty sure that the thing that makes people confused is not the words 
themselves, but their lack of understanding of the concepts behind them.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Linus Torvalds wrote:

> I'm saying that even if you _never_ end up using "git fetch" ever again 
> (because in practice you always want to do a "fetch + merge == pull"), 
> people who teach others the concepts and usage of git should probably 
> start by talking about "git fetch".
> 
> Then, when the user says (and he obviously will say this) "but I don't 
> want to just fetch the other persons work into some local branch, I want 
> to actually get it into _my_ branch", you say "Ahhah!" and talk about how 
> "pull" is a shorthand for first fetching and then merging the result into 
> the current branch.

Actually I believe it would make things even clearer if "merge" was 
taught at that point.  Only when the user is comfortable with the 
separate notions of fetching and merging might the pull shorthand 
possibly be mentioned.

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Nicolas Pitre wrote:
> 
> Actually I believe it would make things even clearer if "merge" was 
> taught at that point.  Only when the user is comfortable with the 
> separate notions of fetching and merging might the pull shorthand 
> possibly be mentioned.

I agree. I just expect that "merge" is such a simple concept that it 
doesn't really need a whole lot of explaining. 

People kind of expect merging to be hard, but I think it's because CVS et 
al have tought people that merging is _painful_. I don't think it's a very 
complicated concept per se, especially if you have explained branches with 
gitk already.

But yes, the order should be:

 (a) explain what "branches" mean in git (and in that situation, "fetch" 
     is very natural - I think fetching itself is probably easier to 
     explain than "branches" are).
 (b) once you've explained branches, the notion of "merge" comes next, and 
     I _think_ that is very obvious. This is where UI issues come in, 
     because "git merge" is really a totally internal program with a 
     pretty horrid UI, but I think we could fix the syntax, and even with 
     the current syntax you can really just gloss it over, because nobody 
     is really going to care.
 (c) once "fetching branches" and "merging" have been explained, "pull" is 
     really pretty damn trivial, and in fact, if you then explain that 
     it's just easier to do "git pull . branchname" than to use "git 
     merge", I think people may just even agree with you.

I think I saw that particular discussion on #git: somebody didn't expect 
"git pull . branch" to be the way to merge. And again, I think it's 
not _really_ because "pull" is hard to understand, it's because people 
haven't been walked through the thing in this way.

Once you understand local branches, fetching and merging, it's actually 
_easier_ to explain why we merge even local branches with "git pull .": 
you just tell them that this way you can use the same command regardless 
of whether you're merging something local or something remote. Again, if 
it's explained that way, I bet a lot of people react with "ahh, that's 
clever", and _like_ the fact that they only really need to learn _one_ 
command, instead of learning two.

See? Explain it that way: "pull" really is simple. By using "pull", you 
don't have to learn about "merge" syntax. You -can- use "merge" as a 
separate program if you want to, but the syntax isn't very nice, exactly 
because you're not really expected to.

But the real issue here is to explain local branches. I will happily admit 
that local branches are very VERY different from just about any other SCM, 
but I also claim that git is just much BETTER than other SCM's in this 
respect.

And yes, this is why you should NOT try to use the same naming as "hg", 
for example. Last I saw, hg still didn't even have local branches, To 
mercurial, repository == branch, and that's it. It was what I came from 
too, and I used to argue for using git that way too. I've since seen the 
error of my ways, and git is simply BETTER. 

And the concept of local branches is exactly _why_ you have to have 
separate "fetch" and "pull", but why you do _not_ need a separate "merge" 
(because "pull ." does it for you).

If you don't understand local branches, you'll never understand git usage. 
And once you _do_ understand local branches, "fetch" vs "pull" actually is 
rather simple.

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 3521 bytes --]

On Wed, 15 Nov 2006 12:40:43 -0800 (PST), Linus Torvalds wrote:
> On Wed, 15 Nov 2006, Nicolas Pitre wrote:
> >
> > Actually I believe it would make things even clearer if "merge" was
> > taught at that point.  Only when the user is comfortable with the
> > separate notions of fetching and merging might the pull shorthand
> > possibly be mentioned.
>
> I agree. I just expect that "merge" is such a simple concept that it
> doesn't really need a whole lot of explaining.

Well, one of the problems is that with current git I can teach, (and I
have), that there's a conceptual:

	pull = fetch + merge

But then shortly after I have to teach an interface notion:

	merge = pull .

So there's this goofy circular notion that people end up with
mentally. If we fix it so that a local merge really is performed with
"git merge <branch>" instead of "git pull . <branch>" then teaching
pull=fetch+merge really is a lot easier.

In the meantime, pull would still be useless to me, I think. But maybe
that's just the "default branch to merge" selection being broken. If
that were fixed, maybe I would start using pull.

>  (a) explain what "branches" mean in git (and in that situation, "fetch"
>      is very natural - I think fetching itself is probably easier to
>      explain than "branches" are).

There's a piece missing here, namely the mapping between remote and
local branch names and any notion of "tracking branches". I think a
sane story for that is still being invented, (or if it exists now, I
haven't seen it yet).

>  (c) once "fetching branches" and "merging" have been explained, "pull" is
>      really pretty damn trivial, and in fact, if you then explain that
>      it's just easier to do "git pull . branchname" than to use "git
>      merge", I think people may just even agree with you.

Well, they get pretty darn confused at this point, in my experience.

> Once you understand local branches, fetching and merging, it's actually
> _easier_ to explain why we merge even local branches with "git pull .":
> you just tell them that this way you can use the same command regardless
> of whether you're merging something local or something remote. Again, if
> it's explained that way, I bet a lot of people react with "ahh, that's
> clever", and _like_ the fact that they only really need to learn _one_
> command, instead of learning two.

No. It's really, really broken to use "pull ." for local merging. Not
a feature at all. We just got done establishing that pull is a
shorthand for doing fetch+merge, so reusing it when there is _no_
fetch at all is insane.

You just established quite clearly hat git has a huge advantge over
all other systems by having a model that everything is fetched in
and then worked with locally. I agree that this is a major
selling-point of git, and I'm also baffled that systems like bzr and
hg try so hard to push every branch into a separate repository.

But I think that git's "work with everything locally" story is undercut
a bit by regular usage being to use a transfer-inducing command like
"pull" for a totally local merge.

Anyway, I think we all agree that we'd really rather have "git merge
<branch>" be usable for local merges, so let's get that in place and
users can pick whichever they like.

> But the real issue here is to explain local branches. I will happily admit
> that local branches are very VERY different from just about any other SCM,
> but I also claim that git is just much BETTER than other SCM's in this
> respect.

Totally agree.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> So there's this goofy circular notion that people end up with
> If we fix it so that a local merge really is performed with
> "git merge <branch>" instead of "git pull . <branch>" then teaching
> pull=fetch+merge really is a lot easier.

I am wondering if that could be "git merge <committish>..."
instead.  I do not care too much about the ... part (i.e. an
Octopus), but I often find myself doing:

	git checkout next
        git merge "Merge early part of branch 'foo'" HEAD foo~3

when earlier part of "foo" topic are worthy to be in 'next' but
not the later ones.

> In the meantime, pull would still be useless to me, I think. But maybe
> that's just the "default branch to merge" selection being broken.

Have you looked into per-branch configuration for default merge
source recently?  It might not be documented well enough,
though, because I do not use it myself, but you should be able
to improve on that (meaning both documentation and setting up
the defaults upon cloning and fetching).

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Junio C Hamano wrote:

> I am wondering if that could be "git merge <committish>..."
> instead.  I do not care too much about the ... part (i.e. an
> Octopus), but I often find myself doing:
> 
> 	git checkout next
>         git merge "Merge early part of branch 'foo'" HEAD foo~3
> 
> when earlier part of "foo" topic are worthy to be in 'next' but
> not the later ones.

Indeed !

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> On Wed, 15 Nov 2006, Junio C Hamano wrote:
>
>> I am wondering if that could be "git merge <committish>..."
>> instead.  I do not care too much about the ... part (i.e. an
>> Octopus), but I often find myself doing:
>> 
>> 	git checkout next
>>         git merge "Merge early part of branch 'foo'" HEAD foo~3
>> 
>> when earlier part of "foo" topic are worthy to be in 'next' but
>> not the later ones.
>
> Indeed !

Indeed, what?

That means that updated "git merge" (not the current one) would
not be able to assume it's parameter is a branch name, and still
has to come up with the merge message "Merge <branch>".

Merging only within the local branch namespace already has the
problem you need to solve to come up with a nicely formatted
"Merge <branch> of <remote repository>" some way.  I am not
saying that this is unsolvable (you can look at remotes/ files
to see what remote tracking branch the branch is about), but
something you need to keep in mind when implementing the
improved "git merge".

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > On Wed, 15 Nov 2006, Junio C Hamano wrote:
> >
> >> I am wondering if that could be "git merge <committish>..."
> >> instead.  I do not care too much about the ... part (i.e. an
> >> Octopus), but I often find myself doing:
> >> 
> >> 	git checkout next
> >>         git merge "Merge early part of branch 'foo'" HEAD foo~3
> >> 
> >> when earlier part of "foo" topic are worthy to be in 'next' but
> >> not the later ones.
> >
> > Indeed !
> 
> Indeed, what?

What you propose would be excellent indeed.

> That means that updated "git merge" (not the current one) would
> not be able to assume it's parameter is a branch name, and still
> has to come up with the merge message "Merge <branch>".
> 
> Merging only within the local branch namespace already has the
> problem you need to solve to come up with a nicely formatted
> "Merge <branch> of <remote repository>" some way.  I am not
> saying that this is unsolvable (you can look at remotes/ files
> to see what remote tracking branch the branch is about), but
> something you need to keep in mind when implementing the
> improved "git merge".

Right.  But that is an _implementation_ detail, not a usability issue.

Re: Cleaning up git user-interface warts

[Karl Hasselström]

On 2006-11-15 13:52:47 -0800, Junio C Hamano wrote:

> That means that updated "git merge" (not the current one) would not
> be able to assume it's parameter is a branch name, and still has to
> come up with the merge message "Merge <branch>".

Often, it would be a branch or a tag, so no problem there. For commits
in general, it should not be hard to compute the set of branches and
tags the commit is part of, and in the (probably) common case where
this set has exactly one element, the problem is solved. For the
remaining cases, it should not be too horrible to ask the user to
describe what is being merged.

-- 
Karl Hasselström, kha@treskal.com

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Carl Worth wrote:
> 
> Well, one of the problems is that with current git I can teach, (and I
> have), that there's a conceptual:
> 
> 	pull = fetch + merge
> 
> But then shortly after I have to teach an interface notion:
> 
> 	merge = pull .

This is why I would suggest teaching the _concept_ of the "merge", and not 
the actual command.

I don't think you should basically ever use the "git merge" command 
itself, not in teaching, and not in real life. So after talking about 
branches and having taught people to use "git fetch", the next stage is 
not so much to teach people to use "git merge", but to explain to them the 
_concept_ of merging. 

I really think that's a fairly quick thing, partly exactly _because_ you 
shouldn't at that point need to worry about syntax or details or anything 
like that at all. You just tell them that there's a notion of "merging" 
two branches by joining them together and havign the result have the 
changes from both branches. So it's a _conceptual_ issue, and that's why I 
said I think you should just totally gloss over the whole issue of "git 
merge" syntax.

Once you've explained the _concept_ of merging, you then introduce the 
command to actually _execute_ the merge: it's "git pull".

See? No circular thinking at all. One is a _concept_ ("join two branches 
together by including both in the result") and the other is a command 
("pull will fetch the remote data if any, and merge it into the current 
branch").

If you explain it that way, then _obviously_ if you don't need to fetch 
any remote data, doing "git pull . xyzzy" will merge the local branch 
"xyzzy" into the current branch.

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 2150 bytes --]

On Wed, 15 Nov 2006 13:45:58 -0800 (PST), Linus Torvalds wrote:
> On Wed, 15 Nov 2006, Carl Worth wrote:
> >
> > Well, one of the problems is that with current git I can teach, (and I
> > have), that there's a conceptual:
> >
> > 	pull = fetch + merge
> >
> > But then shortly after I have to teach an interface notion:
> >
> > 	merge = pull .
>
> This is why I would suggest teaching the _concept_ of the "merge", and not
> the actual command.
>
> I don't think you should basically ever use the "git merge" command
> itself, not in teaching, and not in real life.

I think that's just and accident of git-merge having such a bad
syntax, (requiring a merge message, not using -m for that, requiring
two heads instead of defaulting to current, etc.). So the result is
accepting another bad syntax "pull ." for an operation that really is
merge.

> Once you've explained the _concept_ of merging, you then introduce the
> command to actually _execute_ the merge: it's "git pull".

I think we'll be doing better when there is a stronger correlation
between the concepts of the operations and the command names for
carrying them out.

Plus, when I'm teaching "fetch everything first, then manipulate it
locally", (which is what I teach, since that's the only way I use
git), then the "." looks really out of place when I teach the 'merge'
command. I end up saying, "Oh, that's there because you could do the
fetch and merge all in one step if you really wanted, but I never do
that.".

And that's because I _do_ teach fetch first, as you've suggested.

> changes from both branches. So it's a _conceptual_ issue, and that's why I
> said I think you should just totally gloss over the whole issue of "git
> merge" syntax.

That doesn't work. I know I went looking at the git-merge
documentation when I started to learn git. "It can't really be this
hard, can it?" was my reaction to it. And then only after attending a
tutorial did I learn that "pull ." is the way it's really done.

That's nothing more than a user-interface trap for new users, plain
and simple.

The real fix is to stop glossing over git-merge and just give it a
usable syntax.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Carl Worth <cworth@cworth.org> wrote:
> Plus, when I'm teaching "fetch everything first, then manipulate it
> locally", (which is what I teach, since that's the only way I use
> git), then the "." looks really out of place when I teach the 'merge'
> command. I end up saying, "Oh, that's there because you could do the
> fetch and merge all in one step if you really wanted, but I never do
> that.".
> 
> And that's because I _do_ teach fetch first, as you've suggested.

Ditto.  In every way.

I've taught the same fetch first, then merge strategy.  Nobody I
know in meat-space pulls from a remote URL and merges in one shot;
they always fetch locally, look at the incoming changes, decide if
its worthwhile/ok, *then* merge with "git pull . branch".

The "." looks out of place for everyone...

-- 

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Shawn Pearce wrote:
> 
> I've taught the same fetch first, then merge strategy.  Nobody I
> know in meat-space pulls from a remote URL and merges in one shot;

Actually, with different people involved it's _much_ better to do it in 
one shot.

Why? Because doing a separate "fetch to local space" + "merge from local 
space" actually loses the information on what you are merging.

It's a lot more useful to have a merge message like

	Merge branch 'for-linus' of git://one.firstfloor.org/home/andi/git/linux-2.6

than one like

	Merge branch 'for-linus'

which is what you get if you fetched it first.

Of course, in a situation like git itself, where most of the merges are 
stuff that Junio has had pending in his own tree ('maint' branch etc), 
things are different. But in a system where people actually use separate 
trees, there really is an advantage to consider the fundamental operation 
to be the "pull", not the "merge".

Again, the kernel really is more distributed than most projects, but this 
is another thing people should recognize: git has been designed for "true 
distributed development". Not the "fake" kind. Not the "I merge mainly my 
own branches" kind of thing. Truly distributed.

And in a truly distributed situation, "pull" is strictly more powerful 
than a separate "fetch" + separate "merge".

In other words, an SCM that does "pull" is _better_ than an SCM that does 
"merge". You can implement "merge" as a special case of "pull" (which we 
do), but you cannot conveniently do it the other way around without having 
to tie them together some other way (ie you could have a "remember the 
last place we fetched this branch from in order to tie the fetch and the 
merge together" - but please realize that that is exactly what "pull" 
_is_).

So I will generally do a "git pull" (possibly followed by a "git reset 
--hard ORIG_HEAD" if I decided it wasn't good) over a "git fetch" + "git 
merge". Exactly because the "pull" operation is actually more powerful.

Maybe people who aren't in my position don't always appreciate the _power_ 
of git. The reason "merge" is a second-class citizen is simply because IT 
SHOULD BE.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Linus Torvalds wrote:

> 
> 
> On Wed, 15 Nov 2006, Shawn Pearce wrote:
> > 
> > I've taught the same fetch first, then merge strategy.  Nobody I
> > know in meat-space pulls from a remote URL and merges in one shot;
> 
> Actually, with different people involved it's _much_ better to do it in 
> one shot.
> 
> Why? Because doing a separate "fetch to local space" + "merge from local 
> space" actually loses the information on what you are merging.
> 
> It's a lot more useful to have a merge message like
> 
> 	Merge branch 'for-linus' of git://one.firstfloor.org/home/andi/git/linux-2.6
> 
> than one like
> 
> 	Merge branch 'for-linus'

That is an implementation detail that should be easily overcome once the 
notion of tracking branch with URL attribute is implemented.  Then it 
will be really easy to notice whether the branch argument is a local 
branch or a tracking branch with remote reference.

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Nicolas Pitre wrote:
> 
> That is an implementation detail that should be easily overcome once the 
> notion of tracking branch with URL attribute is implemented.

Nope.

I simply don't _have_ those branches.

Why? Because the kernel is _distributed_. There is no central place 
(certainly not my repository) that tracks all the possible branches that 
might get merged.

In other words, I repeat: in a TRULY DISTRIBUTED ENVIRONMENT it makes more 
sense to have a "pull" that fetches and merges, over something that 
fetches separately and then merges. Because in a truly distributed 
environment, you simply DO NOT HAVE static branches that you can associate 
with particular sources.

See?

And the thing is, I think the git design should be geared towards true 
distribution. It should NOT be geared toward a fairly static set of 
branches that all have a fairly static set of other repositories 
associated with them. Can you see the difference?

I'm personally convinced that one of the reasons people tend to use git in 
a centralized manner is just a mental disease that has its roots in how 
they used _other_ SCM's. I don't want git design to be polluted by such a 
centralized notion.

So to repeat: you can always make "pull" boil down to "pull from myself" 
(aka just "merge"), but you can _not_ make "fetch + merge" boil down to 
"pull" without meking up extra state to track separately. In other words, 
"pull" really is the strictly more powerful operation.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Linus Torvalds wrote:

> 
> 
> On Wed, 15 Nov 2006, Nicolas Pitre wrote:
> > 
> > That is an implementation detail that should be easily overcome once the 
> > notion of tracking branch with URL attribute is implemented.
> 
> Nope.
> 
> I simply don't _have_ those branches.
> 
> Why? Because the kernel is _distributed_. There is no central place 
> (certainly not my repository) that tracks all the possible branches that 
> might get merged.
> 
> In other words, I repeat: in a TRULY DISTRIBUTED ENVIRONMENT it makes more 
> sense to have a "pull" that fetches and merges, over something that 
> fetches separately and then merges.
[...]

OK fine.  git-pull is there to stay and let's make sure it remains the 
same.

Let's see if, for example, git-merge can be made more useful in the mean 
time for those evidently inferior people that would prefer an interface 
that maps more closely to the actual operation that is being performed.  
And although I do understand what "pull" does, I think I should qualify 
myself as one of those inferior people nevertheless since /pull . blah" 
really irritates me.  OK I must be really dumb to let myself being 
disturbed by such an insignificant detail... but apparently I'm not 
alone.

But I promise to never change the "pull" behavior if I ever attempt to 
fix the "merge" command for the inferior mortals as myself.  All power 
to those with superior minds shall never be removed.

;-)

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

On 11/15/06, Linus Torvalds <torvalds@osdl.org> wrote:
> Actually, with different people involved it's _much_ better to do it in
> one shot.
>
> Why? Because doing a separate "fetch to local space" + "merge from local
> space" actually loses the information on what you are merging.
>
> It's a lot more useful to have a merge message like
>
>         Merge branch 'for-linus' of git://one.firstfloor.org/home/andi/git/linux-2.6
>
> than one like
>
>         Merge branch 'for-linus'
>
> which is what you get if you fetched it first.

Full ACK from a platform integrator's perspective.  Local merge is
great for trial runs but the history in a persistent branch should be
as self-contained and self-explanatory as possible.  It shouldn't
depend on what I name local tracking branches, which are just a
convenience so that I can still do trial runs when my connectivity is
broken.

I don't have to manually log the _mechanical_origin_ of a given delta;
git does that for me, and mostly just DTRT when the same delta arrives
via several paths.  When I use git pull from a remote branch (with or
without an entry in remotes/heads, which for this purpose is just
shorthand), I don't have to manually log what conflicts I have and
haven't resolved, either; I must have assimilated whatever I cared
about in the remote branch's history up to that point, because as long
as there are things in that remote branch that I haven't decided how
to handle, I stick to cherry-picking.

Obviously, fetch to local space is great (especially when you spend
some of your working hours behind a firewall that blocks outbound TCP
9418).  Fetch from local space is also great, when the local space you
are fetching from reflects local work (such as a sync point and
reconciliation of several upstream sources, which then needs to be
ported forward or back to the chosen core version for each platform).
Fetch from a local space that is just a tracker for remote work is not
great, because it doesn't capture the editorial decision implied by a
remote pull:  I looked at what the remote branch had to offer as of
this date, systematically decided which bits did and didn't belong in
the branch to which I was pulling, and pulled.

The record of that pull becomes a first-class object because it's
attached to an actual content delta in the target branch.  So it
propagates into branches that pull from it.  Pulling this delta into
another branch is different from cherry-picking a feature delta; it
implies acceptance of the reconciliation and editorial work associated
with the merge in the source branch.

Coming from me, this is all rather theoretical, as I haven't been
using this particular tool for the purpose long enough to have an
independent opinion.  But for what it's worth, the workflow Linus
describes isn't just for the guy at the top of the pyramid.

Cheers,

Re: Cleaning up git user-interface warts

[Andreas Ericsson]

Michael K. Edwards wrote:
> On 11/15/06, Linus Torvalds <torvalds@osdl.org> wrote:
>> Actually, with different people involved it's _much_ better to do it in
>> one shot.
>>
>> Why? Because doing a separate "fetch to local space" + "merge from local
>> space" actually loses the information on what you are merging.
>>
>> It's a lot more useful to have a merge message like
>>
>>         Merge branch 'for-linus' of 
>> git://one.firstfloor.org/home/andi/git/linux-2.6
>>
>> than one like
>>
>>         Merge branch 'for-linus'
>>
>> which is what you get if you fetched it first.
> 
> Full ACK from a platform integrator's perspective.  Local merge is
> great for trial runs but the history in a persistent branch should be
> as self-contained and self-explanatory as possible.  It shouldn't
> depend on what I name local tracking branches, which are just a
> convenience so that I can still do trial runs when my connectivity is
> broken.
> 

[...]

> 
> Coming from me, this is all rather theoretical, as I haven't been
> using this particular tool for the purpose long enough to have an
> independent opinion.  But for what it's worth, the workflow Linus
> describes isn't just for the guy at the top of the pyramid.
> 

I think it's unfortunate that git was originally written by Linus, since 
he so obviously is "the guy at the top of the pyramid" in many more 
senses than just "Linus said this and that patch was OK to commit", 
since git was designed to work like king Arthur's round table; "Linus is 
in the same circle as me, so ofcourse we help each other out".

All suggestions I've been reading about tracking branches, 
separate-remotes and whatnot have their merit. If any of it gets 
implemented, I'd still like to be able to do one-shot pulls from remote 
repos *without* creating specific tracking branches for it. It's 
extremely useful to fetch other peoples topic-branches into my own 
"master" (or topic-branch) when I trust their changes to be good. Please 
consider that when you're hacking away on whatever changes to do.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 2051 bytes --]

On Wed, 15 Nov 2006 15:33:43 -0800 (PST), Linus Torvalds wrote:
> It's a lot more useful to have a merge message like
>
> 	Merge branch 'for-linus' of git://one.firstfloor.org/home/andi/git/linux-2.6
>
> than one like
>
> 	Merge branch 'for-linus'

There's more information in the first, sure. But I absolutely don't
accept that it's necessarily more useful, and definitely not that this
is a good argument for using pull with a remote branch instead of
fetch followed by merge with a local branch.

First, the pull may just fast-forward in which case there's no message
at all. And we've been through that topic enough recently that we all
know that no important information is lost by not doing any separate
recording in that case.

So you can't turn around and argue that the remote URL information is
suddenly important when it just so happens that it's not a fast
forward.

> And in a truly distributed situation, "pull" is strictly more powerful
> than a separate "fetch" + separate "merge".

I don't buy it. In my usage, I have several different remote
repositories I'm interested in tracking, each with any number of
branches. What I really want is an easy command that fetches all of
those branches, (even new ones that I've never heard about---but never
any of their "tracking branches" that wouldn't be of interest to
me). And I want to do that once, to get the online-access-required
part over with and get all the data into my local repository where I
can start working with it.

As for the URL from which I'm fetching all this stuff, it's really not
interesting to me at all. The URL for "Keith's stuff" keeps changing
anyway---I have no interest in recording that. But I do think it's
worth recording that the commits came from Keith's repository. I do
that right now with a keith/ prefix for his branches. It could also be
done by bringing in his .git/description during the fetch and storing
it somewhere. But I honestly don't see how storing something like that
during would make the system any less distributed in any sense.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

On 11/16/06, Carl Worth <cworth@cworth.org> wrote:
> First, the pull may just fast-forward in which case there's no message
> at all. And we've been through that topic enough recently that we all
> know that no important information is lost by not doing any separate
> recording in that case.
>
> So you can't turn around and argue that the remote URL information is
> suddenly important when it just so happens that it's not a fast
> forward.

When it's a fast forward, the puller hasn't had to make any judgment
calls, so there's no editorial history to record.  When it's not, but
the puller chooses to retain the result on a persistent branch, that
_is_ an editorial decision (even if the result of the auto-merge is
clean); I like having that in the history.

> > And in a truly distributed situation, "pull" is strictly more powerful
> > than a separate "fetch" + separate "merge".
>
> I don't buy it. In my usage, I have several different remote
> repositories I'm interested in tracking, each with any number of
> branches. What I really want is an easy command that fetches all of
> those branches, (even new ones that I've never heard about---but never
> any of their "tracking branches" that wouldn't be of interest to
> me). And I want to do that once, to get the online-access-required
> part over with and get all the data into my local repository where I
> can start working with it.

What do you want all of those branches for?  They haven't been
published to you (that's a human interaction that doesn't go through
git), so for all you know they're just upstream experiments, and doing
things with them is probably shooting yourself in the foot.

I do agree that a robust form of "for b in .git/remotes/*; do git
fetch `basename $b`; done" would be a nice bit of porcelain.  The
entries in .git/remotes would probably need to grow a "Fetch-options:"
field so that you could choose whether or not to follow tags, etc.
Patch to follow.

Cheers,

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 1244 bytes --]

On Thu, 16 Nov 2006 09:57:00 -0800, "Michael K. Edwards" wrote:
> What do you want all of those branches for?  They haven't been
> published to you (that's a human interaction that doesn't go through
> git), so for all you know they're just upstream experiments, and doing
> things with them is probably shooting yourself in the foot.

The same "what do you want them all for" question could be asked of
git-clone which also fetches all available branches. I really just
want to be able to easily watch what's going on in multiple
repositories.

I want to be able to just say "git update" (or whatever) and then be
able to list and browse and explore the stuff locally.

Yes, there's still outside communication that's necessary, but with
the ability to easily track all the remote branches that communication
can be even less formal if I can easily browse and explore things
locally. For example, I might not even know the name of the branch:

Me: Have you pushed a branch for your new work on the frob-widget?
Friend: Yes

And then I can "get fetch" and see "cool-new-frob" come in without
having to be told that name. Or I could have even just fetched
without the specific communication if I was already expecting it for
some reason.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> On Thu, 16 Nov 2006 09:57:00 -0800, "Michael K. Edwards" wrote:
>> What do you want all of those branches for?  They haven't been
>> published to you (that's a human interaction that doesn't go through
>> git), so for all you know they're just upstream experiments, and doing
>> things with them is probably shooting yourself in the foot.
>
> The same "what do you want them all for" question could be asked of
> git-clone which also fetches all available branches. I really just
> want to be able to easily watch what's going on in multiple
> repositories.
>
> I want to be able to just say "git update" (or whatever) and then be
> able to list and browse and explore the stuff locally.
>...

I have no objection to this if it is done in a controlled way
that does not make life more difficult for people who work with
multiple remote repositories.

And I think "git fetch" is the tool for what you want if
enhanced properly; see Linus's message that explaind that we
already have that support in "manually configurable" form but
initializing and maintaining the configuration is currently all
manual and can be improved.

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 4101 bytes --]

On Fri, 17 Nov 2006 00:41:33 -0800, Junio C Hamano wrote:
> I have no objection to this if it is done in a controlled way
> that does not make life more difficult for people who work with
> multiple remote repositories.

That's fine with me. Maybe I didn't explain this well before, but my
desire is exactly for this to work with multiple repositories.

Specifically, what we have in cairo is a "central" shared tree that
many people push to. But we only have two branches there, (one for
bug-fixes only for our stable releases, and one for ongoing
development of new features, and that only of stuff that's well
cooked).

So that tree looks and acts an awful lot like our cvs tree back in the
past. It's often very linear and often fairly boring to look at in gitk.

Meanwhile, all the really interesting stuff happens in personal
repositories where people have their own branches for stuff that is
still getting cooked. This is what's a lot more fun to watch, and
there's a lot more distributed back-and-forth that goes on here as
people collaborate on things. And it's all this kind of collaboration
that cvs never helped with at all, but git has been great.

So, what I want is both "git update" for the central tree. I said we
only have two branches, but that's really only two that are
active---the "stable" branch is actually a new branch after every
major release. It was 1.0 for a while, is 1.2 now, and will be 1.4
later. So I want "git update" to automatically pick those new branches
up as they get created.

Meanwhile, I also want to use "git update" to track everything that
people are working on in the more wild personal trees. So, yes, I do
want "git update" to be able to track lots of remote repositories in a
sane way.

What I have been doing up to this point is a little script I wrote
that does git-ls-remote on the repository I want to track and writes a
.git/remotes file to bring in all their branches. So if I want to see
what behdad is up to, I first refresh his .git/remotes file with my:

	cairo-git-setup-remotes behdad
then:
	git fetch behdad

And I end up with a bunch of branch names with "behdad-" prefixes that
I can explore or blow away if I'm no longer interested, (could have
used a "behdad/" prefix as well).

The first problem we ran into when doing that months ago was that I
don't want any tracking branches to come across this way. Or else I
end up with behdad-origin, he then gets cworth-behdad-origin, ad
nauseum. So we filtered "origin" out, but it will be nice to revisit
this if there's a sane distinction in git now to separate tracking
branches from heads.

> And I think "git fetch" is the tool for what you want if
> enhanced properly; see Linus's message that explaind that we
> already have that support in "manually configurable" form but
> initializing and maintaining the configuration is currently all
> manual and can be improved.

Yes, git-fetch is lovely, and it's the need for manual configuration
that's a problem, (and the mixing up of heads and remote tracking
branches that has been in git historically).

So, yes, I'll definitely look into improving this. I think the details
will involve:

1. Making clone do the --use-separate-remotes behavior by default

2. Taking advantage of that consistently for all branches instead of a
   special master:origin mapping in clone

3. Enhancing git-fetch (or other) to modify .git/remotes, (or was
   there a desire for some other branch-specific section in the config
   file?)

4. Making git-fetch handle the disappearance of a remote branch
   gracefully

5. Adding something like git-fetch --all to allow it to pick up all new
   branches

6. Adding a "git update" that does a fetch for all appropriately
   marked remotes.

On this last point, maybe we do something like:

	update=no|yes|all

in .git/remotes. Then git-clone would set this up with update=all for
origin so git-update would do a "fetch --all" on the origin
repository. Then step 3 above would have to provide for setting this
update option as appropriate.

Anyway, something along those lines perhaps. Any feedback?

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Johannes Schindelin]

Hi,

On Fri, 17 Nov 2006, Carl Worth wrote:

> 1. Making clone do the --use-separate-remotes behavior by default

Fully agree.

> 2. Taking advantage of that consistently for all branches instead of a
>    special master:origin mapping in clone

Fully agree, too.

> 3. Enhancing git-fetch (or other) to modify .git/remotes, (or was
>    there a desire for some other branch-specific section in the config
>    file?)

I introduced the remote.<nick>.{url,fetch,push} entries into the config 
with the goal to enhance -fetch to remember the current command line with 
a setting. I was the only one to find that useful.

BTW I still would argue that it is better to write the remote information 
into the config, because you have a saner way to manipulate that from 
scripts than .git/remotes/<nick>.

> 4. Making git-fetch handle the disappearance of a remote branch
>    gracefully

I think a message like "This remote branch no longer exists. Maybe you 
want to use 'git branch -d <branch>' to remove it locally?" should 
suffice.

> 5. Adding something like git-fetch --all to allow it to pick up all new
>    branches

IIRC this idea was rejected, but I would find it useful. Especially with 
what Han-Wen said: you can store the branches you fetch with "git fetch 
--all <nick>" under .git/refs/remotes/<nick>/<branchname>.

> 6. Adding a "git update" that does a fetch for all appropriately
>    marked remotes.
> 
> On this last point, maybe we do something like:
> 
> 	update=no|yes|all
> 
> in .git/remotes. Then git-clone would set this up with update=all for
> origin so git-update would do a "fetch --all" on the origin
> repository. Then step 3 above would have to provide for setting this
> update option as appropriate.

First thought was: it is only useful if you want to track multiple 
repositories. But next thought: if you mark the correct remotes in every 
of your local repositories, you don't have to remember which nick your 
upstream has. Yeah, I like it. But maybe do it as "git fetch --update" to 
avoid more cluttering of the bindir?

Ciao,
Dscho

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

>> 5. Adding something like git-fetch --all to allow it to pick up all new
>>    branches
>
> IIRC this idea was rejected, but I would find it useful. Especially with 
> what Han-Wen said: you can store the branches you fetch with "git fetch 
> --all <nick>" under .git/refs/remotes/<nick>/<branchname>.

With separate-remote layout, this can be done without risk of
tracking refname clashing with local refname, which was the
primary reason for an earlier reluctance.  

While separate-remote layout also solves Carl's "do not want to
track tracking branches remote has" problem, local branch
namespace can have both for-others (not necessarily "public" but
could be "for colleagues") and throwaway branches, so --all is
probably not the right thing to do in most cases.  But I am Ok
with the approach of seeing how well it works out in practice by
doing the simplest "--all" and giving options to restrict it
later.

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
> I introduced the remote.<nick>.{url,fetch,push} entries into the config 
> with the goal to enhance -fetch to remember the current command line with 
> a setting. I was the only one to find that useful.
> 
> BTW I still would argue that it is better to write the remote information 
> into the config, because you have a saner way to manipulate that from 
> scripts than .git/remotes/<nick>.

I'm *fully* in favor of the remote.<nick>.{url,fetch,push} entries
in the config file.  I've pretty much switched every repository to
that format at this point.

In writing git-gui I'm finding it much, much easier to manage
things through repo-config than to do any mucking around in the
.git/remotes directory.  Yes, the remote files have simple format,
but I can get everything in one "git repo-config --list" pull it
all into a Tcl array and work with it; using .git/remotes means I
have to open the file and read each line too.  :-(

-- 

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> What I have been doing up to this point is a little script I wrote
> that does git-ls-remote on the repository I want to track and writes a
> .git/remotes file to bring in all their branches. So if I want to see
> what behdad is up to, I first refresh his .git/remotes file with my:
>
> 	cairo-git-setup-remotes behdad
> then:
> 	git fetch behdad
>
> And I end up with a bunch of branch names with "behdad-" prefixes that
> I can explore or blow away if I'm no longer interested, (could have
> used a "behdad/" prefix as well).

I would suggest refs/remotes/behdad.

> So, yes, I'll definitely look into improving this. I think the details
> will involve:
>
> 1. Making clone do the --use-separate-remotes behavior by default
>
> 2. Taking advantage of that consistently for all branches instead of a
>    special master:origin mapping in clone

This already should be the case if you use separate-remote.  I
haven't run "clone --separate-remote" myself for a long time,
but the design was certainly to make it behave that way.
Specifically, map everything in refs/heads/ at remote to
refs/remotes/$origin/ with corresponding names, one-to-one.

I do not see much reason to change the mapping of master:origin
which is done for the traditional layout.  The traditional
layout is not suitable for your workflow anyway, and that is why
you prefer separate-remote layout for your project, and I fully
agree it would suit you better.

> 3. Enhancing git-fetch (or other) to modify .git/remotes, (or was
>    there a desire for some other branch-specific section in the config
>    file?)
>
> 4. Making git-fetch handle the disappearance of a remote branch
>    gracefully
>
> 5. Adding something like git-fetch --all to allow it to pick up all new
>    branches

These three are easily done for separate-remote layout but at
that point you would not want --all but more powerful --mirror
(or --update if you want to use that word), which goes the whole
nine yards of noticing disappearance of remote branch, making
matching deletion of local tracking branch, updating
.git/remotes, etc.  I've muttered something similar in a nearby
thread; see below.

> 6. Adding a "git update" that does a fetch for all appropriately
>    marked remotes.
>
> On this last point, maybe we do something like:
>
> 	update=no|yes|all
>
> in .git/remotes. Then git-clone would set this up with update=all for
> origin so git-update would do a "fetch --all" on the origin
> repository. Then step 3 above would have to provide for setting this
> update option as appropriate.

I would prefer this to be kept in contrib/; it feels like it is
filling rather very narrow need.

> Anyway, something along those lines perhaps. Any feedback?

I muttered something less elaborate in the nearby thread.

	Message-ID: <7vr6w78b4x.fsf@assigned-by-dhcp.cox.net>
	Message-ID: <7v64dev88t.fsf@assigned-by-dhcp.cox.net>

The part that deals with manual configuration (the last point in
the first message, and the second in message its entirety) is
something your workflow would not need nor want to worry about,
but I think it is necessary for different ref namespace layouts
and different workflows.  I think the automatable part (the
first two points in the "sensible thing to do" list in the first
message) is very relevant to what you talked about in your
message.

Re: Cleaning up git user-interface warts

[Sean]

On Wed, 15 Nov 2006 14:52:32 -0800
Carl Worth <cworth@cworth.org> wrote:

> The real fix is to stop glossing over git-merge and just give it a
> usable syntax.

Agreed 100%   There's just no good reason to hide the user level
merge command inside of pull.

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Sean <seanlkml@sympatico.ca> wrote:
> On Wed, 15 Nov 2006 14:52:32 -0800
> Carl Worth <cworth@cworth.org> wrote:
> 
> > The real fix is to stop glossing over git-merge and just give it a
> > usable syntax.
> 
> Agreed 100%   There's just no good reason to hide the user level
> merge command inside of pull.

So what about making git-merge take a -m "msg" argument to supply
the commit message, in which case it does the current behavior
(and thus git-pull needs to change to supply -m); and then make
git-merge without any -m parameter invoke "git pull . $@" ?

A minor tweak to both apps, a minor breakage to git-merge, but one
that I think anyone who invokes it by hand today would find sane
(using -m like we do elsewhere) and since the vintage of both
git-pull and git-merge should always match shouldn't break anyone
who uses git-pull today.

-- 

Re: Cleaning up git user-interface warts

[Richard CURNOW]

* Shawn Pearce <spearce@spearce.org> [2006-11-15]:
> 
> So what about making git-merge take a -m "msg" argument to supply
> the commit message, in which case it does the current behavior
> (and thus git-pull needs to change to supply -m); and then make
> git-merge without any -m parameter invoke "git pull . $@" ?

Sounds good to me.

When I'm merging in my own projects, I currently always use merge
(possibly preceded by fetch) rather than pull.  Why?  Because I don't
want my history full of commit messages like

Merge branch "trial_hack" from "../scratch_dir_with_silly_name"

In contrast to Linus's case of wanting to record where the remote merge
came from, I expressly don't want to record that - I want the merge
commit to describe conceptually what was being merged with what.

OK, I could use probably use pull with --no-commit, but I've already
trained my fingers to type out the merge syntax.  They'd be happier with
'git merge -m "Merge feature foo with fixes for bar" bar" though.

Re: Cleaning up git user-interface warts

[Johannes Schindelin]

Hi,

On Thu, 16 Nov 2006, Richard CURNOW wrote:

> In contrast to Linus's case of wanting to record where the remote merge
> came from, I expressly don't want to record that - I want the merge
> commit to describe conceptually what was being merged with what.
> 
> OK, I could use probably use pull with --no-commit, but I've already
> trained my fingers to type out the merge syntax.  They'd be happier with
> 'git merge -m "Merge feature foo with fixes for bar" bar" though.

For the moment, if you forget --no-commit, you can always do a "git-commit 
--amend" -- even with merges.

Hth,
Dscho

Re: Cleaning up git user-interface warts

[Jerome Lovy]

On Wed, 15 Nov 2006, Carl Worth wrote:
> Well, one of the problems is that with current git I can teach, (and I
> have), that there's a conceptual:
> 
> 	pull = fetch + merge
> 
> But then shortly after I have to teach an interface notion:
> 
> 	merge = pull .
> 
> So there's this goofy circular notion that people end up with
> mentally. If we fix it so that a local merge really is performed with
> "git merge <branch>" instead of "git pull . <branch>" then teaching
> pull=fetch+merge really is a lot easier.

On a conceptual level, can we not perhaps explain that if

	pull = fetch + merge

then

	merge = pull - fetch

and that the latter (pull - fetch) happens to be expressed with the 
interface as 'git pull .' ?

My 2 cents.
Jérôme

Re: Cleaning up git user-interface warts

[Theodore Tso]

On Wed, Nov 15, 2006 at 12:40:43PM -0800, Linus Torvalds wrote:
> And yes, this is why you should NOT try to use the same naming as "hg", 
> for example. Last I saw, hg still didn't even have local branches, To 
> mercurial, repository == branch, and that's it. It was what I came from 
> too, and I used to argue for using git that way too. I've since seen the 
> error of my ways, and git is simply BETTER. 

Actually, that's not true.  Mercurial has local branches, just as git
does.  Some people choose not to *use* this particular feature, and
use the BK style repository == branch, but that's mainly because it's
conceptually easy for them, and a number of BK refugees are very
happily using Hg.  

It's probably because of the BK refugee population that after you do
an hg pull, it will warn you that you need to do an "hg update" in
order to merge the working directory up to the latest version that was
just pulled --- and this change was made precisely because Hg supports
local branches, and merging with the current branch isn't always the
right thing, unlike with BK.

> And the concept of local branches is exactly _why_ you have to have 
> separate "fetch" and "pull", but why you do _not_ need a separate "merge" 
> (because "pull ." does it for you).

It's just that the semantics are different, and many developers have
to use multiple DSCM's, depending on what project they happen to be
developing on.  So the reality is that there are people who have to
use bzr, git, and hg, all at the same time.  And while eventually
newbies will figure out and remember that "git pull ." == "merge", the
naming is simply confusing, that's all.  (What does "pull" have to do
with "merge"?  It's not at all obvious.)  

For somoene who uses git full-time, and to the exclusion of all other
systems, I'm sure it's not a problem at all.
	

Re: Cleaning up git user-interface warts

[Andreas Ericsson]

Theodore Tso wrote:
> On Wed, Nov 15, 2006 at 12:40:43PM -0800, Linus Torvalds wrote:
>> And yes, this is why you should NOT try to use the same naming as "hg", 
>> for example. Last I saw, hg still didn't even have local branches, To 
>> mercurial, repository == branch, and that's it. It was what I came from 
>> too, and I used to argue for using git that way too. I've since seen the 
>> error of my ways, and git is simply BETTER. 
> 
> Actually, that's not true.  Mercurial has local branches, just as git
> does.  Some people choose not to *use* this particular feature, and
> use the BK style repository == branch, but that's mainly because it's
> conceptually easy for them, and a number of BK refugees are very
> happily using Hg.  
> 
> It's probably because of the BK refugee population that after you do
> an hg pull, it will warn you that you need to do an "hg update" in
> order to merge the working directory up to the latest version that was
> just pulled --- and this change was made precisely because Hg supports
> local branches, and merging with the current branch isn't always the
> right thing, unlike with BK.
> 
>> And the concept of local branches is exactly _why_ you have to have 
>> separate "fetch" and "pull", but why you do _not_ need a separate "merge" 
>> (because "pull ." does it for you).
> 
> It's just that the semantics are different, and many developers have
> to use multiple DSCM's, depending on what project they happen to be
> developing on.  So the reality is that there are people who have to
> use bzr, git, and hg, all at the same time.  And while eventually
> newbies will figure out and remember that "git pull ." == "merge", the
> naming is simply confusing, that's all.  (What does "pull" have to do
> with "merge"?  It's not at all obvious.)  
> 
> For somoene who uses git full-time, and to the exclusion of all other
> systems, I'm sure it's not a problem at all.


It seems we should, cheaply, be able to avoid a large part of the 
confusion by

* Mentioning git-fetch before git-pull in all documentation newborn 
gitizens are likely to come across. Most git-users aren't Linus, and for 
every successful project the maintainers are outnumbered 100 to 1 by the 
contributors. Those projects successful *because* maintainers are 
heavily outnumbered so we should make it easier for contributors by 
teaching them the right things from the start and possibly have a 
separate man-page for maintainer (git-{maintainer,developer} man-pages, 
anyone?).
* Creating "git update" which might possibly be an internal alias to 
"git pull", except that it should read .git/remotes/* by default unless 
a specific remotes-file is specified.
* Renaming git-merge to git-merge-driver
* Implementing a git-merge that actually does what its name implies, 
possibly by making it an internal alias to pull, but with these differences:
   - It always merges into your current branch.
   - It understands "git merge branch" as well as "git merge . branch".

This is just the very low-hanging fruit. If we take these steps and let 
things cool down a bit, it would probably be proper to take a fresh look 
at this in a couple of months.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Andreas Ericsson wrote:
> 
> * Mentioning git-fetch before git-pull in all documentation newborn gitizens
> are likely to come across.

However, I also think it might make sense to talk about the _simple_ form 
of "git pull" first.

The form I use is actually a lot simpler (conceptually) than the "short" 
form.

When you do

	git pull <reponame> <branchname>

there are very few things that can confuse you (although trying to do it 
without a current branch at all is apparently one such thing ;). 

There are no local branches to worry about, and there aren't any issues 
about what the default repository or branchname on the remote side would 
be either.

So in many ways, if you use this format, you simply never have to worry. 
You may have to _type_ a bit more, so it's not the short or concise 
format, but it sure is the _simple_ format. There simply isn't anything to 
be confused about.

And yes, I actually tend to use this even for project that I don't develop 
on, partly because the defaults for the short and concise formats are bad. 
For example, I follow the "modesetting" branch on the xorg intel graphics 
driver tree, and because I'm always on that branch, what I do is

	git pull origin modesetting

which works correctly (while "git pull" would _not_ have done the right 
thing: it would have picked the right repository, but it would have picked 
the "master" branch of that repository, not the "modesetting" branch).

And notice how I don't do _any_ development there, I just follow that 
branch. The "merge" will obviously always be a fast-forward, but that's 
exactly what I want. 

> Most git-users aren't Linus, and for every successful project the 
> maintainers are outnumbered 100 to 1 by the contributors.

Well, as mentioned, I think even for non-developers, doing pulls with 
explicit branchnames is actually perfectly sane.

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 1621 bytes --]

On Thu, 16 Nov 2006 08:30:55 -0800 (PST), Linus Torvalds wrote:
> The form I use is actually a lot simpler (conceptually) than the "short"
> form.
>
> When you do
>
> 	git pull <reponame> <branchname>

Yes, that's what the user almost always wants. The UI problem here is
that the conceptually simpler form is syntactically longer, (which
means users aren't likely to find it).

So if we can just get <reponame> and <branchname> to default
correctly, (based on the current branch name, and clone/fetch/pull
history), then the conceptually simple form ends up syntactically
simple as "git pull".

And I definitely don't have any problem with that. I'd love to be able
to teach that kind of simple thing to new users.

> driver tree, and because I'm always on that branch, what I do is
>
> 	git pull origin modesetting
...
> Well, as mentioned, I think even for non-developers, doing pulls with
> explicit branchnames is actually perfectly sane.

The behavior is sane, but having to always type the branch name
specifically because it never changes... that's a user-interface bug.

This is a good example of the kind of thing I wanted to hit when
starting this thread. I don't think there are any big conceptual
changes needed in git to make it easier for new users. But there are
little things that are problems that really should be fixed. Wouldn't
it be great to have the following exchange:

	User: How do I track on-going development in a branch?
	Master: Use "git pull"

Rather than:

	User: How do I track on-going development in a branch?
	Master Use "git pull origin <name-of-branch-you-are-already-on>"

?

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Carl Worth wrote:
>
> On Thu, 16 Nov 2006 08:30:55 -0800 (PST), Linus Torvalds wrote:
> > The form I use is actually a lot simpler (conceptually) than the "short"
> > form.
> >
> > When you do
> >
> > 	git pull <reponame> <branchname>
> 
> Yes, that's what the user almost always wants. The UI problem here is
> that the conceptually simpler form is syntactically longer, (which
> means users aren't likely to find it).

Yeah. 

And this is something I absolutely agree with. Our default branches for 
"pull" are horrible. You can "fix" it, but you can only fix it by adding 
_explicit_ branches to your .git/config file by hand, so I don't think 
that's actually a real fix at all. We should just fix the default (where 
even a "I don't know what branch you want" _error_ would be preferable 
over the current situation).

Along with the "git checkout <tag>" thing, I think these two things are 
definitely worth just fixing.

> The behavior is sane, but having to always type the branch name
> specifically because it never changes... that's a user-interface bug.

Yeah. Each branch should

 (a) have a "default source" initialized on the initial "clone"

 (b) have a way to set the source afterwards

 (c) error out if you do just a "git pull" or "git pull remotename" if 
     there is no default branch for the current local branch for that 
     remote.

We actually have (b) in a weak form right now ("weak" because it requires 
you to manually edit the config file: we've got the mechanism, but not a 
nice UI for it), but (a) and (c) are just broken.

And yeah, we should allow pulling into a branch that hasn't been 
initialized.

Re: Cleaning up git user-interface warts

[Sean]

On Thu, 16 Nov 2006 09:30:47 -0800 (PST)
Linus Torvalds <torvalds@osdl.org> wrote:

> Yeah. Each branch should
> 
>  (a) have a "default source" initialized on the initial "clone"
>
> (b) have a way to set the source afterwards
>
> (c) error out if you do just a "git pull" or "git pull remotename" if 
>     there is no default branch for the current local branch for that 
>     remote.

This would be _great_.  You just shouldn't have to hack at the
.git/config file to get reasonable default sources after a clone.
Or even for that matter after fetching a new branch into an
existing repo.

Re: Cleaning up git user-interface warts

[Anand Kumria]

On Wed, 15 Nov 2006 11:18:36 -0800, Linus Torvalds wrote:

> On Wed, 15 Nov 2006, Andy Parkins wrote:
>>
>> On the one hand you're arguing that git syntax is easy to learn, and on the 
>> other that no one will be able to learn a new syntax just as easily.
> 
> I'm saying that people who are new to git will _have_ to learn new 
> concepts ANYWAY.
> 
> I don't think the naming is the hard part. 

It isn't - the unexpectedness of what happens is.

I've started by teaching how to do stuff locally, then "pushing" it out to
others (me).  All the while being able to point out how this is either all
local, or sends stuff (without any local modifications) to others.

Come up to 'pull' and ere you have to point out that not only will you get
the remote changes but they are also merged into your repository. On the
wrong branch?

Too bad.

The problem with git-pull behaving illogically drove me to look at cogito
(an aside, perhaps cg-throw should be the corrollary to cg-fetch?)
instead. Alas it has problems with a cogito branch not being something you
can mentally map back to a git branch.

> But I bet people don't teach it that way. They _start_ by teaching "pull". 
> Right?

Nope.

Anand

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Andy Parkins <andyparkins@gmail.com> writes:

>> But trying to rename "pull" (or the "git" name itself) is just going to
>> cause more confusion than you fix.
>
> I don't think so.  Mainly because the proposed new git pull would be a subset 
> of the existing git pull.  It's not changing function, it's just reducing in 
> function.

We usually use the word "regression" to refer to that kind of
change.

I think it makes a lot of sense having command x that does
essentially the same thing as the current fetch but with more
usability enhancements and more convention as built-in defaults,
and another command y that does what the current 'pull .' does
but with more usability enhancements and more convention as
built-in defaults.  I agree that kind of UI improvements would
make it easier to explain to new people.  Calling x "pull",
however, breaks the existing users and documents, and causes
confusion.  I really do not think you can argue with that.

That's why we are talking about using an uncontaminated word
"get".  I think it is a good effort.

>> aren't that complicated. There's no reason to rename them. We do have
>> other problems:
>
> That there are other problems doesn't negate these problems.

And I think Linus is right in pointing out that there are other
problems that are equally or even more pressing than _renaming_
to break things for existing users.

I personally do not think the current fetch/pull confusing, and
I do see real downside in _renaming_ them, but I am open to the
current get/put discussion because I think the new commands'
semantics may be designed to match newcomers' expectation better
(it's to match tools to newcomers instead of teaching them the
new language of the land) and I do not think that approach would
break existing users and documents.

For some things "matching tools to newcomers" would not really
work, though.  For example, I do not think you can get away with
hiding index forever if you want your users to do real work in a
workflow that involves merging and cherry picking.

Re: Cleaning up git user-interface warts

[Theodore Tso]

On Wed, Nov 15, 2006 at 10:03:18AM -0800, Linus Torvalds wrote:
> So the reason for using "git pull" is
> 
>  - bk did it that way, and like it or not, bk was the first usable 
>    distributed system. hg is totally uninteresting.

Yes, "bk pull" had an implied merge.  But, the reason why bk pull was
never really a problem with Bitkeeper is because it didn't really have
support for multiple branches active within the same repository ---
what Larry called "lines of development".  Or rather, Larry started
down the path of implementing lines of development, and then never
fully supported it, mainly because making it easy for people to use
was the tricky part.   

So with Bitkeeper, with "bk pull" there was never any question about
which branch ("line of development") you would be merging into after
doing a "bk pull", since there was only one LOD, and given that BK had
the rule that a within a LOD only one tip was allowed, a "bk pull"
_had_ to do do a merge operation.   

The moment you start supporting multiple unmerged tips in a repository
i.e., branches, it raises the question, "which branch should the pull
operation merge onto"?  And git's answer, "the current branch", is
often not the right one.  *That's* why always doing a merge isn't
always the right answer, and so in the git world, people are told, use
"git fetch" instead, and in the hg world, "hg pull" doesn't do the
merge.  IMO, it's a fundamental result of the fact that both git and
hg have chosen to support mulitple LOD's, whereas BK punted on the
concept.

If you are operating on your local development branch, the reality is
that merging is probably not the right answer in the general case,
which is why the hg world have omitted doing the merge.  And by
telling people, use "git fetch" instead, that's also an implicit
admission that merging onto the current branch is often not the Right
Thing.

The problem is that "pull" is a very evocative word, especially given
the existence "push", and so in the git world we are reduced to
telling people, "you really don't want to use pull, trust me".  

Is this a major issue?  Not really; I can think of a number of other
issues that make git hard to learn, and why hg has a more gentle
learning curve, and the "don't use pull" is probably a relatively
minor annoyance in the grand scheme of things.

If people are looking for a simple way out, maybe it would be enough
to have an option where if "git pull" is called from an interactive
terminal, and the "novice user" option is enabled, "git pull" returns
a warning message, "You probably want to use 'git fetch' instead; are
you sure?"  If people are saying that we shouldn't be teaching "git
pull" until fairly late in the game, maybe we should have a way of
discouraging novices from using, simply because they they are used to
seeing "pull" from other distributed SCM's.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Theodore Tso <tytso@mit.edu> writes:

> So with Bitkeeper, with "bk pull" there was never any question about
> which branch ("line of development") you would be merging into after
> doing a "bk pull", since there was only one LOD, and given that BK had
> the rule that a within a LOD only one tip was allowed, a "bk pull"
> _had_ to do do a merge operation.   

I've never used Bk and I really appreciate your comments here.

> If you are operating on your local development branch, the reality is
> that merging is probably not the right answer in the general case,

I agree, but I wonder why you are pulling/fetching (with or
without merge) if you are operating on your local development
branch (implying that you are in the middle of something else).

> ...  And by
> telling people, use "git fetch" instead, that's also an implicit
> admission that merging onto the current branch is often not the Right
> Thing.
>
> The problem is that "pull" is a very evocative word, especially given
> the existence "push", and so in the git world we are reduced to
> telling people, "you really don't want to use pull, trust me".  

I would rather say "use 'git branch' to make sure if you are
ready to merge".  Who teaches not to use "git pull"?

> If people are looking for a simple way out, maybe it would be enough
> to have an option where if "git pull" is called from an interactive
> terminal, and the "novice user" option is enabled, "git pull" returns
> a warning message,

I have to disagree with this.  In the simplest CVS-like central
repository with single branch setup in which many "novice users"
start out with, there is almost no need for "git fetch" nor
tracking branch.  You pull, resolve conflicts, attempt to push
back, perhaps gets "oh, no fast forward somebody pushed first",
pull again, then push back.  So I am not sure where "you really
do not want to use pull.  trust me" comes from.

It is a different story for people who _know_ git enough to know
what is going on.  They may be using multiple branches and
interacting with multiple remote branches, and there are times
you would want fetch and there are other times you would want
pull.  But for them, I do think the suggestion would never end
with "trust me" -- they would understand what the differences
are.

Re: Cleaning up git user-interface warts

[Alexandre Julliard]

Junio C Hamano <junkio@cox.net> writes:

> I would rather say "use 'git branch' to make sure if you are
> ready to merge".  Who teaches not to use "git pull"?

We do that for Wine. The problem is that we recommend using git-rebase
to make it easier for occasional developers to keep a clean history,
and rebase and pull interfere badly.

The result is that we recommend always using fetch+rebase to keep up
to date, but this is confusing many people too, because git-fetch
appears to do a lot of work yet leaves the working tree completely
unchanged, and git-rebase doesn't do anything (since in most cases
they don't have commits to rebase) but has an apparently magical
side-effect of updating the working tree.

Ideally it should be possible to have git-rebase do the right thing
even if the branch has been merged into; then we could tell people to
always use git-pull, and when they get confused by seeing merges in
their history have them do a git-rebase to clean things up.

-- 
Alexandre Julliard

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Thu, Nov 16, 2006 at 12:34:27PM CET, Alexandre Julliard wrote:
> Junio C Hamano <junkio@cox.net> writes:
> 
> > I would rather say "use 'git branch' to make sure if you are
> > ready to merge".  Who teaches not to use "git pull"?
> 
> We do that for Wine. The problem is that we recommend using git-rebase
> to make it easier for occasional developers to keep a clean history,
> and rebase and pull interfere badly.

How do those developers submit their changes? Do they push? If they do,
git-rebase can be saving one merge at most, and the merge is actually a
good thing (someone should write some nice standalone writeup about
that).

If they don't have push access and maintain their patches locally until
they get accepted, perhaps it would be far simpler for them to use
StGIT?

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Alexandre Julliard]

Petr Baudis <pasky@suse.cz> writes:

> How do those developers submit their changes? Do they push? If they do,
> git-rebase can be saving one merge at most, and the merge is actually a
> good thing (someone should write some nice standalone writeup about
> that).

No, they use git-format-patch and mail them in.

> If they don't have push access and maintain their patches locally until
> they get accepted, perhaps it would be far simpler for them to use
> StGIT?

For regular developers, sure. But regular developers will need to
properly understand the git model anyway, and then they will able to
make sense even of the standard git commands ;-)  The problem is that
there isn't a smooth progression to that point.

At first, a user will simply want to download and build the code, and
for that git-pull works great, it's a one-stop command to update their
tree.

Then after a while the user will fix a bug here and there, and at that
point git-rebase is IMO the best tool, it's reasonably easy to use,
doesn't require learning other commands, and once the patch is
accepted upstream it nicely gets the tree back to the state that the
user is familiar with.

The problem is that rebase doesn't work with pull, so the user needs
to un-learn git-pull and start using git-fetch; it's to avoid this
that we recommend using git-fetch from the start, which is unfortunate
since it makes things harder for beginners.

-- 
Alexandre Julliard

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Alexandre Julliard wrote:

> Junio C Hamano <junkio@cox.net> writes:
> 
>> I would rather say "use 'git branch' to make sure if you are
>> ready to merge".  Who teaches not to use "git pull"?
> 
> We do that for Wine. The problem is that we recommend using git-rebase
> to make it easier for occasional developers to keep a clean history,
> and rebase and pull interfere badly.

What about proposed (and I think not accepted) merge strategy
"rebase" (formerly called "subordinate" or something like that)?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Alexandre Julliard]

Jakub Narebski <jnareb@gmail.com> writes:

> Alexandre Julliard wrote:
>
>> Junio C Hamano <junkio@cox.net> writes:
>> 
>>> I would rather say "use 'git branch' to make sure if you are
>>> ready to merge".  Who teaches not to use "git pull"?
>> 
>> We do that for Wine. The problem is that we recommend using git-rebase
>> to make it easier for occasional developers to keep a clean history,
>> and rebase and pull interfere badly.
>
> What about proposed (and I think not accepted) merge strategy
> "rebase" (formerly called "subordinate" or something like that)?

That sounds very interesting. Has it ever been implemented, or only
discussed?

-- 
Alexandre Julliard

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Alexandre Julliard wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
>> Alexandre Julliard wrote:
>>> Junio C Hamano <junkio@cox.net> writes:
>>> 
>>>> I would rather say "use 'git branch' to make sure if you are
>>>> ready to merge".  Who teaches not to use "git pull"?
>>> 
>>> We do that for Wine. The problem is that we recommend using git-rebase
>>> to make it easier for occasional developers to keep a clean history,
>>> and rebase and pull interfere badly.
>>
>> What about proposed (and I think not accepted) merge strategy
>> "rebase" (formerly called "subordinate" or something like that)?
> 
> That sounds very interesting. Has it ever been implemented, or only
> discussed?

There was some implementation with warts

  http://thread.gmane.org/gmane.comp.version-control.git/30068
  Message-Id: <20061025155009.GD5591@parisc-linux.org>

which didn't got corrected and resent.
-- 
Jakub Narebski

Re: Cleaning up git user-interface warts

[Theodore Tso]

On Wed, Nov 15, 2006 at 08:21:36PM -0800, Junio C Hamano wrote:
> Theodore Tso <tytso@mit.edu> writes:
> > So with Bitkeeper, with "bk pull" there was never any question about
> > which branch ("line of development") you would be merging into after
> > doing a "bk pull", since there was only one LOD, and given that BK had
> > the rule that a within a LOD only one tip was allowed, a "bk pull"
> > _had_ to do do a merge operation.   
> 
> I've never used Bk and I really appreciate your comments here.
> 
> > If you are operating on your local development branch, the reality is
> > that merging is probably not the right answer in the general case,
> 
> I agree, but I wonder why you are pulling/fetching (with or
> without merge) if you are operating on your local development
> branch (implying that you are in the middle of something else).

Well, when I was using BitKeeper, I never would.  Bitkeeper has what
Linus calls the broken "repository == branch" model.  So normally I
would have one repository where I would track the upstream branch, and
only do bk pull into that branch.  I would do my hacking in another
repository (i.e., branch), and periodically keep track wha was going
on in mainline by cd'ing to the mainline repository and doing the bk
pull there.  

The challenge when you put multiple branches into a single repository,
is you have to keep track of which branch you happen to be in.  In the
BK world, this was obvious because it would show up in my shell
prompt:

<tytso@candygram>       {/usr/src/linux-2.6}
2% 

(OK, obviously I'm in the Linux 2.6 upstream repository)

In a system where you need to keep track of what branch you are in via
an SCM-specific local state information, it's easy to get confused and
do a pull when you are in the "wrong" branch, or while you have local
state in your working directory.   

What I currently do (and I'm sure I'm being really horrible and need
to be say 100 "Hail, Linus"'es for penance for not adhering staying in
the one true distributed state of grace) is that I keep an entirely
separate Linux 2.6 git repository just to make sure I never get
confused about what branch I might happen to be in when I do the "git
pull" --- and yeah, I could have used "git fetch", but 3+ years of BK
usage plus Hg usage is hard to get away from.  I'm sure this is where
Linus would say that use of BK and Hg, causes permanent brain damage,
ala's Dijkstra's ofted quoted comment about use of Basic inducing
brain damage....

> I have to disagree with this.  In the simplest CVS-like central
> repository with single branch setup in which many "novice users"
> start out with, there is almost no need for "git fetch" nor
> tracking branch.  You pull, resolve conflicts, attempt to push
> back, perhaps gets "oh, no fast forward somebody pushed first",
> pull again, then push back.  So I am not sure where "you really
> do not want to use pull.  trust me" comes from.

I think the problem is the people who have had years of BK or Hg
experience.  Maybe it's more of a documentation problem; perhaps a
"git for BK" or "git for Hg" users is what's needed.  The problem
though is that while use of BK is definitely legacy, there are going
to be a lot of people who need to use both BK and Hg.   

> It is a different story for people who _know_ git enough to know
> what is going on.  They may be using multiple branches and
> interacting with multiple remote branches, and there are times
> you would want fetch and there are other times you would want
> pull.  But for them, I do think the suggestion would never end
> with "trust me" -- they would understand what the differences
> are.

Well, I think this is where git's learning curve challenges are.  Yes,
for users that are doing the stupidest, most simplistic usage models,
git is quite easy to use.  And I am willing to grant that for people
who are using the deepest, most complicated and most distributed
development, who understand multiple branches and the index, and all
of the deep git plumbing, there's also no problem.

The challenge is in between; to use a car analogy, git has a great
automatic transmision, and an extremely powerful "racing clutch".  But
for someone where the automatic transmission isn't good enough, when
as they start to learn how to use the manual transmission, git's
extremely touchy "racing clutch" is much more difficult master ---
especially in comparison to people who have learned to drive other,
more pedestrian "standard transmission" cars.  So people who try to
use git's racing clutch keep stalling out the car, and some give up in
frustration.

And maybe the problem is one that should be addressed only by lots of
training, but at the moment, that's the reason why I believe a number
of projects have chosen Hg instead of git; they need more than the
"stupid simple" git usage, but if they don't need the extreme power of
git, Hg is simpler for people to learn how to use.  The problem, of
course, comes when later on, the project finds out they really want
git's power, and now they have to deal with the repository conversion
as well as retraining their entire development community.

But hey, maybe this isn't a problem the git community wants to solve;
clearly git is optimized for the Linux kernel development, and maybe
it's too much to ask that it also work well for somewhat less
extremely distributed development models.  But in any case, that's why
I chose Hg for e2fsprogs.  At the time when I made my choice, git was
just too painful to learn how to use its more esoteric features, and
Hg was much closer to BK's model.  (Since then, Hg has added more
functionality, including better multiple branches in a repository
support, and it's gotten more complicated, but it's still much simper
to teach someone how to use Hg than git.)

Regards,

Re: Cleaning up git user-interface warts

[Theodore Tso]

On Thu, Nov 16, 2006 at 11:07:00AM -0500, Theodore Tso wrote:
> I think the problem is the people who have had years of BK or Hg
> experience.  Maybe it's more of a documentation problem; perhaps a
> "git for BK" or "git for Hg" users is what's needed.  The problem
> though is that while use of BK is definitely legacy, there are going
> to be a lot of people who need to use both BK and Hg.   

Err, what I meant to say is that there are going to be a lot of people
who will need to simultaneously use both git and Hg.

Re: Cleaning up git user-interface warts

[Sanjoy Mahajan]

The car analogy is excellently clear.

> they need more than the "stupid simple" git usage, but if they don't
> need the extreme power of git, Hg is simpler for people to learn how
> to use.

As a 80%-hg/20%-git user, I'm curious what features of git you had in
mind, so I know where to look as I wander up the git learning curve.

My experience with the git user interface, for what it's worth, is
that I never quite get the conceptual model crystal clear enough in my
head. So it won't stay for long enough for me to progress up the
learning curve and retain the gains.  I move up a bit, but the gain
soon evaporates and I backslide, and then just hack my way through it.

I found hg's conceptual model very easy to learn, almost as if I don't
have to remember anything.  Maybe that simplicity comes at a price,
whence my question at the start about the extreme-power features of
git.

-Sanjoy

`Never underestimate the evil of which men of power are capable.'

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Sanjoy Mahajan wrote:

> The car analogy is excellently clear.
> 
>> they need more than the "stupid simple" git usage, but if they don't
>> need the extreme power of git, Hg is simpler for people to learn how
>> to use.
> 
> As a 80%-hg/20%-git user, I'm curious what features of git you had in
> mind, so I know where to look as I wander up the git learning curve.
> 
> My experience with the git user interface, for what it's worth, is
> that I never quite get the conceptual model crystal clear enough in my
> head. So it won't stay for long enough for me to progress up the
> learning curve and retain the gains.  I move up a bit, but the gain
> soon evaporates and I backslide, and then just hack my way through it.
> 
> I found hg's conceptual model very easy to learn, almost as if I don't
> have to remember anything.  Maybe that simplicity comes at a price,
> whence my question at the start about the extreme-power features of
> git.

As I never used Mercurial (hg), only read a bit about it and discussed on
#revctrl, I cannot say what features git has that hg has not, but I can
tell what powerfull git features differ from other SCM.

First, usually in other SCM the concept of branch is closely tied to the
concept of repository, perhaps allowing to share storage between branches
on the same local filesystem (on the same machine). In git, repository
holds DAG, the graph of revisions (of versions). Branches are "only" ways
to access this graph, and to extend it of the new commits. This makes git
more powerfull, but also perhaps unnecessary complicated if you deal with
single-branch repositories, or few-branch case. Additionally this
"complication" makes very clean model of repository - but you have to
understand it...

Second, the index. One might think that it is performance hack, but it
allows for commiting changes piece by piece and, what is more important,
a place form making merge in. Cogito (alternate Git UI/porcelain) tries to
hide index. By the way, I wonder how hg does merges without index to
provide place where do merges in...

Third, explicit/on-demand packing. This allows for the most (I think)
compression of all SCMs, and for the wire format to be the same as on-disk
format (with the addition that you can send thin packs on wire). As of now
no porcelain tries to hide it, although with the latest work allowing for
historical packs it would be easy to add this without significantly
affecting preformance.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Linus Torvalds escreveu:
>  - git itself has now done it that way for the last 18 months, and the 
>    fact is, the people _complaining_ are a small subset of the people who 
>    actually use git on a daily basis and don't complain.


that's not a good argument; the set of git users is a small subset of 
those that looked at git, and dismissed it because they couldn't wrap 
their heads around it.   It's worth trying to get those on board by 
fixing the annoying little issues that have popped up in this thread. 
The technical base for GIT is excellent, and the only reason for not 
using it is its arcane interface.

A version control system is often only tangentially related to the real 
work that needs to be done, so the incentive to learn it well is small, 
   and a steep learning curve only makes it worse.

FWIW, I regularly mess up with the differences between fetching, pulling 
and merging.  In particular, having to do a two step process to get 
remote changes in,

   git pull url-to-server master:master
      ..error message about not being a fast-forward..

   git pull --update-head-ok url-to-server master:master
      ..still an error message about update not being a fast-forward..

       (sigh)

   git pull url-to-server master:scrap-branch

   git pull . scrap-branch:my-current-branch

       (make mental note of deleting scrap-branch)


-- 

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Han-Wen Nienhuys wrote:

> FWIW, I regularly mess up with the differences between fetching, pulling 
> and merging.  In particular, having to do a two step process to get 
> remote changes in,
> 
>    git pull url-to-server master:master
>       ..error message about not being a fast-forward..
> 
>    git pull --update-head-ok url-to-server master:master
>       ..still an error message about update not being a fast-forward..

What about:

     git pull --update-head-ok url-to-server +master:master

(or --force, but be careful with that one)?
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Han-Wen Nienhuys <hanwen@xs4all.nl> writes:

> FWIW, I regularly mess up with the differences between fetching,
> pulling and merging.  In particular, having to do a two step process
> to get remote changes in,
>
>   git pull url-to-server master:master
>      ..error message about not being a fast-forward..
>
>   git pull --update-head-ok url-to-server master:master
>      ..still an error message about update not being a fast-forward..
>
>       (sigh)

Sigh indeed.

Why don't you do the simple and obvious

	git pull url master

or "git pull url" if you already know the master is the branch
you are interested in.

The more advanced form of using tracking branches are there and
documentation talks about them for completeness but that does
not mean you have to use it.

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Junio C Hamano escreveu:
>> FWIW, I regularly mess up with the differences between fetching,
>> pulling and merging.  In particular, having to do a two step process
>> to get remote changes in,
>>
>>   git pull url-to-server master:master
>>      ..error message about not being a fast-forward..
>>
>>   git pull --update-head-ok url-to-server master:master
>>      ..still an error message about update not being a fast-forward..
>>
>>       (sigh)
> 
> Sigh indeed.
> 
> Why don't you do the simple and obvious
> 
> 	git pull url master

It is not all evident from the git-pull man-page that this is the 
obvious and most common usage.

> or "git pull url" if you already know the master is the branch
> you are interested in.

Because I usually replace verbose commands with shortcuts only when I 
understand exactly what the shortcut is.

To me it's very unlogical that

   master:current-branch

doesn't work, but

   master:

does work, and does what I'd expect

   master:current-branch

to do. Interestingly, doing

   pull ..url.. master:HEAD

also doesn't merge into the current branch, but rather creates a bogus 
refs/heads/HEAD

I use the remote:local syntax, because I started using GIT in scripted 
compiles from copied branches of remote repositories. There the explicit 
remote:local statements are necessary because there is no default branch.

-- 

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Han-Wen Nienhuys <hanwen@xs4all.nl> writes:

> Junio C Hamano escreveu:
>>...
>> Sigh indeed.
>>
>> Why don't you do the simple and obvious
>>
>> 	git pull url master
>
> It is not all evident from the git-pull man-page that this is the
> obvious and most common usage.

In the git user poll a few months ago, many people recommended
"everyday git" as a good cheat sheet, and indeed it does not
talk anything about directing the underlying git-fetch to
manipulate tracking branches by giving explicit refspec pairs to
git pull.  You are obviously tripped by both the overeager
manpage (but manpage should strive to be complete so you cannot
really blame it) and less than optimally organized tutorial
style documents.

I myself do prefer, when learning a new tool, to use longhand
until I understand the shorthand, but that attitude requires a
true commitment to learn the tool, and most people do not go
that route.  Tutorial style documents tend to give the commonly
used shorthand first for that exact reason.

Shorthand to give only the branch name to fetch and merge
immediately without using a tracking branch is equivalent to
longhand "branch:" as you found out, so if that was what was
desired then people with the attitude "before understanding what
longhand does I prefer using shorthand" like myself and you
would have liked to learn "git pull url branch:" notation from
Tutorial.  But I think we _are_ minority.  People would not want
to see that seemingly useless colon there.

> To me it's very unlogical that
>
>   master:current-branch
>
> doesn't work,

That shows that you did not understand what fetch does.  Maybe
you do now, but a very natural consequence of directing fetch to
update tracking branches with the colon notation is:

 - "pull url master:master", while on master, is almost always
   wrong and not something you would want to do, ever.

   "fetch --update-head-ok url +master:master; reset --hard HEAD"

   may make sense but never "pull".

> I use the remote:local syntax, because I started using GIT in scripted
> compiles from copied branches of remote repositories. There the
> explicit remote:local statements are necessary because there is no
> default branch.

If you perhaps wanted to ask "is there a better way to do what
I've been doing?", then I am willing to think with you to come
up with an answer.  Unfortunately, however, I do not understand
the above paragraph, so I'd refrain from commenting on it in
this response.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

(not changing what I said but editorial)
> I myself do prefer, when learning a new tool, to use longhand
> until I understand the shorthand, but that attitude requires a
> true commitment to learn the tool, and most people do not go
> that route.  Tutorial style documents tend to give the commonly
> used shorthand first for that exact reason.

Eh, sorry, "prefer to use longhand until I understand what is
going on before using the shorthand" is what I wanted to say.

> Shorthand to give only the branch name to fetch and merge
> immediately without using a tracking branch is equivalent to
> longhand "branch:" as you found out, so if that was what was
> desired then people with the attitude "before understanding what
> longhand does I prefer using shorthand" like myself and you

"prefer not using shorthand", sorry again.

> would have liked to learn "git pull url branch:" notation from
> Tutorial.  But I think we _are_ minority.  People would not want
> to see that seemingly useless colon there.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

> Han-Wen Nienhuys <hanwen@xs4all.nl> writes:
>
>> Junio C Hamano escreveu:
>>>...
>>> Sigh indeed.
>>>
>>> Why don't you do the simple and obvious
>>>
>>> 	git pull url master
>>
>> It is not all evident from the git-pull man-page that this is the
>> obvious and most common usage.
>
> In the git user poll a few months ago, many people recommended
> "everyday git" as a good cheat sheet, and indeed it does not
> talk anything about ...

Sorry, I must have been very grumpy mood when I wrote the
message (cf. Pasky's utterance on #git a few days ago).  What I
wrote was a bit incoherent, so here is an attempt to clarify.

I should point out that the colon separated refspec pairs you
can give to "pull" was designed with considerable thought; it is
not a convenience hack that we give them to "pull" that "fetches
and merges".  Linus's and Michael's other messages in this
thread may seem to be saying that using tracking branches is not
a kosher way to use git, but I do not think that is a correct
interpretation of their messages.

The workflow that does not use any tracking branches is the
simplest and truly distributed way as Linus says.  The command
recommended in "everyday git" document:

	git pull $url $branchname

is the most natural way to express it, and simplest variant that
you do not have to say anything "colon" in it.

However that does not mean it is a bad practice to use tracking
branches.  Sometimes it is handy to be able to refer to what you
fetched from the remote the last time, possibly which is what
you merged into your branch if that last fetch was done via "git
pull", so that you can later examine its history without your
own development.  For that purpose, you need to store what you
fetched in your local refs/ namespace, and that is what tracking
branches are.

The workflow that fetches to tracking branches and then merges
within local repository as two separate steps loses the true
origin information ("Merge branch 'foo'" vs "Merge branch 'foo'
of git://git.bar.xz/foo.git").  That's the reason why not just
"git fetch" but also "git pull" take the colon separated refspec
pairs to direct git to update the tracking branches when "pull"
happenes.  The longhands are cumbersome to type all the time,
and we have shorthand, both to store URL: and Pull: lines in
remotes/ hierarchy, and also $branchname alone is a shorthand
for saying "${branchname}:", meaning "do not use a tracking
branch to store this".

So you have options to use or not to use tracking branches.
After cloning we happen to default to track all remote branches
with corresponding local tracking branches, but that is only
because may people on the list wanted to make life easier to CVS
migrants where following mostly static set of branches is the
norm ("set" is the static part: I do not mean the branches stay
still) and we wanted to make it easier for them.

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Han-Wen Nienhuys wrote:

> Linus Torvalds escreveu:
> >  - git itself has now done it that way for the last 18 months, and the
> > fact is, the people _complaining_ are a small subset of the people who
> > actually use git on a daily basis and don't complain.
> 
> 
> that's not a good argument; the set of git users is a small subset of those
> that looked at git, and dismissed it because they couldn't wrap their heads
> around it. 

And I've said this again, and I'll say it once more: that has basically 
_nothing_ to do with whether you spell "pull" as "pull" or "merge".

The reason people have trouble wrapping their heads around git is because 
they have been braindamaged by CVS and SVN, and just don't understand the 
fairly fundamental new concepts and workflow.

That's totally different from then arguing about stupid naming issues.

Peopel seem to believe that changign a few names or doing other totally 
_minimal_ UI changes would somehow magically make things understandable. I 
claim that isn't so at all. The fact is, git is different from CVS and 
SVN, and git _has_ to be different from CVS and SVN. It has to be 
different because the whole model of CVS and SVN is simpyl fundamentally 
BROKEN.

> It's worth trying to get those on board by fixing the annoying
> little issues that have popped up in this thread.

I claim that those "annoying little issues" are totally made up by people 
who had trouble wrapping their minds about git, and then make up reasons 
that have nothing to do with reality for why that might be so.

Let's face it, you could just alias "merge" to "pull", and it wouldn't 
really change ANYTHING. You'd still have to learn the new model. 

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

> And I've said this again, and I'll say it once more: that has basically 
> _nothing_ to do with whether you spell "pull" as "pull" or "merge".
>
> The reason people have trouble wrapping their heads around git is because 
> they have been braindamaged by CVS and SVN, and just don't understand the 
> fairly fundamental new concepts and workflow.
> ...
> Let's face it, you could just alias "merge" to "pull", and it wouldn't 
> really change ANYTHING. You'd still have to learn the new model. 

I had a bit different feeling about yesterday's discussion
myself.

If somebody uses git like you do in "truly distributed way", the
current pull behaviour and pull being an operational mirror to
push are natural consequence of the model and concepts, and
there is nothing to fix (modulo "the default merge source per
branch" should be made easier to use).  Renaming the pull to
merge would not make it any easier to use unless the underlying
model is understood, and I fully agree with you on that.

But for people working in a project organized around central
repository in the CVS/SVN fashion, the workflow is quite
different.  CVS does not even let you "fetch" without either
merging (co) or throwing away your work (co -C), and we already
do support that model with:

	git clone
        git pull
        work work work; git commit
        git push
        : oops not fast forward?
        git pull
        resolve work; git commit
	git push

without ever using a local branch, any tracking branch, nor
use of git-fetch.  So we do support both extremes ("truly
distributed" and "not distributed at all") reasonably well.

The trouble starts when the users hear about this wonderful
"distributed" stuff git offers, and try to use it without
understanding the key concepts.  People tend to learn by doing
and there is a leap the user need to make because now they need
to understand branched development, branches and fetching like
you explained if they want to use git the same way as you do.
Once they understand them, then the current set of tools offer
them a simple and very straightforward user interface (the tools
directly reflect the concepts and it is straightforward only
because we are talking about users who understood the concepts).

But we have to admit that this leap may rather be difficult for
people who are used to other models.  Telling them that our
model is different and it is different for a good reason does
not change the fact that the more different something is, the
more difficult to learn it.

I suspect that there could be a way to use git, not like you or
I do.  Our workflows are already quite different (e.g. you
almost never do topic branch merge yourself in your repository,
but I have abundance of them).  There is no reason to think
there won't be other workflows that are suitable for other
people.  Some workflows might be classified less distributed and
inferiour compared to the "truly git way" from "truly
distributed is the point of git" point of view, but nevertheless
could be "good enough" for those people.  In other words, a
workflow that is a bit more advanced than just a single trunk
CVS/SVN usage could still take advantage of some of the features
to support distributed development model git has, while not
taking full advantage of truly distributed nature of git.

I think the complaints in the yesterday's discussion are mostly
about frustration that, while we have a reasonable support for
the both extremes, we do not either know what that middle ground
workflow is, or even if we know what that is, we do not support
it very well.

And I am not opposed to people exploring what that different
workflow would be, and while they do so if they come up with a
set of commands (get/put perhaps) to suppor that slightly
different workflow, that would be a very good thing.

Add foreign SCM importers in the mix and the situation becomes
more difficult and interesting.  cvsimport mostly works and
quacks like git-fetch with set of tracking branches, which I
think is the right model for the importers, and would integrate
well with the current set of tools.  I believe svnimport is the
same way.  But I do not know about git-svn.

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Linus Torvalds escreveu:
>>>  - git itself has now done it that way for the last 18 months, and the
>>> fact is, the people _complaining_ are a small subset of the people who
>>> actually use git on a daily basis and don't complain.
>>
>> that's not a good argument; the set of git users is a small subset of those
>> that looked at git, and dismissed it because they couldn't wrap their heads
>> around it. 
> 
> And I've said this again, and I'll say it once more: that has basically 
> _nothing_ to do with whether you spell "pull" as "pull" or "merge".
> 
> The reason people have trouble wrapping their heads around git is because 
> they have been braindamaged by CVS and SVN, and just don't understand the 
> fairly fundamental new concepts and workflow.

 > I claim that those "annoying little issues" are totally made up by
 > people
 > who had trouble wrapping their minds about git, and then make up
 > reasons
 > that have nothing to do with reality for why that might be so.

Let me put this more personally: I continue to be bitten by stupid 
naming issues, and the myriad of little mostly non-orthogonal commands.
My head is doing just fine otherwise, and has no problems wrapping it 
around the core of GIT.  I've also used Darcs for almost a year. Darcs, 
which is much less overwhelming.

This is not about CVS or SVN, so don't put them up as a strawman.
If you want to argue that my brain is warped, use other distributed VCs 
as an example.

The following

   mkdir x y
   cd x
   hg init
   echo hoi > bla
   hg add
   hg commit -m 'yes, I am also too stupid to refuse explicit empty 
commit messages'
   cd ../y
   hg init
   hg pull ../x

pretty much works the same in Darcs, bzr and mercurial.

With GIT, this is what happens

[hanwen@haring y]$ git pull ../x
fatal: Needed a single revision
Pulling into a black hole?

[hanwen@haring y]$ git fetch ../x
warning: no common commits
remote: Generating pack...
Done counting 3 objects.
Deltifying 3 objects.
  100% (3/3) done
Total 3, wremote: ritten 3 (delta 0), reused 0 (delta 0)
Unpacking 3 objects
  100% (3/3) done

[hanwen@haring y]$ git checkout
fatal: ambiguous argument 'HEAD': unknown revision or path not in the 
working tree.
Use '--' to separate paths from revisions
fatal: Not a valid object name HEAD

[hanwen@haring y]$ git branch master
fatal: Needed a single revision

at this point, I resort to adding a bogus commit and/or editing 
.git/HEAD by hand. I'm sure there is a saner way of doing it, but I 
still haven't found out what it is.

This might not be typical GIT use, but it does show the typical GIT user 
experience, at least mine.

If you want to have another example of how not to design a 
user-interface, try the above on Monotone.

> That's totally different from then arguing about stupid naming issues.
> 
> Peopel seem to believe that changign a few names or doing other totally 
> _minimal_ UI changes would somehow magically make things understandable. I 
> claim that isn't so at all. The fact is, git is different from CVS and 
> SVN, and git _has_ to be different from CVS and SVN. It has to be 
> different because the whole model of CVS and SVN is simpyl fundamentally 
> BROKEN.
> 
>> It's worth trying to get those on board by fixing the annoying
>> little issues that have popped up in this thread.
> 
> 
> Let's face it, you could just alias "merge" to "pull", and it wouldn't 
> really change ANYTHING.

I don't want ANYTHING to really change, I just want a sane interface to it.


-- 
  Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Han-Wen Nienhuys <hanwen@xs4all.nl> writes:

You claim it is _an interface_ issue but it is not.

> With GIT, this is what happens
>
> [hanwen@haring y]$ git pull ../x
> fatal: Needed a single revision
> Pulling into a black hole?

You asked it to fetch from the neighbour repository and merge it
into your current branch which does not exist (I presume that
you omitted to describe what you did in directory y/ and I am
assuming you did "mkdir y && cd y && git initdb" and nothing
else).  You are pulling into a black hole.

> [hanwen@haring y]$ git fetch ../x
>...
> [hanwen@haring y]$ git checkout

You fetched without telling it in which tracking branch to store
what you fetched, and as a result your HEAD is not updated, so
your current branch still does not exist.  A failure from
checking out nothingness is not an interface issue; expectation
for it to work is a concept level issue.

> [hanwen@haring y]$ git branch master
> fatal: Needed a single revision

You are not at any commit yet and you try to create a branch?

Of course, the "right" (in some sense of the word) thing is to
do "git clone x y" in the parent directory, without creating y
upfront.

If you have an empty y to begin with, then you can do this:

	$ git fetch ../x :origin
        $ git reset --hard origin

which would mirror a part of what "git clone" would have done
for you.  It copies from the other repository, stores the tip in
your tracking branch called "origin", and make your HEAD to be
the same as origin.  After these two commands, you would have
two branches, origin and master, and you will be on master.

You can name 'origin' any way you want.  You might want to name
it 'x' to make it clear (to yourself) that it is used to track
what will happen in the neighboring repository 'x'.  Also, you
would most likely be fetching and merging from the same ../x
from now on, so it might be handy to set up the remotes for it:

	$ cat >.git/remotes/x <<EOF
        URL: ../x
        Pull: master:origin
	EOF

Then subsequent work of yours would be done on 'master' branch
(you have only two branches, and origin is a tracking branch so
you will never make commits on it, which means the above is a
logical consequence), and from time to time you would sync with
whoever is working in ../x

	$ git pull x

Here, 'x' is just a shorthand which looks up the URL: and Pull: line
through .git/remotes/x.  If your .git/remotes/ file was named origin
(not x), you could even have written:

	$ git pull

because pull defaults to 'origin' (without any other configuration).

>> Let's face it, you could just alias "merge" to "pull", and it
>> wouldn't really change ANYTHING.
>
> I don't want ANYTHING to really change, I just want a sane interface to it.

I agree that you do not want to change anything.  You just
needed a bit of handholding, because you deviated from the
cookbook usage, to correct your course.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

> Han-Wen Nienhuys <hanwen@xs4all.nl> writes:
>
>> [hanwen@haring y]$ git pull ../x
>> fatal: Needed a single revision
>> Pulling into a black hole?

Having said all that, I happen to think that this particular
case of pulling into void could deserve to be special cased to
pretend it is a fast forward (after all, nothingness is an
ancestor of anything), if only to make new people's first
experience more pleasant.

Working from nothingness is something not usually done in
everyday work, so from practical and technical point of view it
does not add much _real_ value to the people who actually uses
the system, but nevertheless, new people typically start
learning the system from either cloned repository (which I
believe is covered by the existing tools fairly well) or
emptiness (which bitten us here in a bad way), and making the
first experience more pleasnt to new people have a positive
value of flattening the learning curve.

So please consider that this is classified as a bug.

Re: Cleaning up git user-interface warts

[Horst H. von Brand]

Junio C Hamano <junkio@cox.net> wrote:
> Junio C Hamano <junkio@cox.net> writes:
> > Han-Wen Nienhuys <hanwen@xs4all.nl> writes:
> >
> >> [hanwen@haring y]$ git pull ../x
> >> fatal: Needed a single revision
> >> Pulling into a black hole?
> 
> Having said all that, I happen to think that this particular
> case of pulling into void could deserve to be special cased to
> pretend it is a fast forward (after all, nothingness is an
> ancestor of anything), if only to make new people's first
> experience more pleasant.

If you make pushing into an empty repository work also, you fix the case of
"create an empty repo for somebody, let them fill it up remotely later".

[...]

> So please consider that this is classified as a bug.

Thanks!
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239

Re: Cleaning up git user-interface warts

[Shawn Pearce]

"Horst H. von Brand" <vonbrand@inf.utfsm.cl> wrote:
> If you make pushing into an empty repository work also, you fix the case of
> "create an empty repo for somebody, let them fill it up remotely later".

This seems to work just fine now.  I do it all of the time.

-- 

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Horst H. von Brand wrote:
> Junio C Hamano <junkio@cox.net> wrote:
>> Junio C Hamano <junkio@cox.net> writes:
>>> Han-Wen Nienhuys <hanwen@xs4all.nl> writes:
>>>
>>>> [hanwen@haring y]$ git pull ../x
>>>> fatal: Needed a single revision
>>>> Pulling into a black hole?
>> 
>> Having said all that, I happen to think that this particular
>> case of pulling into void could deserve to be special cased to
>> pretend it is a fast forward (after all, nothingness is an
>> ancestor of anything), if only to make new people's first
>> experience more pleasant.
> 
> If you make pushing into an empty repository work also, you fix the case of
> "create an empty repo for somebody, let them fill it up remotely later".

That was only the _pull_ which didn't work in empty repo.
Fetch and push worked (and work) just fine with empty repo.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Junio C Hamano escreveu:
> You claim it is _an interface_ issue but it is not.

 >> I don't want ANYTHING to really change, I just want a sane interface 
 >> to it.
 >
 > I agree that you do not want to change anything.  You just
 > needed a bit of handholding, because you deviated from the
 > cookbook usage, to correct your course.

Users (well, I do at least) start fiddling with systems to find out how 
they work.   Reading the manual is usually done as a last resort. I 
think this is pretty well documented in usability research.

I'm trying to show how GIT is badly suited to this. Your response is to 
explain to me what I should have done. That's nice, but that approach 
doesn't scale, because you don't reach the dozens of users out there who 
try the same, fail and give up.

If you really want to find out the weaknesses, you'd have to sit someone 
new to git in front of a computer, and let him figure how to operate it, 
while videotaping everything.

Writing a manual for newbies is also an effective (and simpler and 
cheaper) approach of figuring out what needs to be changed.



As another example:  annoyances regarding program invocation

  - option handling: -x -f -z != -xfz , "--max-count 1" doesn't work, 
but needs an '='

  - git --help lists an unordered set, which is too long scan quickly. 
I'd expect that list to either contain everything or the minimum set for 
daily use. I.e. the set introduced in a first tutorial.  Why are merge, 
prune, verify-tag there?

Try "bzr help" for comparison.

  - --pretty option with wholly uninformative options full, medium, 
short, raw.  It's not even documented what each option does.


I can go on with listing idiosyncrasies, but my point is not to get help 
from you, but rather to show how git can be improved.


>> With GIT, this is what happens
>>
>> [hanwen@haring y]$ git pull ../x
>> fatal: Needed a single revision
>> Pulling into a black hole?
> 
> You asked it to fetch from the neighbour repository and merge it
> into your current branch which does not exist (I presume that
> you omitted to describe what you did in directory y/ and I am
> assuming you did "mkdir y && cd y && git initdb" and nothing
> else).  You are pulling into a black hole.

as you remark in the other reply, there is IMO no reason for not having 
an empty 'master' branch. If master + HEAD gets created on the first 
commit, it might as well be created on the init-db.

-- 
  Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Han-Wen Nienhuys escreveu:

> I can go on with listing idiosyncrasies, but my point is not to get help 
> from you, but rather to show how git can be improved.

oh, and another annoying one: git's insistence on firing up a pager if 
there is nothing to page, eg. try

   git-log je-n-existe-pas

-- 
  Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Han-Wen Nienhuys wrote:

> As another example:  annoyances regarding program invocation
> 
>   - option handling: -x -f -z != -xfz , "--max-count 1" doesn't work, 
> but needs an '='

That's true, and the probable cause is that git tries to first, avoid
dependency on options parsers like getopt/getopt_long/argp or popt for
commands in C, getopt for commands in shell, Getopt::Std/Getopt::Long for
commands in Perl, and something for commands in Python (if there are any
left); second, existing options parsers do not deal (I think) with
distinction between arguments to wrapper and arguments to command, '--' to
separate revisions from pathnames not options from arguments, and the whole
revisions and revision list specifying syntax (where "a --not b" is not
equivalent to "--not a b").

That said, perhaps we should craft our own options parsing (or modify
existing one)...

>   - git --help lists an unordered set, which is too long scan quickly. 

It is one page of alphabetically ordered commands.

git(7) gives whole list of commands, divided into categories, by the way.

> I'd expect that list to either contain everything or the minimum set for 
> daily use. I.e. the set introduced in a first tutorial.  Why are merge, 
> prune, verify-tag there?
> 
> Try "bzr help" for comparison.

I wonder why "repack" isn't there, if "prune" is.

>   - --pretty option with wholly uninformative options full, medium, 
> short, raw.  It's not even documented what each option does.

And 'oneline' and undocumented 'email'. True, git lacks documentation (and
this one of main complaints in git survey).
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Jakub Narebski escreveu:

>>   - --pretty option with wholly uninformative options full, medium, 
>> short, raw.  It's not even documented what each option does.
> 
> And 'oneline' and undocumented 'email'. True, git lacks documentation (and
> this one of main complaints in git survey).

The recently posted patch documenting is an improvement, but why not
add an option so you can do

  --format 'committer %c\nauthor %a\n'
  
this catches all combinations, and is easier for scripting.

Right now, I have some scripts that have to munge log output with
regular expressions to strip out the "author:"  prefixes.


-- 
 Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Han-Wen Nienhuys wrote:

> Jakub Narebski escreveu:
> 
>>>   - --pretty option with wholly uninformative options full, medium, 
>>> short, raw.  It's not even documented what each option does.
>> 
>> And 'oneline' and undocumented 'email'. True, git lacks documentation (and
>> this one of main complaints in git survey).
> 
> The recently posted patch documenting is an improvement, but why not
> add an option so you can do
> 
>   --format 'committer %c\nauthor %a\n'
>   
> this catches all combinations, and is easier for scripting.
> 
> Right now, I have some scripts that have to munge log output with
> regular expressions to strip out the "author:"  prefixes.

If we ever implemented this, I'd rather to separate what is now of format
parsing in git-for-each-ref (although I'd like to make it more like rpm's
--query-format argument, with %-n{header}, %[array] etc.) into separate
module, and reuse it for git-log and friends --pretty/--format handling.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Johannes Schindelin]

Hi,

On Fri, 24 Nov 2006, Han-Wen Nienhuys wrote:

> The recently posted patch documenting is an improvement, but why not
> add an option so you can do
> 
>   --format 'committer %c\nauthor %a\n'
>   
> this catches all combinations, and is easier for scripting.

Yes, it would be easier for scripting, and it would probably be relatively 
easy, what with the addition of interpolate.[ch] to git. However, it is 
work, and I am lazy.

What information would you like, anyway? IOW can you provide me with a 
list like this:

%c	committer
%a	author
%d	committer_date
...

Ciao,
Dscho

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> On Fri, 24 Nov 2006, Han-Wen Nienhuys wrote:
>
>> The recently posted patch documenting is an improvement, but why not
>> add an option so you can do
>> 
>>   --format 'committer %c\nauthor %a\n'
>>   
>> this catches all combinations, and is easier for scripting.
>
> Yes, it would be easier for scripting, and it would probably be relatively 
> easy, what with the addition of interpolate.[ch] to git. However, it is 
> work, and I am lazy.

Lazy is good when the details should not matter.  If some people
are scripting, they are fully capable of reading raw or fuller.

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Han-Wen Nienhuys wrote:
> 
> This is not about CVS or SVN, so don't put them up as a strawman.
> If you want to argue that my brain is warped, use other distributed VCs as an
> example.

Your example has nothing at all to do with "pull" vs "fetch", though.

Your example is about something totally _different_, namely that under 
git, "git init-db" is _only_ for creating a _new_ project.

> The following
> 
>   mkdir x y
>   cd x
>   hg init
>   echo hoi > bla
>   hg add
>   hg commit -m 'yes, I am also too stupid to refuse explicit empty commit messages'
>   cd ../y
>   hg init
>   hg pull ../x
> 
> pretty much works the same in Darcs, bzr and mercurial.
> 
> With GIT, this is what happens
> 
> [hanwen@haring y]$ git pull ../x

Bzzt. This is where you went wrong, and you blamed "pull".

The way you do this in git is to NOT do "git init". Instead, you replace 
all the

	mkdir y
	cd ../y
	hg init
	hg pull ../x

with a simple

	git clone x y

and YOU ARE DONE.

Now, we could certainly _make_ "git pull" work on an empty git project, 
but that has _nothing_ to do with what people have been talking about.

In fact, the fact that "git fetch" kind of works is not exactly accidental 
(because "git fetch" _is_ meant to add new local branches too), but all 
the problems you have with it are due to the SAME issue. You started 
without any branch at all, because you started with an empty git repo, and 
you're simply not _supposed_ to do that.

So current rule (and this is not new, it's always been true): the ONLY 
time you use "git init-db" is when you are going to start a totally new 
project. Never _ever_ otherwise. If you want to track another project, use 
"git clone".

> This might not be typical GIT use, but it does show the typical GIT user
> experience, at least mine.

It's not that it isn't typical, it's that you are using the wrong model. 
Maybe it's not well documented, I can easily give you that, but ALL your 
problems come from that fundamental starting point: you shouldn't have 
used "git init-db" in the first place.

Somebody want to document it?

Alternatively, we certainly _could_ make "git pull" just accept an empty 
git repo, and make it basically create the current branch.

(And we probably should improve the error messahe)

> I don't want ANYTHING to really change, I just want a sane interface to it.

The sane interface _exists_. It's called "git clone".

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Linus Torvalds escreveu:

> So current rule (and this is not new, it's always been true): the ONLY 
> time you use "git init-db" is when you are going to start a totally new 
> project. Never _ever_ otherwise. If you want to track another project, use 
> "git clone".

Actually, only a 2 weeks ago, you suggested that I share the website
and main source code for my project in a single repository for reasons
of organization.

In this setup I find it logical to do

  git init-db
  git pull ..url.. website/master

to wind up with just the 5mb website, instead of the complete 70mb
of packed source code with all of its branches and tags.

> It's not that it isn't typical, it's that you are using the wrong model. 
> Maybe it's not well documented, I can easily give you that, but ALL your 
> problems come from that fundamental starting point: you shouldn't have 
> used "git init-db" in the first place.
> 
> Somebody want to document it?
> 
> Alternatively, we certainly _could_ make "git pull" just accept an empty 
> git repo, and make it basically create the current branch.

Yes, I would like that.  


-- 

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Han-Wen Nienhuys wrote:
> 
> Actually, only a 2 weeks ago, you suggested that I share the website
> and main source code for my project in a single repository for reasons
> of organization.
> 
> In this setup I find it logical to do
> 
>   git init-db
>   git pull ..url.. website/master

I don't disagree per se. It should be easy to support, it's just that it's 
not traditionally been something we've ever done.

So the way you'd normally set up a single repo that contains multiple 
other existing repositories is to basically start with one ("git clone") 
and then add the other branches and "git fetch" them.

So again, instead of "git init-db" + "git pull", you'd just use "git 
clone" instead.

Note that there _is_ another difference between "git pull" and 
"fetch+merge". The difference being that "git pull" implicitly does the 
checkout for you (I say "implicitly", because that's the way the git 
merge conceptually works: we always merge in the working tree. That's not 
the only way it _could_ be done, though - for trivial merges, we could do 
them without any working tree at all, but we don't suppotr that).

And that "git pull" semantic actually means that if you want a _bare_ 
repository, I think "git --bare init-db" + "git --bare fetch" actually 
does exactly the right thing right now too. But "git pull" would not be 
the right thing to use.

Btw, another normal way to generate a central "multi-headed repo" for is 
to not use "pull" or "fetch" or "clone" at ALL, but I would likely do 
something like

	mkdir central-repo
	cd central-repo
	git --bare init-db

and that's it. You now have a central repository, and you _never_ touch it 
again in the central place except to repack it and do other "maintenance" 
(eg pruning, fsck, whatever).

Instead, from the _outside_, you'd probably just do

	git push central-repo mybranch:refs/heads/central-branch-name

(actually, you'd probably set up that branch-name translation of 
"mybranch:refs/heads/central-branch-name" in your remote description, but 
I'm writing it out in full as an example).

So there are many ways to do it. It just happens that "git init-db" 
followed by "git pull" is not one of them ;)

(And the real reason for that is simple: "git pull" simply wants to have 
something to _start_ with. It's not hugely fundamental, it's just how it 
was written).

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Linus Torvalds wrote:
> 
> (And the real reason for that is simple: "git pull" simply wants to have 
> something to _start_ with. It's not hugely fundamental, it's just how it 
> was written).

Here's a very lightly tested patch that allows you to use "git pull" to 
populate an empty repository.

I'm not at all sure this is necessarily the nicest way to do it, but it's 
fairly straightforward.

Junio, what do you think?

		Linus

---
diff --git a/git-pull.sh b/git-pull.sh
index ed04e7d..7e5cee2 100755
--- a/git-pull.sh
+++ b/git-pull.sh
@@ -44,10 +44,10 @@ do
 	shift
 done
 
-orig_head=$(git-rev-parse --verify HEAD) || die "Pulling into a black hole?"
+orig_head=$(git-rev-parse --verify HEAD 2> /dev/null)
 git-fetch --update-head-ok --reflog-action=pull "$@" || exit 1
 
-curr_head=$(git-rev-parse --verify HEAD)
+curr_head=$(git-rev-parse --verify HEAD 2> /dev/null)
 if test "$curr_head" != "$orig_head"
 then
 	# The fetch involved updating the current branch.
@@ -80,6 +80,11 @@ case "$merge_head" in
 	exit 0
 	;;
 ?*' '?*)
+	if test -z "$orig_head"
+	then
+		echo >&2 "Cannot merge multiple branches into empty head"
+		exit 1
+	fi
 	var=`git-repo-config --get pull.octopus`
 	if test -n "$var"
 	then
@@ -95,6 +100,12 @@ case "$merge_head" in
 	;;
 esac
 
+if test -z "$orig_head"
+then
+	git-update-ref -m "initial pull" HEAD $merge_head "" || exit 1
+	exit
+fi
+
 case "$strategy_args" in
 '')

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

> On Thu, 16 Nov 2006, Linus Torvalds wrote:
>> 
>> (And the real reason for that is simple: "git pull" simply wants to have 
>> something to _start_ with. It's not hugely fundamental, it's just how it 
>> was written).
>
> Here's a very lightly tested patch that allows you to use "git pull" to 
> populate an empty repository.
>
> I'm not at all sure this is necessarily the nicest way to do it, but it's 
> fairly straightforward.
>
> Junio, what do you think?

Yeah, I talked about making "merge" treat missing HEAD as a
special case of fast forward, but I like yours better.  It is a
lot cleaner and to the point.

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Linus Torvalds wrote:
> @@ -95,6 +100,12 @@ case "$merge_head" in
>  	;;
>  esac
>  
> +if test -z "$orig_head"
> +then
> +	git-update-ref -m "initial pull" HEAD $merge_head "" || exit 1
> +	exit
> +fi
> +

So this is the place that probably wants a "git-checkout" before the 
exit, otherwise you'd (illogically) have to do it by hand for that 
particular case.

Of course, we should _not_ do it if the "--bare" flag has been set, so you 
migth want to tweak the exact logic here.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

> On Thu, 16 Nov 2006, Linus Torvalds wrote:
>> @@ -95,6 +100,12 @@ case "$merge_head" in
>>  	;;
>>  esac
>>  
>> +if test -z "$orig_head"
>> +then
>> +	git-update-ref -m "initial pull" HEAD $merge_head "" || exit 1
>> +	exit
>> +fi
>> +
>
> So this is the place that probably wants a "git-checkout" before the 
> exit, otherwise you'd (illogically) have to do it by hand for that 
> particular case.
>
> Of course, we should _not_ do it if the "--bare" flag has been set, so you 
> migth want to tweak the exact logic here.

As you said, pull inherently involve a merge which implies the
existence of associated working tree, so I do not think there is
any room for --bare to get in the picture.  We already do the
checkout when we recover from a fetch that is used incorrectly
and updated the current branch head underneath us.

To give the list a summary of the discussion so far, here is a
consolidated patch.

-- >8 --
From: Linus Torvalds <torvalds@osdl.org>
Subject: git-pull: allow pulling into an empty repository

We used to complain that we cannot merge anything we fetched
with a local branch that does not exist yet.  Just treat the
case as a natural extension of fast forwarding and make the
local branch'es tip point at the same commit we just fetched.
After all an empty repository without an initial commit is an
ancestor of any commit.

Signed-off-by: Junio C Hamano <junkio@cox.net>

---
diff --git a/git-pull.sh b/git-pull.sh
index ed04e7d..e23beb6 100755
--- a/git-pull.sh
+++ b/git-pull.sh
@@ -44,10 +44,10 @@ do
 	shift
 done
 
-orig_head=$(git-rev-parse --verify HEAD) || die "Pulling into a black hole?"
+orig_head=$(git-rev-parse --verify HEAD 2>/dev/null)
 git-fetch --update-head-ok --reflog-action=pull "$@" || exit 1
 
-curr_head=$(git-rev-parse --verify HEAD)
+curr_head=$(git-rev-parse --verify HEAD 2>/dev/null)
 if test "$curr_head" != "$orig_head"
 then
 	# The fetch involved updating the current branch.
@@ -80,6 +80,11 @@ case "$merge_head" in
 	exit 0
 	;;
 ?*' '?*)
+	if test -z "$orig_head"
+	then
+		echo >&2 "Cannot merge multiple branches into empty head"
+		exit 1
+	fi
 	var=`git-repo-config --get pull.octopus`
 	if test -n "$var"
 	then
@@ -95,6 +100,13 @@ case "$merge_head" in
 	;;
 esac
 
+if test -z "$orig_head"
+then
+	git-update-ref -m "initial pull" HEAD $merge_head "" &&
+	git-read-tree --reset -u HEAD || exit 1
+	exit
+fi
+
 case "$strategy_args" in
 '')
 	strategy_args=$strategy_default_args

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Junio C Hamano wrote:
> 
> As you said, pull inherently involve a merge which implies the
> existence of associated working tree, so I do not think there is
> any room for --bare to get in the picture.

Fair enough. Feel free to add the signed-off-by from me too, 

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 910 bytes --]

On Thu, 16 Nov 2006 09:17:32 -0800 (PST), Linus Torvalds wrote:
> So the way you'd normally set up a single repo that contains multiple
> other existing repositories is to basically start with one ("git clone")
> and then add the other branches and "git fetch" them.

For that we'd also need a way for clone to be able to fetch just a
single branch, and not all of them as well.

There is some clone vs. fetch asymmetry here that has annoyed me for a
while, and that I don't think has been mentioned in this thread
yet. Namely:

clone: can only be executed once, fetches all branches, "remembers"
       URLs for later simplified use

fetch: can be executed many times, fetches only named branches,
       doesn't remember anything for later

I've often been in the situation where I cloned a long time ago, but
I'd like to be able to fetch everything that I would get if I were to
start a fresh clone.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Johannes Schindelin]

Hi,

On Wed, 15 Nov 2006, Linus Torvalds wrote:

> Peopel seem to believe that changign a few names or doing other totally 
> _minimal_ UI changes would somehow magically make things understandable. 

Never ever underestimate pet peeves. If we give many people an obvious 
reason (however trivial and bike-shed-coloured) to complain, they will 
complain.

If we pull (pun intended) that reason away under their collective 
backsides, they will have to find another reason to complain. But by the 
time they found something, they will already be happy git users!

But since you just provided a patch to make life easier on non-gitters, I 
guess you agree with that already.

And hopefully you also agree that enhancing the syntax of git-merge to 
grok "git-merge [-m message] <branch>" and "git-merge [-m message] 
<url-or-remote> <branch>" would be a lovely thing, luring even more 
people into using git.

Maybe they even start complaining about subversion and CVS calling a merge 
"update", who knows?

Ciao,
Dscho

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Fri, 17 Nov 2006, Johannes Schindelin wrote:
> 
> Never ever underestimate pet peeves. If we give many people an obvious 
> reason (however trivial and bike-shed-coloured) to complain, they will 
> complain.

I do actually think that this discussion has been informative, partly 
because I never even realized that some people would ever think to do 
"init-db" + "pull". 

Making things like that work is easy enough, it's just that I never saw 
any point until people complained. And when they complained, the initial 
complaint wasn't actually obvious. Only when Han-Wen actually gave 
something that didn't work, was it clear that the real issue wasn't so 
much _naming_, as just expectations about the _work_flow_.

> And hopefully you also agree that enhancing the syntax of git-merge to 
> grok "git-merge [-m message] <branch>" and "git-merge [-m message] 
> <url-or-remote> <branch>" would be a lovely thing, luring even more 
> people into using git.

I definitely think we can make "git merge" have a more pleasant syntax. 
I'm just still not sure that people should actually use it ;)

My real point was/is that usually it's really not the "naming details" 
that people _really_ have problems with. The real problems tend to be in 
learning a new workflow.

We can make some of those workflows easier, but I would heartily recommend 
that people not worry about naming of "pull" vs "fetch", because that's 
almost certainly not really the issue. Instead, if you have a problem, 
rather than concentrating on the names of the programs, say:

 - what do you want to get done.

   Most likely it's _trivial_ to do with git, it's just that somebody used 
   the wrong approach, and then it didn't work at all.

 - give actual examples of a workflow that didn't work or was complex.

   (again, the "init-db" + "pull" example). 

   And yes, in many cases, it might well be a case of "sure, we can make 
   that _other_ workflow work too". But somebody like me, who has used git 
   for a year and a half, and used BK before it, probably simply uses a 
   different workflow than somebody who comes from CVS. 

For example, I suspect that your gripe with "git fetch" was just from 
using it in a really awkward manner. Maybe we could make your workflow 
work with git too, but maybe it really already (and always) did, you just 
used a particular tool in a way that made the use be really really 
painful.

Sometimes it's just a question of "ok, use it like _this_, and now it's 
actually really simple". Other times it's "ok, I didn't even realize that 
you wanted to use it like _that_, and yeah, that's incredibly 
inconvenient, and we can change it".

I just got involved in this discussion because I thought people were 
talking about all the wrong things. Command naming really can't be _that_ 
big of a deal. I really don't believe that we should have some people use 
"gh" instead of "git" just because they think "pull" should mean not to 
merge or something.

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Linus Torvalds escreveu:
> My real point was/is that usually it's really not the "naming details" 
> that people _really_ have problems with. The real problems tend to be in 
> learning a new workflow.

I agree that discussions on naming may cloud the issue, but "learning
the workflow" implies that people should adapt to the limitations of
their tools.  That's only a viable stance when the tools are finished
and completely perfect.

Until that time, it would be good goal to remove all idiosyncrasies,
all gratuitious asymetries and needless limitations in the commands of
git, eg.

 - clone but not a put-clone,

 - pull = merge + fetch, but no command for merge + throw

 - clone for getting all branches of a repo, but no command for
   updating all branches of a repo.  

Of course, when all warts are fixed, backward compatibility will force
us to choose some new names. At that point, a discussion on naming is
in place.


-- 
 Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Han-Wen Nienhuys <hanwen@xs4all.nl> writes:

>  - clone but not a put-clone,

What's put-clone?  Care to explain?

>  - pull = merge + fetch, but no command for merge + throw

What's merge+throw?  Care to explain?

>  - clone for getting all branches of a repo, but no command for
>    updating all branches of a repo.  

This one I can understand, but how would you propose to "update
all branches", in other words what's your design for mapping
remote branch names to local branch namespaces?

It would be nice if the design does not straightjacket different
repository layouts different people seem to like, but I think it
would be Ok to limit ourselves only to support the straight
one-to-one mapping and support only separate-remote layout.

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Junio C Hamano escreveu:
> Han-Wen Nienhuys <hanwen@xs4all.nl> writes:
> 
>>  - clone but not a put-clone,
> 
> What's put-clone?  Care to explain?

put clone would be the putative inverse of clone, ie. make a clone of
a local repository on a remote server.

>>  - pull = merge + fetch, but no command for merge + throw
> 
> What's merge+throw?  Care to explain?

throw is the hypothetical opposite of fetch. I agree that this is
academical, because it's logical to only allow fast-forwards for
sending revisions.

>>  - clone for getting all branches of a repo, but no command for
>>    updating all branches of a repo.  
> 
> This one I can understand, but how would you propose to "update
> all branches", in other words what's your design for mapping
> remote branch names to local branch namespaces?
> 
> It would be nice if the design does not straightjacket different
> repository layouts different people seem to like, but I think it
> would be Ok to limit ourselves only to support the straight
> one-to-one mapping and support only separate-remote layout.

I think the whole clone design is a bit broken, in that the "master"
branch gets renamed or copied to "origin", but all of the other
branches remain unchanged in their names.

It's more logical for clone to either

 * leave all names unchanged

 * put all remote branches into a subdirectory.  This would also make
   it easier to track branches from multiple servers.

   At present,  I have in my build-daemon the following branches,

	cvs-head-repo.or.cz-lilypond.git
	hanwen-repo.or.cz-lilypond.git
	hwn-jcn-repo.or.cz-lilypond.git
	lilypond_1_0-repo.or.cz-lilypond.git
	lilypond_1_2-repo.or.cz-lilypond.git
	lilypond_1_4-repo.or.cz-lilypond.git
	lilypond_1_6-repo.or.cz-lilypond.git
	lilypond_1_8-repo.or.cz-lilypond.git
	lilypond_2_0-repo.or.cz-lilypond.git
	lilypond_2_2-repo.or.cz-lilypond.git
	lilypond_2_3_2b-repo.or.cz-lilypond.git
	lilypond_2_3_5b-repo.or.cz-lilypond.git
	lilypond_2_4-repo.or.cz-lilypond.git
	lilypond_2_6-repo.or.cz-lilypond.git
	lilypond_2_8-repo.or.cz-lilypond.git
	master-git.sv.gnu.org-lilypond.git
	master-hanwen
	master-repo.or.cz-lilypond.git
	origin-repo.or.cz-lilypond.git
	stable
	stable-2.10
	stable--2.10-git.sv.gnu.org-lilypond.git

  It would solve lots of problems for me if cloning and fetching would
  put branches into a subdirectory, ie.

    git clone git://repo.or.cz/lilypond.git

  leads to branches

    repo.or.cz/lilypond_2_8
    repo.or.cz/lilypond_2_6
    repo.or.cz/lilypond_2_4
    repo.or.cz/master
     (etc..)

	
-- 

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Fri, Nov 17, 2006 at 01:27:53AM CET, Han-Wen Nienhuys wrote:
> put clone would be the putative inverse of clone, ie. make a clone of
> a local repository on a remote server.

So effectively to tell git push not to unpack on the remote side, and to
push all branches and relevant tags.

..snip..
> It's more logical for clone to either
> 
>  * leave all names unchanged
> 
>  * put all remote branches into a subdirectory.  This would also make
>    it easier to track branches from multiple servers.
> 
>    At present,  I have in my build-daemon the following branches,
> 
> 	cvs-head-repo.or.cz-lilypond.git
> 	hanwen-repo.or.cz-lilypond.git
> 	hwn-jcn-repo.or.cz-lilypond.git
> 	lilypond_1_0-repo.or.cz-lilypond.git
> 	lilypond_1_2-repo.or.cz-lilypond.git
> 	lilypond_1_4-repo.or.cz-lilypond.git
> 	lilypond_1_6-repo.or.cz-lilypond.git
> 	lilypond_1_8-repo.or.cz-lilypond.git
> 	lilypond_2_0-repo.or.cz-lilypond.git
> 	lilypond_2_2-repo.or.cz-lilypond.git
> 	lilypond_2_3_2b-repo.or.cz-lilypond.git
> 	lilypond_2_3_5b-repo.or.cz-lilypond.git
> 	lilypond_2_4-repo.or.cz-lilypond.git
> 	lilypond_2_6-repo.or.cz-lilypond.git
> 	lilypond_2_8-repo.or.cz-lilypond.git
> 	master-git.sv.gnu.org-lilypond.git
> 	master-hanwen
> 	master-repo.or.cz-lilypond.git
> 	origin-repo.or.cz-lilypond.git
> 	stable
> 	stable-2.10
> 	stable--2.10-git.sv.gnu.org-lilypond.git
> 
>   It would solve lots of problems for me if cloning and fetching would
>   put branches into a subdirectory, ie.
> 
>     git clone git://repo.or.cz/lilypond.git
> 
>   leads to branches
> 
>     repo.or.cz/lilypond_2_8
>     repo.or.cz/lilypond_2_6
>     repo.or.cz/lilypond_2_4
>     repo.or.cz/master
>      (etc..)

That's basically exactly what git clone --use-separate-remote should do.
Now only if it would become the default... :-)

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 760 bytes --]

On Thu, 16 Nov 2006 16:13:44 -0800, Junio C Hamano wrote:
> >  - clone for getting all branches of a repo, but no command for
> >    updating all branches of a repo.

I want this one as well.

> This one I can understand, but how would you propose to "update
> all branches", in other words what's your design for mapping
> remote branch names to local branch namespaces?

As long as its consistent with "clone" I'll be happy, (I think as part
of a separate topic we need to fix the mappings in clone, see
--use-separate-remotes as default and related).

The current case is really annoying where I have to throw use clone
into a new repository just to get everything, rather than just being
able to fetch everything into the repository I already have.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 1788 bytes --]

On Thu, 16 Nov 2006 16:13:44 -0800, Junio C Hamano wrote:
> This one I can understand, but how would you propose to "update
> all branches", in other words what's your design for mapping
> remote branch names to local branch namespaces?

What I want here is a command "git update" that fetches and
fast-forwards the all branches which are designated as "tracking" a
branch in some known remote repository. And git-clone would setup all
branches appropriately so that they would be updated by git-update.

Additionally, it would be nice if git-update would also create new
tracking branches for all remotes repositories that had been
designated as being tracked, (and git-clone would do this as well).

There should also be a mechanism to easily create new tracking support
for specific branches or all branches of a repository, (could be "git
fetch URL branch" or "git fetch --all URL", for example).

With this kind of setup, I would use "git update" regularly, and only
ever merge locally. And by definition merging with any local tracking
branch would have just as much information available as "pull URL
branch" so the message would be the same.

I've been using git for 10-11 months, so I think I understand the
models fairly well, and I'd be really happy with a setup like that. I
also have talked with a fair number of (non-git-using) users who think
git is confusing, but I think would find the above scenario just fine.

In this scenario, git pull would still work just fine, but it would
also be much easy to teach a workflow that didn't use pull at all, so
if there's any git-pull confusion that's an actual problem, it could
be avoided.

Junio, what do you think of a setup something like that? I really
don't want to create a command other than "git" to implement it.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Fri, 17 Nov 2006, Han-Wen Nienhuys wrote:
> 
> Until that time, it would be good goal to remove all idiosyncrasies,
> all gratuitious asymetries and needless limitations in the commands of
> git, eg.

Well, a lot of the assymmetries aren't actually gratuitous at all.

>  - clone but not a put-clone,

As mentioned, in order to "put-clone", you generally have to "create" 
first, so the "put-clone" really makes no sense.

The _true_ reverse is really your

 - "git init-db" on both sides

 - "git pull" (your workflow ;) on receiving

 - "git push" on sending.

The fact that we can do "git clone" on the _receiving_ side is an 
assymmetry, but it's not gratutous: when receiving we don't need any extra 
permissions or setup to create a new archive. In contrast, when sending, 
you do have to have that "get permission to create new archive" phase.

>  - pull = merge + fetch, but no command for merge + throw

Again, this is not gratuitous, and the reason is very similar: when you 
pull, you're pulling into something that _you_ control and _you_ have 
access to, namely your working directory. In order to merge you have to 
have the ability to fix up conflicts (whether automatically or manually), 
and this is something that you _fundamentally_ can only do when you own 
the repo space.

Again, when you do "push", the reason you can't merge is not a "gratuitous 
assymmetry", but a _fundamental_ assymmetry: by definition, you're pushing 
to a _remote_ thing, and as such you can't merge, because you can't fix up 
any merge problems.

See?

In many ways, if you want _symmetry_, you need to make sure that the 
_cases_ are symmetrical. If you have ssh shell access, you can often do 
that, and the "reverse" of a "git pull" is actually just another "git 
pull" from the other side:

	ssh other-side "cd repo ; git pull back"

Now they really _are_ symmetrical: "git pull" is really in many ways ITS 
OWN reverse operation. 

But "push" and "pull" _fundamentally_ aren't symmetric operations, and you 
simply cannot possibly make them symmetric. Any system that tries would be 
absolutely horrible to use, exactly because it would be either:

 - making local/remote operations totally equivalent

   This sounds like a "good" thing, but from a real user perspective it's 
   actually horribly horribly bad. Knowing the difference between local 
   and remote is what allows a lot of performance optimizations, and a lot 
   of security. Your local repo is _yours_, and nobody can take that away 
   from you, and that's a really fundamental reason for why the symmetry 
   cannot exist, and why local/remote operations MUST NOT be something 
   that you can mix without thinking about them,

 - limit local operations in a way to make them effectively unusable and 
   unscriptable.

   You'd basically have to do everything even _locally_ through some 
   server interface, and you'd not be allowed to ever touch your local 
   checked-out repository directly. Again: local repositories really _are_ 
   special, because you can touch the checked out copy. If you try to 
   suppress that, you're screwed.

>  - clone for getting all branches of a repo, but no command for
>    updating all branches of a repo.  

As in sending? Sure there is: use "git push --all". It will push out every 
branch (and tag) you have. Add "--force" if you want to make sure that it 
also pushed out branches even if the result isn't a strict superset (of 
course, the receiving end may actually end up refusing to take it, there's 
a option for the receiver to say "I will refuse any update that isn't a 
strict superset of what I had").

If you mean as in "receiving new branches", then yeah, you do have to 
script it, with some fairly trivial "git ls-remote" to make sure you get 
the new remotes.

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Linus Torvalds escreveu:
> The fact that we can do "git clone" on the _receiving_ side is an 
> assymmetry, but it's not gratutous: when receiving we don't need any extra 
> permissions or setup to create a new archive. In contrast, when sending, 
> you do have to have that "get permission to create new archive" phase.
> 
>>  - pull = merge + fetch, but no command for merge + throw
> 
> Again, this is not gratuitous, and the reason is very similar: when you 
> pull, you're pulling into something that _you_ control and _you_ have 

>But "push" and "pull" _fundamentally_ aren't symmetric operations, and you 
>simply cannot possibly make them symmetric. 

Point taken;  thank you. 

In that case, we're full circle with the command naming issues. Push
and pull are fundamentally asymmetric operations, but then a
consistent UI would dictate that they wouldn't be named symmetrically,
as they are now.


-- 

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

I think there's a fundamental assumption built into the design of git
that most programmers accustomed to a corporate environment don't
understand.  Namely, that each programmer owns his or her entire
"repository", and can do whatever he or she darn well pleases with it
at any time.  Go ahead and create hundreds of transient branches as
part of a scripted "merge complexity metric" calculation.  Try three
different refactoring strategies on different branches, abandon two of
them, and prune them months later.  And generally use the power of the
SCM to juggle a lot of things at once, because there's no sysadmin
gatekeeper stopping you, and the thing is designed and coded scalably
so it doesn't grind to a halt as soon as everyone has dozens of
private branches.

Even if you do find a way to push git in a direction that it doesn't
scale, it's no one's problem but your own -- people who pull from you
are pulling the _content_ on the branches they care about, not the
structure of your repository.

On 11/16/06, Han-Wen Nienhuys <hanwen@xs4all.nl> wrote:
> I agree that discussions on naming may cloud the issue, but "learning
> the workflow" implies that people should adapt to the limitations of
> their tools.  That's only a viable stance when the tools are finished
> and completely perfect.
>
> Until that time, it would be good goal to remove all idiosyncrasies,
> all gratuitious asymetries and needless limitations in the commands of
> git, eg.

One person's gratuitous asymmetry is another's minimalism.  (If the
symmetric thing doesn't make any sense or can't be implemented
scalably, leave it out.)  It is more important that git continue to
work than that it appear symmetric without reference to its function.

>  - clone but not a put-clone,

What possible use would that be?  git is not rsync.

>  - pull = merge + fetch, but no command for merge + throw

pull = fetch + merge.  It is (almost?) always followed by a judgment
call based on the merge results.  merge + throw doesn't make any sense
in terms of the job at hand, which is facilitating human judgments
about whether to accept someone else's work into one's working tree.

>  - clone for getting all branches of a repo, but no command for
>    updating all branches of a repo.

clone is shorthand for the steps involved in setting up a new
repository with content similar to an existing one.  There isn't any
merge involved, and no scope for human judgment, so it's simplest to
clone the whole state of the remote repository (including tags and
branches) and let the user blow away any branches he doesn't need.
But once the clone is done, all of those branches are _truly_ _local_
-- they don't retain any reference to the remote branches, and you can
commit to all of them.  The only entry placed in .git/remotes is the
"origin" of the new clone, which is the "master" of the remote
repository.  That's for the user's convenience, and is about the only
thing in the new clone that _isn't_ a copy of something in the remote
tree.

So the "update all" process wouldn't look anything like a clone, it
would be a fetch and replay of each remote branch onto the
corresponding local branch.  You and Carl seem to want "git clone" not
only to copy the heads of the remote branches but to populate
.git/remotes with trackers for all of those branches, and then to
start each "git update" by polling all of the remote repositories to
see if branches have been created or deleted, then pull every branch
in sight.  What do you do when "upstream" creates a branch with the
same name as a local branch you have created?  How do you deal with
branch points that don't exist in your repository because you touched
one of the "tracker" branches between pulls?

In short, if you want a local, read-only tracker for a whole remote
repository instead of a branch that's actually published to you (and
maintained accordingly), you might consider s/git/rsync/.

Cheers,

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

On 11/16/06, Michael K. Edwards <medwards.linux@gmail.com> wrote
>   The only entry placed in .git/remotes is the
> "origin" of the new clone, which is the "master" of the remote
> repository.  That's for the user's convenience, and is about the only
> thing in the new clone that _isn't_ a copy of something in the remote
> tree.

Actually, this "origin" entry does contain "Pull:" lines for all of
the branches that were cloned, so that "git pull" fetches and merges
updates to all of these branches.  (If upstream is in the habit of
reverting things, you may need "git pull -f"; I just did that on the
git repo to handle a failure to fast-forward on the "pu" branch.)

Presumably "git branch -D" should inspect everything under
.git/remotes to see whether one or more Pull: lines need to be deleted
along with the branch.  Currently, it looks like "remotes" entries are
created only by "git clone" or by hand.  Junio, are there any plans to
manage the contents of "remotes" through the tool instead of by hand?

Cheers,

Re: Cleaning up git user-interface warts

[Junio C Hamano]

"Michael K. Edwards" <medwards.linux@gmail.com> writes:

> Presumably "git branch -D" should inspect everything under
> .git/remotes to see whether one or more Pull: lines need to be
> deleted along with the branch.

I am not sure what you mean.  .git/remotes files do not describe
any relationship between local branches (and that is where one
of the problem raised in recent thread -- pull does not notice
on which branch you are on and change its behaviour depending on
it), so I do not think there is anything gained for "git branch
-D" by going through them.

> Currently, it looks like "remotes" entries are
> created only by "git clone" or by hand.  Junio, are there any plans to
> manage the contents of "remotes" through the tool instead of by hand?

I muttered something in a near-by thread

	Message-ID: <7vr6w78b4x.fsf@assigned-by-dhcp.cox.net>

I am reasonably sure a separate tool (what I tentatively called
"maint-remote" in the message) is necessary, because, while it
would be relatively easy to make "git fetch" and friends to add
new mappings in the default way under a new option, people with
different workflows would want differnt "default mappings", and
adding new mappings for _all_ remote branches is useful only for
people who work in one particular way (namely, the CVS-style
"the central distribution point is where everybody meet" model).

The tool, under "interactive" mode, would probably take one
parameter, the short name of a remote ($name), and would give
you a form to update its URL:, shows ls-remote output against
that repository and would let you:

 - update the URL: which would probably cause the ls-remote to
   be re-run;

 - remove existing mappings;

 - add mappings for a remote branch for which you do not have a
   corresponding tracking branch, with a straightforward default
   mapping:

   	refs/heads/$branch:refs/remotes/$name/$branch

But I haven't thought things through yet.

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

On 11/16/06, Junio C Hamano <junkio@cox.net> wrote:
> "Michael K. Edwards" <medwards.linux@gmail.com> writes:
>
> > Presumably "git branch -D" should inspect everything under
> > .git/remotes to see whether one or more Pull: lines need to be
> > deleted along with the branch.
>
> I am not sure what you mean.  .git/remotes files do not describe
> any relationship between local branches (and that is where one
> of the problem raised in recent thread -- pull does not notice
> on which branch you are on and change its behaviour depending on
> it), so I do not think there is anything gained for "git branch
> -D" by going through them.

.git/remotes/foo does contain Pull: lines which indicate the local
branch onto which to _fetch_ remote changes.  It's the subsequent
_merge_ that doesn't notice which branch you have checked out.

Cheers,

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Michael K. Edwards wrote:

> Currently, it looks like "remotes" entries are
> created only by "git clone" or by hand.  Junio, are there any plans to
> manage the contents of "remotes" through the tool instead of by hand?

Don't forget quite new work with managing remotes (and per-branch
configuration) in the config instead of separate remotes/ (or even older
branches/) file
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Horst H. von Brand]

Han-Wen Nienhuys <hanwen@xs4all.nl> wrote:

[...]

> Until that time, it would be good goal to remove all idiosyncrasies,
> all gratuitious asymetries and needless limitations in the commands of
> git, eg.
> 
>  - clone but not a put-clone,

Lost me there.

>  - pull = merge + fetch, but no command for merge + throw

throw + merge (at the remote end, that is)?
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 07:03:18PM CET, Linus Torvalds wrote:
> If you think "pull" is confusing, I can guarantee you that _changing_ the 
> name is a hell of a lot more confusing. In fact, I think a lot of the 
> confusion comes from cogito, not from git - the fact that cogito used 
> different names and different syntax was a mistake, I think.

  I would agree that having "pull" mean something different in Cogito
than in Git was a bad idea (explanation: historically, for some period
of time Cogito had cg-pull which meant the same as cg-fetch or hg pull;
later it got renamed to cg-fetch). But I'm also happy that Cogito just
does not use the "pull" expression at all currently: "updating" seems to
be a clear and unloaded enough concept for new people. Pull is really
_very_ confusing, with it meaning something different (but not different
enough) in _all_ other systems but BK (which is basically irrelevant
nowadays).

  That said, I agree with your argument that changing it in Git now
might just result in more confusion. I'm just trying to explain Cogito's
choice here, and I believe it does no good nor harm to Core Git if it
just uses different name for the concept and avoids the original name at
all (except explaining in the docs that updating in Cogito is what
pulling is in Git).

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 03:10:16AM CET, Junio C Hamano wrote:
> You have to admit both pull and fetch have been contaminated
> with loaded meanings from different backgrounds. I was talking
> about killing the source of confusion in the longer term by
> removing fetch/pull/push, so we are still on the same page.

How was/is fetch contaminated?

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Petr Baudis wrote:

> On Wed, Nov 15, 2006 at 03:10:16AM CET, Junio C Hamano wrote:
> > You have to admit both pull and fetch have been contaminated
> > with loaded meanings from different backgrounds. I was talking
> > about killing the source of confusion in the longer term by
> > removing fetch/pull/push, so we are still on the same page.
> 
> How was/is fetch contaminated?

I think "fetch" is sane.  Its only problem is a missing symetrical 
counterpart verb, like "get" and "put".

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Nicolas Pitre wrote:
> 
> I think "fetch" is sane.  Its only problem is a missing symetrical 
> counterpart verb, like "get" and "put".

If you're a dog owner, the obvious counterpart for "fetch" is "throw" ;)

I think "get" and "put" would be bad, just because of confusion with 
"sccs get" (ie it has that "get this file" connotations).

Maybe "fetch" and "push" aren't totally diametrically opposite, but 
really, I don't think they are that hard to understand either. We do have 
the BK legacy of "pull" implying a merge, and that's fairly fundamental. 

It's also true that in a lot of usage schenarios, what people actually 
_use_ is "pull" and "push", and no, they aren't mirror images (since push 
will _not_ do the merge), but at the same time, from a _usage_ standpoint 
they really _are_ each others opposites. 

You "pull" to get other peoples data into your branch (and once you've 
internalized local branches and the merge thing, you know what this 
means), and you "push" to push your changes out. It really _is_ the usage 
schenario, and using "opposite" words really _does_ make sense.

It's true that _technically_ "fetch" is the opposite of "push", but at the 
same time, that really is about technology, not about usage models. You 
normally wouldn't do a "git fetch + git push" pair. You _can_ do so, but 
it's not the natural way to work - unless you're just doing a mirror 
service.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Linus Torvalds wrote:

> 
> 
> On Wed, 15 Nov 2006, Nicolas Pitre wrote:
> > 
> > I think "fetch" is sane.  Its only problem is a missing symetrical 
> > counterpart verb, like "get" and "put".
> 
> If you're a dog owner, the obvious counterpart for "fetch" is "throw" ;)

Yeah.  You could always throw a branch to your dog.

Or maybe we should introduce the concept of "bones" to GIT in place of 
branches?  ;-)

> I think "get" and "put" would be bad, just because of confusion with 
> "sccs get" (ie it has that "get this file" connotations).

Has SCCS really had a similar level of influence than BK or CVS in that 
matter?

> Maybe "fetch" and "push" aren't totally diametrically opposite, but 
> really, I don't think they are that hard to understand either. We do have 
> the BK legacy of "pull" implying a merge, and that's fairly fundamental. 
> 
> It's also true that in a lot of usage schenarios, what people actually 
> _use_ is "pull" and "push", and no, they aren't mirror images (since push 
> will _not_ do the merge), but at the same time, from a _usage_ standpoint 
> they really _are_ each others opposites. 

The problem is the "usage standpoint" distinction that has to be made.  
Exactly because in GIT it is a bit distorted from what most people 
expect from other standpoints.

> You "pull" to get other peoples data into your branch (and once you've 
> internalized local branches and the merge thing, you know what this 
> means), and you "push" to push your changes out. It really _is_ the usage 
> schenario, and using "opposite" words really _does_ make sense.

But that's exactly why newbies have problems.  Instead of simply 
understanding the bare operation (fetch data in a branch _then_ merge 
it) they sort of need to abstract the concept of branch away because a 
"pull" does it all automagically.  Which is fine as long as you're 
willing to ignore branch concepts altogether.  But once branches are 
back in the picture for more involved operations then the "pull" word 
simply feels odd.  Even more so with the local merge syntax.

When I say to someone "just merge branch weezee with your current 
branch" the most intuitive command would be:

	git merge weezee

But because "pull" mixes two concepts together this makes the thing more 
esoteric.  Unless, of course, you get used to the mental model you 
outlined above, but IMHO simply needing a mental model to explain the 
tool is a sign that something is mapped wrong.

Re: Cleaning up git user-interface warts

[Anand Kumria]

On Wed, 15 Nov 2006 15:26:44 -0500, Nicolas Pitre wrote:

> On Wed, 15 Nov 2006, Petr Baudis wrote:
> 
>> On Wed, Nov 15, 2006 at 03:10:16AM CET, Junio C Hamano wrote:
>> > You have to admit both pull and fetch have been contaminated
>> > with loaded meanings from different backgrounds. I was talking
>> > about killing the source of confusion in the longer term by
>> > removing fetch/pull/push, so we are still on the same page.
>> 
>> How was/is fetch contaminated?
> 
> I think "fetch" is sane.  Its only problem is a missing symetrical 
> counterpart verb, like "get" and "put".

"throw" ?

But I think "I'll just 'throw' this set of patches at you" is a lot
harshers sounding than "I'll just 'push' this set of patches at you".

Anand

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> On Tue, 14 Nov 2006 15:52:47 -0500 (EST), Nicolas Pitre wrote:
>> Even if I have a clear preference for GIT's _technology_, I still think
>> that the HG user interface is more convivial.  I even been thinking
>> about writing something like an hg-like frontend to GIT from time to
>> time just so that GIT could then be better compared to (and actually
>> just used like) HG.
>
> I've actually been tempted to do the same myself. I really think that
> the technology is a more important criterion than the UI so the
> imagined hg-on-git interface would be an attempt to get people to look
> past the interface differences and look at the technology when
> deciding.
>...
>> I still think that the GIT user interface sucks in many ways.  The
>...

I've actually been tempted to do that too, and my earlier "if I
were to redo git from scratch" message was the beginning of it
to summarize my preference about some of the issues raised in
this thread.

Commenting on the messages in this thread:

 - "resolve / resolved" are both confusing, when you are talking
   about "mark-resolved" operation.

 - "pull/push/fetch" have undesired confusion depending on where
   people learned the term.  I'd perhaps vote for replacing
   fetch with download and push with upload.

 - I think it would be sensible to make remote tracking branches
   less visible.  For example:

	git diff origin

   where origin is the shorthand for your upstream (e.g. you
   have .git/remotes/origin that records the URL and the branch
   you are tracking) should be easier to understand than

   	git diff remotes/origin/HEAD

   The latter is an implementation detail.  I could imagine we
   might even want to allow

	git diff origin#next

   to name the branch of the remote repository.  The notion of
   "where the tips of remote repository's branches are" is
   probably be updated by "git download" (in other words, the
   above "git diff" does not automatically initiate network
   transfer).

 - "git merge" to merge another branch into the current would
   make sense.  "git pull . remotes/origin/next" is showing too
   much implementation detail.  It should just be:

	git merge origin#next

And I agree with Pasky that fixing UI is hard unless you are
willing to get rid of historical warts.  Syntax of the command
line arguments the current set of Porcelain-ish takes are
sometimes just horrible.  It may not be a bad idea to start
building the fixed UI from scratch, using different prefix than
"git" (say "gu" that stands for "git UI" or "gh" that stands for
"git for humans").

Of course, it could even be "cg" ;-).

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

>  - I think it would be sensible to make remote tracking branches
>    less visible.  For example:
>...
>  - "git merge" to merge another branch into the current would
>    make sense.  "git pull . remotes/origin/next" is showing too
>    much implementation detail.  It should just be:
>
> 	git merge origin#next

This and other examples in "making remote tracking branches less
visible" are hard to read because I used the word "origin" in
two different sense.  So here is a needed clarification.

If you have remotes/upstream that says:

	URL: git://git.xz/repo.git
        Pull: refs/heads/master:remotes/origin/master
        Pull: refs/heads/next:remotes/origin/next

Then, currently the users need to say:

	git diff remotes/origin/master
        git merge remotes/origin/next

By "making tracking branches less visible", what I mean is to
let the users say this instead:

	git diff upstream
        git merge upstream#next

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Junio C Hamano wrote:

> Junio C Hamano <junkio@cox.net> writes:
> 
> >  - I think it would be sensible to make remote tracking branches
> >    less visible.  For example:
> >...
> >  - "git merge" to merge another branch into the current would
> >    make sense.  "git pull . remotes/origin/next" is showing too
> >    much implementation detail.  It should just be:
> >
> > 	git merge origin#next
> 
> This and other examples in "making remote tracking branches less
> visible" are hard to read because I used the word "origin" in
> two different sense.  So here is a needed clarification.
> 
> If you have remotes/upstream that says:
> 
> 	URL: git://git.xz/repo.git
>         Pull: refs/heads/master:remotes/origin/master
>         Pull: refs/heads/next:remotes/origin/next
> 
> Then, currently the users need to say:
> 
> 	git diff remotes/origin/master
>         git merge remotes/origin/next
> 
> By "making tracking branches less visible", what I mean is to
> let the users say this instead:
> 
> 	git diff upstream
>         git merge upstream#next

What is the point of hiding tracking branches?  Why just not making them 
easier to use instead?  There are currently so many ways to specify 
remote branches that even I get confused.

OK..... let's pretend this is my follow-up to your "If I were redoing 
git from scratch" query.  Actually I would not redo it from scratch 
since the vast majority of it is rather sane already.  But here's some 
changes that I would do:

1) make "git init" an alias for "git init-db".

What's the point of "-db"?  Sure we're initializing the GIT database.  
But who cares?  The user doesn't care if GIT uses a "database" or 
whatever.  And according to some people's definition of a "database" it 
could be argued that GIT doesn't use a database at all in the purist 
sense of it. What the user wants is to get started and "init" (without 
the "-db" is so much more to the point. Doesn't matter if incidentally 
it happens to be the same keyword HG uses for the same operation because 
we are not afflicted by the NIH disease, right? And it has 3 chars less 
to type which is for sure a premium improvement to the very first GIT 
user experience!

2) "pull" and "push" should be symmetrical operations

They are symmetrical in the dictionary and in people's mind.  OK but what 
if I merge content from another _local_ branch into the current one?  
Isn't that kind of a pull as well?  Answer: NO IT IS NOT!  Reason: 
because we already have "merge" for that very operation for damn sake!  
And because "merging" isn't a synonym for "pulling" at all, we cannot 
pretend it should sort of become more true if taken the other way 
around.

Actually, if we _merge_ stuff together, we certainly have to /pull/ some 
of it, meaning that "merge" might imply a "pull", even in real life 
situations outside of the GIT context (think merging Vodka and Kahlua in 
a glass where you might have to pull the Vodka bottle out of the freezer 
before you can merge it). And thankfully we got it right with git-merge 
which can take either a branch or an URL as argument which in the later 
case will perform a pull implicitly (OK currently a fetch but you know 
what I mean).

But trying to put in people's head that "pulling" implies a "merge"?  No 
that doesn't work really well.  OK if you pull too hard on the Vodka 
bottle that might imply a merge at some point but it would certainly be 
accidental.  And it is not without coincidence that some people had 
accidental GIT merges by using git-pull.

Conclusion:  git-pull must not perform any merge.  It is the symmetrical 
operation of a push meaning that it pulls content from a remote branch 
and does no more.  People understands that pretty well, .  This makes 
git-fetch redundant (or an alias to git-pull) in that case, and again we 
don't mind it becoming similar to in HG because we admit HG was right 
about it.

3) remote branch handling should become more straight forward.

OK! Now that we've solved the pull issue and that everybody agrees with 
me (how can't you all agree with me anyway) let's have a look at remote 
branches.  It should be simple:

a)	git-pull git://repo.com/time_machine.git

This pulls every branches from the time_machine.git repository and 
create identically named branches locally, except for the remote 
master becoming origin locally.  All those branches are marked read-only 
(i.e. cannot commit to them) and _each_ of those branches get an URL 
associated to them somehow (the association is an implementation 
detail).

If then you do:

b)	git-pull origin

Then it will pull the git://repo.com/time_machine.git:master branch into 
the local "origin" branch.  IOW, local tracking branches becomes 
synonyms for their remote URLs after they've been pulled once.  If the 
remote branch "next" became a local "next" with the first pull (because 
it didn't specify any branch meaning that they were all pulled), doing 
a:

c)	git-pull next

would actually be the same as:

d)	git-pull git://repo.com/time_machine.git:next

Now to have different remote and local names for those tracking 
branches:

e)	git-pull git://repo.com/time_machine.git:master upstream

would be a variation where a remote branch gets a different local name. 
This pulls the remote master branch but calls it "upstream" locally.  
If that "upstream" branch does exist locally already then fail with 
appropriate error message, unless the local branch happens to have the 
same URL attribute already.  You then have two local branches tracking 
the same remote branch which is weird but still fine if someone wants
to have different views (today's pull and yesterday's pull).  This is 
not necessarily something to encourage but only a fallout of the branch 
semantic.  And again a simple:

f)	git-pull upstream

would update the "upstream" branch from the remote master branch.

I think the concept of "branch group" should be preserved too.  So if 
you create a group called "warp", then add "origin", "next", and 
"upstream" to it, then:

g)	git-pull warp

would pull all the included branches.  One way to create a branch group 
with the initial pull is not to specify the remote branch but only the 
repository URL, like:

h)	git-pull git://repo.com/time_machine.git warp

Because no specific branch in the remote repository was specified just 
like in (a) then all branches are pulled, but because a local name was 
provided then this becomes a branch group.

Branch groups could be used to extend the branch namespace as well to 
avoid clashes with different remote repositories.  In this case the 
branch groups could be a way to arrange branches in a hierarchy so 
"warp" refer to all branches included in the warp group while 
"warp/upstream" refer to only one branch. In this case "upstream" and 
"warp/upstream" would be the same branch if "upstream" was effectively 
added to the "warp" group, but it doesn't need to be so.  And branches 
in a group don't have to come from the same remote repository either 
since the source of each branch (the URL) is a per branch attribute.

To make it "easy" on the user, I think that any branch (or tag) down the 
hierarchy should be used without the "path" leading to it if there is no 
conflict.  We already do that with heads and tags, So if for example the 
"warp" group contained a branch named "lightspeed" but no such branch 
(or tag) existed anywhere else then it could be referenced with simply 
"lightspeed" or "warp/lightspeed".

Then you don't need any strange scheme for diff and merge.  Just using 
"git-diff upstream" or "git-merge origin next" suffice.  Oh and I don't 
think it would be a good idea to have a completely separate namespace 
for local vs remote aka tracking branches.  Maybe in .git/refs/ they 
should be separate to distinguish which ones are read-only remote 
tracking ones and which ones are local, but that must not be forced on 
the UI.

Thinking about it some more, maybe (a) should create a default branch 
group if the remote repository has more than one branches, say "origin".  
This way, git-pull without any argument would be the same as 
"git-pull origin" by default.  If "origin" is a single branch then 
(git-pull" would pull only one branch, but if "origin" is a branch group 
then all included branches would be pulled.

This becomes formalized as:

	git_pull [<URL>] [<local_name>]

If <URL> includes a branch name then <local_name> is a single branch 
name.  If <URL> doesn't include any branch name then <local_name> 
becomes a local branch group name containing all branches in the remote 
repository. If <URL> is specified but not <local_name> then <local_name> 
is set to "origin" by default, unless it already exists in which case it 
is an error and the pull fails.  If <URL> is not specified then the URL 
attribute to the specified branch(es) is used.  If nothing is specified 
then "origin" is used for <local_name> by default and URL attribute of 
the origin branch or the origin branch group is/are used.

*****

OK I think this is enough for now. I know that parts of what I've said 
can already be found in GIT, but I wanted the explanation to be 
complete and therefore tentatively coherent.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> What is the point of hiding tracking branches?  Why just not making them 
> easier to use instead?  There are currently so many ways to specify 
> remote branches that even I get confused.

Ok, I think in essence we are saying the same thing except I
went overboard by suggsting to extend sha1_name to also look at
.git/remotes/$name which is not necessary, because we already
have the .git/refs/remotes/%s/HEAD magic there.  Consider the
suggestion of "upstream#next" syntax retracted, please.

> 1) make "git init" an alias for "git init-db".

Or even better, have "gh init".

> 2) "pull" and "push" should be symmetrical operations

I think that makes a lot of sense to have "gh pull" and "gh
push" as symmetric operations, and make "gh merge" do the
fast-forward and 3-way merge magic done in the current "git
pull".  These three words would have a lot saner meaning.

> 3) remote branch handling should become more straight forward.
>
> OK! Now that we've solved the pull issue and that everybody agrees with 
> me (how can't you all agree with me anyway) let's have a look at remote 
> branches.

I would probably prefer making the default namespace under
.git/refs/remotes/remote-name for the tracking branches this
proposal creates, but other than that I agree with the general
direction this proposal is taking us, including branch groups.
We have .git/refs/remotes/%s/HEAD magic so I do not think we
even need to treat one branch repository any specially as you
suggsted.

The reason I am suggsting "gh" instead of "git" is primarily to
deal with stale documentation people would find googling.  I can
easily see people get confused by reading "pull = fetch + merge"
from either mailing list archive or Git cheat sheet various
projects seem to have developed.

It does not mean we need to redo _all_ UI.  I think most of the
archaeology commands have sane UI so during the transition
period (git 1.99) we can have "git log" and "gh log" which are
one and the same program, and perhaps git 2.0 can be shipped
with clear distinction between plumbing (i.e. git-update-index
and friends) and porcelain (e.g. "gh pull" that only fetches but
with the user friendliness you outlined here), with backward
compatibility wart to help old timers (e.g. "git pull" that
still does "git fetch" followed by "git merge").

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> Or even better, have "gh init".

Why gh?  Is Git just Mercurial backwards?  :)

I'm all in favor of this discussion, and in particular of just
breaking the entire UI in 2.0 by using a new frontend command.
I'm just not sure that "Mercurial backwards" describes Git well.

-- 

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Shawn Pearce <spearce@spearce.org> writes:

> Junio C Hamano <junkio@cox.net> wrote:
>> Or even better, have "gh init".
>
> Why gh?  Is Git just Mercurial backwards?  :)
>
> I'm all in favor of this discussion, and in particular of just
> breaking the entire UI in 2.0 by using a new frontend command.
> I'm just not sure that "Mercurial backwards" describes Git well.

I do not have any obsession to any name as long as it is
different from "git" to avoid confusion coming from older
documents that would be found by googling.  gh was just
shorthand for "git for humans" (and easy to type with index
fingers).  I think I listed a few other possibilities in my
previous message.

Re: Cleaning up git user-interface warts

[Johannes Schindelin]

Hi,

On Tue, 14 Nov 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > 1) make "git init" an alias for "git init-db".
> 
> Or even better, have "gh init".

Please no. It only makes things even more confusing. "git init" is perfect 
as it is. We can always have internal aliases from "init-db" to "init" to 
account for older usages.

> > 2) "pull" and "push" should be symmetrical operations
> 
> I think that makes a lot of sense to have "gh pull" and "gh
> push" as symmetric operations, and make "gh merge" do the
> fast-forward and 3-way merge magic done in the current "git
> pull".  These three words would have a lot saner meaning.

I am really opposed to do "gh pull". Not only because of "gh" being 
completely confusing (we already _have_ "git", and for porcelains 
different TLAs), but "pull" _really_ is confusing by now. And Mercurial 
did not help one wit by insisting on their own interpretation.

Why not do something like "get/put" instead? It is

- easier to remember
- not bogus (AFAICT the meaning is not used in diametrical senses)
- shorter to type than download/upload

As for "git merge": Just by the number of arguments you can discern 
between the original usage and the new usage, so I am all in favour of 
replacing "git pull <blabla>" by "git merge <blabla>". Where "<blabla>" 
can be a branch or a remote or a URL (with cogito style #branchname).

Ciao,
Dscho

Re: Cleaning up git user-interface warts

[Sean]

On Wed, 15 Nov 2006 15:01:47 +0100 (CET)
Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

> I am really opposed to do "gh pull". Not only because of "gh" being 
> completely confusing (we already _have_ "git", and for porcelains 
> different TLAs), but "pull" _really_ is confusing by now. And Mercurial 
> did not help one wit by insisting on their own interpretation.

This makes a lot of sense.  The "git" command isn't damaged so bad
that it can't be saved in a backward compatible way, at least for
a transition period.  Adding a new command name seems like a step
backward.
 
> Why not do something like "get/put" instead? It is
> 
> - easier to remember
> - not bogus (AFAICT the meaning is not used in diametrical senses)
> - shorter to type than download/upload
> 
> As for "git merge": Just by the number of arguments you can discern 
> between the original usage and the new usage, so I am all in favour of 
> replacing "git pull <blabla>" by "git merge <blabla>". Where "<blabla>" 
> can be a branch or a remote or a URL (with cogito style #branchname).

Both these ideas sound like a step in the right direction too.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Johannes Schindelin wrote:

> On Tue, 14 Nov 2006, Junio C Hamano wrote:
> 
> > Nicolas Pitre <nico@cam.org> writes:
> > 
> > > 2) "pull" and "push" should be symmetrical operations
> > 
> > I think that makes a lot of sense to have "gh pull" and "gh
> > push" as symmetric operations, and make "gh merge" do the
> > fast-forward and 3-way merge magic done in the current "git
> > pull".  These three words would have a lot saner meaning.
> 
> I am really opposed to do "gh pull". Not only because of "gh" being 
> completely confusing (we already _have_ "git", and for porcelains 
> different TLAs), but "pull" _really_ is confusing by now. And Mercurial 
> did not help one wit by insisting on their own interpretation.

I completely agree that creating yet another command prefix for 
basically the same tools would be a disaster.  We have "git" already so 
let's stick to it and make its usage just more sane.

> Why not do something like "get/put" instead? It is
> 
> - easier to remember
> - not bogus (AFAICT the meaning is not used in diametrical senses)
> - shorter to type than download/upload

Well, of all compromizes this is probably the best one so far.  I would 
have prefered to bite the bullet and fix "pull" instead of adding yet 
more commands.  But if the consensus is that there is no way on earth 
that "pull" can be salvaged then get/put is probably more enjoyable than 
download/upload.  This way pull/fetch/push could still be available 
(albeit burried somewhere out of sight).

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

>> Why not do something like "get/put" instead? It is
>> 
>> - easier to remember
>> - not bogus (AFAICT the meaning is not used in diametrical senses)
>> - shorter to type than download/upload
>
> Well, of all compromizes this is probably the best one so far.  I would 
> have prefered to bite the bullet and fix "pull" instead of adding yet 
> more commands.  But if the consensus is that there is no way on earth 
> that "pull" can be salvaged then get/put is probably more enjoyable than 
> download/upload.  This way pull/fetch/push could still be available 
> (albeit burried somewhere out of sight).

I still think in the long run you would be better off giving
separate names to Porcelains because I am sure you are going to
find the next command to "fix", you cannot suddenly change the
semantics of the command, and you soon run out of alternative
ways to name the action and you in addition have to explain the
differences between fetch and get to new users.  At least, with
"ig pull", you can dismiss all the broken git-x Porcelain-ish by
saying "Oh, git-x user-level commands had inconsistent semantics
and broken UI so do not use them anymore -- they are still there
only to help old timers transition.  The user level commands are
now called ig-x and ig stands for improved git".

But that's a very minor detail and can be fixed when we hit the
wall, so let's wait and see what happens.  Please consider my
gh/gu/cg/whatever dropped.

I think get/put is much better than suddenly changing what pull
means and is shorter to type than x-load; I am Ok with them.
Although I think these words are tainted by SCCS, I do not think
anybody cares.

Re: Cleaning up git user-interface warts

[Andy Parkins]

On Wednesday 2006, November 15 18:16, Junio C Hamano wrote:

> I still think in the long run you would be better off giving
> separate names to Porcelains because I am sure you are going to

The problem I think with that is that the line between plumbing and porcelain 
is not clear.  If you have two names then for the ambiguous ones you are just 
making it more confusing because there is yet another variable to try before 
you get the function you want.



Andy

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

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Andy Parkins <andyparkins@gmail.com> writes:

> On Wednesday 2006, November 15 18:16, Junio C Hamano wrote:
>
>> I still think in the long run you would be better off giving
>> separate names to Porcelains because I am sure you are going to
>
> The problem I think with that is that the line between plumbing and porcelain 
> is not clear.

This is moot because we (at least tentatively) agreed not to do
"gh" or "ig" or whatever, but I do not understand why you feel
so.

If we had a separate Porcelain namespace (say "ng" for "new
git") you would know "ng-commit" is not a Plumbing and when you
are writing a Porcelain script you would stay away from using it
in your script.

In the longer term, when the new Porcelain UI Nico and friends
are designing matures, and if it makes everybody (including
existing users who learned git-* Porcelain-ish during 18-months
process) happy, we could gradually deprecate and eventually
remove the git-* Porcelain-ish over time, at that point we would
have a very clear line between plumbing and porcelain.

But that would not be a flag-day change.  During the transition
period you cannot mechanically tell if git-foo is a plumbing or
a porcelain just like you cannot do so now.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Junio C Hamano wrote:

> If we had a separate Porcelain namespace (say "ng" for "new
> git") you would know "ng-commit" is not a Plumbing and when you
> are writing a Porcelain script you would stay away from using it
> in your script.

There is merit in trying to segregate porcelain vs plumbing... at least 
in theory.  In practice though I don't think this is something we should 
absolutely strive for.

Why? Because something is always going to fail the categorization.  
Sure there are commands that are pure plumbing like git-commit-tree, 
etc.  Some are pure porcelain like git-commit or git-log.  Yet we use 
git-log's output for git-shortlog.  Does it mean that git-log is 
plumbing? Also I have a script here that uses git-commit directly 
because it is so much convenient rather than futzing with the really 
bare plumbing.  I don't think git-commit should be prevented from being 
used within another script even if it is classified as porcelain.

So we have that notion of plumbing vs porcelain but in practice there is 
a whole spectrum between those two poles and I think it is a good thing.

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 1996 bytes --]

On Wed, 15 Nov 2006 11:41:20 -0800, Junio C Hamano wrote:
> Andy Parkins <andyparkins@gmail.com> writes:
> > On Wednesday 2006, November 15 18:16, Junio C Hamano wrote:
> >
> >> I still think in the long run you would be better off giving
> >> separate names to Porcelains because I am sure you are going to
> >
> > The problem I think with that is that the line between plumbing and porcelain
> > is not clear.
>
> This is moot because we (at least tentatively) agreed not to do
> "gh" or "ig" or whatever, but I do not understand why you feel
> so.

I'm not the original poster, but I feel the same way about the line
being unclear.

Here's a real-world example from last week.

For cairo I wrote a little script that two revspecs, (or one in
which case its first parent is used), and it goes off and checks out
both versions, builds each, runs a performance test on each, and then
generates a report showing the performance impact.

So now I can do things like:

	# What's the performance impact of my latest change:
	cairo-perf-diff HEAD

	# Have my last few changes helped as much as I'd hoped:
	cairo-perf-diff HEAD~3 HEAD

	# How has performance changed since our last stable release:
	cairo-perf-diff 1.2.6 HEAD

Anyway, when I announced this I also mentioned how easily someone
might generate an entire series of reports for a series of
commits. The command I gave as an example is:

	for rev in $(git rev-list 1.2.6..HEAD); do
	    cairo-perf-diff $rev
	done

I think that's a perfectly legitimate one-liner for users to use, and
it really shows off the easy-scriptability of git. But certainly, no
"new porcelain" author is going to consider rev-list to be porcelain
rather than plumbing, right? So as soon as I start teaching people to
do useful stuff like this, they might have to reach down into the
"scary" git interface.

I think we're much better off just having one "git" namespace for the
standard command-line interface, and then making it as easy to use as
possible.

-Carl


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> I'm not the original poster, but I feel the same way about the line
> being unclear.
>
> Here's a real-world example from last week.
>...
> Anyway, when I announced this I also mentioned how easily someone
> might generate an entire series of reports for a series of
> commits. The command I gave as an example is:
>
> 	for rev in $(git rev-list 1.2.6..HEAD); do
> 	    cairo-perf-diff $rev
> 	done
>
> I think that's a perfectly legitimate one-liner for users to use, and
> it really shows off the easy-scriptability of git. But certainly, no
> "new porcelain" author is going to consider rev-list to be porcelain
> rather than plumbing, right? So as soon as I start teaching people to
> do useful stuff like this, they might have to reach down into the
> "scary" git interface.

That is a very fine example, but I do not see why it is a
problem.  I do not think the goal of Porcelain is to make it
totally unnecessary for users to know about the plumbing.

The one-liner is essentially a new Porcelain command that is
useful in the cairo developers' workflow, and implementing it
with a plumbing command makes perfect sense.  The whole point of
git plumbing is to be friendly for scripted use.  If the user
who learns that one-liner from you gets curious why and how that
one-liner works, that would be a good gentle introduction to the
plumbing, but otherwise the user is not forced to know about it.

Also I do not see a problem if some plumbing commands happen to
be also useful by themselves ("[alias] less = -p cat-file -p"
comes to mind for example).

Some plumbing commands may be too deep magic and users do not
have to directly deal with them every day.  Some other plumbing
commands are so low-level and needs combination with others to
be any useful, and it is cumbersome to type the combination
every day.  For the latter kind, we have Porcelain commands that
implement the frequently used combination and the end users do
not have to know about them.

So it is true that by having a rich and usable set of Porcelain,
there is less need for the users to know about all the plumbing
details, but I consider that is a happy consequence.  It does
not have to be the goal of having a good Porcelain to hide the
whole plumbing.

Re: Cleaning up git user-interface warts

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 678 bytes --]

On Wed, 15 Nov 2006 13:13:11 -0800, Junio C Hamano wrote:
> That is a very fine example, but I do not see why it is a
> problem.  I do not think the goal of Porcelain is to make it
> totally unnecessary for users to know about the plumbing.

If not, then the promise of the porcelain fails. If cogito offers
"Here are 40 commands so you don't have to learn git's 140" and then
next says "Oh, and you'll still want to learn all those git commands
too", then its existence only makes the "too much stuff to learn"
problem worse, not better.

But I think you agree with me (for now) that fixing the git UI should
not involve creating a new primary command to replace "git".

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 11:36:21PM CET, Carl Worth wrote:
> On Wed, 15 Nov 2006 13:13:11 -0800, Junio C Hamano wrote:
> > That is a very fine example, but I do not see why it is a
> > problem.  I do not think the goal of Porcelain is to make it
> > totally unnecessary for users to know about the plumbing.
> 
> If not, then the promise of the porcelain fails. If cogito offers
> "Here are 40 commands so you don't have to learn git's 140" and then
> next says "Oh, and you'll still want to learn all those git commands
> too", then its existence only makes the "too much stuff to learn"
> problem worse, not better.

I didn't get this argument before either - why do you need to learn "all
those git commands" too? You'll never have to learn "git add" or even
"git commit". If you want to pick specific git commands later (like "git
bisect", which even seeks in a Cogito-compatible way), that's fine, go
ahead! But you by no means have to learn _other_ commands than those you
need. If you want to bisect, you have to learn no other Git commands
than "git bisect".

Another point is, if using _just_ _git_ requires you to learn "all those
git commands too" from git-commit-tree up (yes it does! if you want your
authorship information to be correct), something is wrong.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Robin Rosenberg]

torsdag 16 november 2006 04:21 skrev Petr Baudis:
> Another point is, if using _just_ _git_ requires you to learn "all those
> git commands too" from git-commit-tree up (yes it does! if you want your
> authorship information to be correct), something is wrong.

When/why do I need git-commit-tree? Isn't git-commit enough?

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Thu, Nov 16, 2006 at 11:09:13AM CET, Robin Rosenberg wrote:
> torsdag 16 november 2006 04:21 skrev Petr Baudis:
> > Another point is, if using _just_ _git_ requires you to learn "all those
> > git commands too" from git-commit-tree up (yes it does! if you want your
> > authorship information to be correct), something is wrong.
> 
> When/why do I need git-commit-tree? Isn't git-commit enough?

As I said, when you need to find out how to setup your authorship
information. It's documented as deep as on the git-commit-tree level.
BTW, the documentation is another important part of the
plumbing/porcelain separation, it's not only about the list of commands
but also that porcelain documentation should be reasonably
self-contained and not require users to peek at plumbing docs in order
to find out many stuff. It's also a consideration I take when
maintaining Cogito documentation.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Junio C Hamano escreveu:
> I still think in the long run you would be better off giving
> separate names to Porcelains because I am sure you are going to
> find the next command to "fix", you cannot suddenly change the

 > "ig pull", you can dismiss all the broken git-x Porcelain-ish by
 > saying "Oh, git-x user-level commands had inconsistent semantics
 > and broken UI so do not use them anymore -- they are still there
 > only to help old timers transition.  The user level commands are
 > now called ig-x and ig stands for improved git".


I think it would be good if there were different commands for 
porcelains. Not because fixing the current commands is too much work, 
but rather because it would clarify the structure of git.  GIT is a 
3-layer approach:

  - index+workdir+refs over
  - a DAG of commits over
  - a file based SHA1 database

at first sight it is difficult to tell for each command on which layer 
it operates. It would help understanding GIT a lot if each layer got 
it's own command, eg.

   git - sha1 content db
   gic - sequences of commits
   giu - UI

(Of course, these names are completely silly, but you get the idea)


> I think get/put is much better than suddenly changing what pull
> means and is shorter to type than x-load; I am Ok with them.
> Although I think these words are tainted by SCCS, I do not think
> anybody cares.

they're also tainted  by darcs, but that's a minor problem, I suppose.


-- 

Re: Cleaning up git user-interface warts

[Andy Parkins]

On Wednesday 2006 November 15 04:32, Nicolas Pitre wrote:

> OK..... let's pretend this is my follow-up to your "If I were redoing

Personally, I agree with almost everything in this email.  Except the 
implementation of point 3.

> 3) remote branch handling should become more straight forward.

I was completely confused by this origin/master/clone stuff when I started 
with git.  In hindsight, now I understand git a bit more, this is what I 
would have liked:

 * Don't use the name "origin" twice.  In fact, don't use it at all.  In a 
distributed system there is no such thing as a true origin.

 * .git/remotes/origin should be ".git/remotes/default".   "origin" is only 
special because it is the default to push and pull - it's very nice to have a 
default, but it should therefore be /called/ "default".

 * Whatever git-clone calls the remote, it should be matched by a directory 
in .git/refs/remotes.  So .git/remotes/$name contains "Pull"s to get all the 
remote branches to .git/refs/remotes/$name/*.   This implies that 
git /always/ does --use-separate-remote in clone.  If a branch is practically 
read-only it should be technically read-only too.

 * If clone really wants to have a non-read-only master, then that should 
be .git/refs/heads/master and will initialise 
to .git/refs/remotes/$name/master after cloning.  Personally I think this is 
dangerous because it assumes there is a "master" upstream - which git doesn't 
mandate at all.  Maybe it would be better to take the upstream HEAD and 
create a local branch for /that/ branch rather than require that it is 
called "master".

 * Ensuring we have /all/ upstream branches at a later date is hard, and not 
automatic.  Here is the .git/remotes/default file that should be possible:
    URL: git://host/project.git
    Pull: refs/heads/*:refs/remotes/default/*
   Now, every git-pull would check for new upstream branch refs and sync them 
into the local remotes list.  These are read-only so it'd be perfectly safe 
to delete any locally that no longer exist upstream.

 * git-clone should really just be a small wrapper around
    - git-init-db
    - create .git/remotes/default
    - maybe create specific .git/config
    - git-fetch default
   If git-clone does anything that can't be done with settings in the config 
and the remotes/default file then it's wrong.  The reason I say this is that 
as soon as git-clone has special capabilities (like --shared, --local 
and --reference) then you are prevented from doing magic with existing 
repositories.  For example; how do you create a repository that contains 
branches from two other local repositories that have the objects hard linked?

While I'm writing wishes, I'd like to jump on Junio's integration with other 
fetch-backends wish.  I use git-svn, and it would be fantastic if I could 
replace:

git-svn init --id upstream/trunk svn://host/path/trunk
git-svn fetch --id upstream/trunk
git-svn init --id upstream/stable svn://host/path/branches/stable
git-svn fetch --id upstream/stable

With a .git/remotes/svn
 SVN-URL: svn://host/path
 Pull: trunk:refs/remotes/upstream/trunk
 Pull: branches/stable:refs/remotes/upstream/stable
and
 git fetch svn

Obviously, the syntax is just made up; but you get the idea.  Even better, 
would be if it could cope with my "*" syntax suggested above:
 SVN-URL: svn://host/path
 Pull: trunk:refs/remotes/upstream/trunk
 Pull: branches/*:refs/remotes/upstream/*


There have been lots of "wishlist" posts lately; would it be useful if I tried 
to collect all these suggestions from various people into one place to try 
and get a picture of any consensus?



Andy
-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Andy Parkins wrote:

>  * Don't use the name "origin" twice.  In fact, don't use it at all.  In a 
> distributed system there is no such thing as a true origin.

The remote 'origin' is true origin of the repository: it is repository
we cloned this repository from.

I agree that having branch 'origin', at least in most common multi-branch
(multi-head) repository, is just confusing.

>  * Ensuring we have /all/ upstream branches at a later date is hard, and not 
> automatic.  Here is the .git/remotes/default file that should be possible:
>     URL: git://host/project.git
>     Pull: refs/heads/*:refs/remotes/default/*
>    Now, every git-pull would check for new upstream branch refs and sync them 
> into the local remotes list.  These are read-only so it'd be perfectly safe 
> to delete any locally that no longer exist upstream.

Very nice idea.
 
>  * git-clone should really just be a small wrapper around
>     - git-init-db
>     - create .git/remotes/default
>     - maybe create specific .git/config

I'm not sure about "create .git/remotes/default" part. Isn't git moving from
remotes file to having information about remotes (and branches) in config?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Andy Parkins]

On Wednesday 2006 November 15 09:59, Jakub Narebski wrote:

> >  * Don't use the name "origin" twice.  In fact, don't use it at all.  In
> > a distributed system there is no such thing as a true origin.
>
> The remote 'origin' is true origin of the repository: it is repository
> we cloned this repository from.

But that is not necessarily /the/ original, and "origin" is the absolute 
reference in maths.  It doesn't bother me that much I suppose, it's just that 
as far as unambiguous names go, I'm not wild about it - it's got too 
many "central repository" connotations, which is of course anathema to git.


Andy
-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: Cleaning up git user-interface warts

[Karl Hasselström]

On 2006-11-15 11:33:55 +0100, Andy Parkins wrote:

> But that is not necessarily /the/ original, and "origin" is the
> absolute reference in maths. It doesn't bother me that much I
> suppose, it's just that as far as unambiguous names go, I'm not wild
> about it - it's got too many "central repository" connotations,
> which is of course anathema to git.

To me, "origin" just means "where <whatever we're talking about>
originated". If you think of it that way, it's perfectly obvious that
each repository can have its own origin.

-- 
Karl Hasselström, kha@treskal.com

Re: Cleaning up git user-interface warts

[Andy Parkins]

On Wednesday 2006 November 15 10:48, Karl Hasselström wrote:

> To me, "origin" just means "where <whatever we're talking about>
> originated". If you think of it that way, it's perfectly obvious that
> each repository can have its own origin.

Of course.  I wasn't saying that I didn't understand why origin was chosen.  
It's not a completely crazy name - it does have /a/ meaning.  However, it's 
not an unambiguous meaning.  What if the repository I clone was itself a 
clone?  What if the repository it cloned was pulling from three other 
repositories?  What if those three repositories pull/push from/to each other?

  * -- * -- *
   \   |   / \
    \  |  /  /
     \ | /  / 
       *   /
       |  / 
       | /
       * <--- "origin"
       |
       * <--- cloned repository

The name "origin" is too close to having an "ultimate source" feel to it IMO.  
In a distributed system, it's not the right idea to be pushing.  After the 
clone is complete, the "origin" is no more special than any other repository, 
and if you felt like it you could change the URL for "origin" and it would 
make very little difference to you.

In short: I don't think "origin" is wrong, I just think it's not right.


Andy
-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Andy Parkins wrote:

> On Wednesday 2006 November 15 04:32, Nicolas Pitre wrote:
> 
> > OK..... let's pretend this is my follow-up to your "If I were redoing
> 
> Personally, I agree with almost everything in this email.  Except the 
> implementation of point 3.
> 
> > 3) remote branch handling should become more straight forward.
> 
> I was completely confused by this origin/master/clone stuff when I started 
> with git.  In hindsight, now I understand git a bit more, this is what I 
> would have liked:
> 
>  * Don't use the name "origin" twice.  In fact, don't use it at all.  In a 
> distributed system there is no such thing as a true origin.

I agree, sort of.  Not because"origin" is ambigous as a name.  But 
rather because there is a magic translation from "master" to "origin", 
and I think this is wrong to do that.

As mentioned elsewhere (and let's start using "get" instead of "pull" as 
suggested by Johannes), a "get" should probably always create a branch 
group even if it contains only one branch.  This way the remote branch 
called "master" will still be called "master" locally, under the branch 
group used to represent the remote repository.  And if a local name is 
not provided then let's just call it "default".  This way, amongst the 
remote references, there would be a "default/master" that would be used 
when nothing else is provided by the user. So...

	git get repo.com/time_machine.git

would create a local branch named "remotes/default/master" if the remote 
repo has only a master branch.

Then, a simple:

	git merge

could be the same as

	git merge default

which would be equivalent to

	git merge default/master

Afterwards, because the "default" remote already exists, then:

	git get

would be the same as

	git get default

to get changes for all branches in the "default" remote branches, of 
which "master" might be the only one in the simple case.

But again I think it is important that the URL to use must be a per 
branch attribute i.e. attached to "default/master" and not just 
"default".  This way someone could add all branches of interest into the 
"default" group even if they're from different repositories, and a 
simple  get without any argument would get them all.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> But again I think it is important that the URL to use must be a per 
> branch attribute i.e. attached to "default/master" and not just 
> "default".  This way someone could add all branches of interest into the 
> "default" group even if they're from different repositories, and a 
> simple  get without any argument would get them all.

I think the "one group per one remote repository" model is a lot
easier to explain.  At least when I read your first "branch
group" proposal that was I thought was going on and I found it
quite sensible (and it maps more or less straightforwardly to
the way existing .git/refs/remotes is set up by default).

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > But again I think it is important that the URL to use must be a per 
> > branch attribute i.e. attached to "default/master" and not just 
> > "default".  This way someone could add all branches of interest into the 
> > "default" group even if they're from different repositories, and a 
> > simple  get without any argument would get them all.
> 
> I think the "one group per one remote repository" model is a lot
> easier to explain.  At least when I read your first "branch
> group" proposal that was I thought was going on and I found it
> quite sensible (and it maps more or less straightforwardly to
> the way existing .git/refs/remotes is set up by default).

I think one group per remote repo is how things should be by default 
too.  But we should not limit it to that if possible.

Re: Cleaning up git user-interface warts

[Karl Hasselström]

On 2006-11-15 13:11:36 -0500, Nicolas Pitre wrote:

> On Wed, 15 Nov 2006, Junio C Hamano wrote:
>
> > Nicolas Pitre <nico@cam.org> writes:
> >
> > > But again I think it is important that the URL to use must be a
> > > per branch attribute i.e. attached to "default/master" and not
> > > just "default". This way someone could add all branches of
> > > interest into the "default" group even if they're from different
> > > repositories, and a simple get without any argument would get
> > > them all.
> >
> > I think the "one group per one remote repository" model is a lot
> > easier to explain. At least when I read your first "branch group"
> > proposal that was I thought was going on and I found it quite
> > sensible (and it maps more or less straightforwardly to the way
> > existing .git/refs/remotes is set up by default).
>
> I think one group per remote repo is how things should be by default
> too. But we should not limit it to that if possible.

Without the limitation, we risk name collisions when getting all
branches from the remote repository (that is, including any new
branches we previously didn't know about).

-- 
Karl Hasselström, kha@treskal.com

Re: Cleaning up git user-interface warts

[Alan Chandler]

On Wednesday 15 November 2006 15:41, Nicolas Pitre wrote:
> On Wed, 15 Nov 2006, Andy Parkins wrote:
> >  * Don't use the name "origin" twice.  In fact, don't use it at all.  In
> > a distributed system there is no such thing as a true origin.
>
> I agree, sort of.  Not because"origin" is ambigous as a name.  But
> rather because there is a magic translation from "master" to "origin",
> and I think this is wrong to do that.
>
> As mentioned elsewhere (and let's start using "get" instead of "pull" as
> suggested by Johannes), a "get" should probably always create a branch
> group even if it contains only one branch.  This way the remote branch
> called "master" will still be called "master" locally, under the branch
> group used to represent the remote repository.  And if a local name is
> not provided then let's just call it "default".  This way, amongst the
> remote references, there would be a "default/master" that would be used
> when nothing else is provided by the user. So...
>
> 	git get repo.com/time_machine.git
>
> would create a local branch named "remotes/default/master" if the remote
> repo has only a master branch.

Why not call it remotes/repo.com/time_machine.git/master and have a 
DEFAULT_ORIGIN that is a symref to it in the same way as HEAD is a symref to 
a local branch

-- 
Alan Chandler

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Andy Parkins <andyparkins@gmail.com> writes:

>> 3) remote branch handling should become more straight forward.
>
> I was completely confused by this origin/master/clone stuff when I started 
> with git.  In hindsight, now I understand git a bit more, this is what I 
> would have liked:
>
>  * Don't use the name "origin" twice.  In fact, don't use it at all.  In a 
> distributed system there is no such thing as a true origin.
>
>  * .git/remotes/origin should be ".git/remotes/default".   "origin" is only 
> special because it is the default to push and pull - it's very nice to have a 
> default, but it should therefore be /called/ "default".

I think the naming is just a minor detail and can be overridden
with "clone --origin" already.  Renaming it to default is just
like making separate-remote the default to me -- it is fine as
long as it does not break people's expectations.

>  * If clone really wants to have a non-read-only master, then that should 
> be .git/refs/heads/master and will initialise 
> to .git/refs/remotes/$name/master after cloning.  Personally I think this is 
> dangerous because it assumes there is a "master" upstream - which git doesn't 
> mandate at all.  Maybe it would be better to take the upstream HEAD and 
> create a local branch for /that/ branch rather than require that it is 
> called "master".

I think the latter is what clone has done always; take remote's
HEAD and use that to initialize local master (there is no
confusion coming from multiple peer repositories because you
clone from only one place to initialize the repository -- that
one _is_ the origin), and we even keep the HEAD pointing at the
remote's master or whatever it points at at the remote.  Using
"$name" as an object name uses .git/refs/remotes/$name/HEAD.

>  * git-clone should really just be a small wrapper around
>...
> If git-clone does anything that can't be done with settings in the config 
> and the remotes/default file then it's wrong.  The reason I say this is that 
> as soon as git-clone has special capabilities (like --shared, --local 
> and --reference) then you are prevented from doing magic with existing 
> repositories.

That is not entirely true.  clone has convenience because people
asked.  It does not have to mean you are not allowed to give
similar convenience to other commands.  Patches?

> branches from two other local repositories that have the objects hard linked?

fetch by second local repository with git-local-fetch perhaps.

> There have been lots of "wishlist" posts lately; would it be
> useful if I tried to collect all these suggestions from
> various people into one place to try and get a picture of any
> consensus?

A list of common things wished by people certainly is a handy
thing to have.

A consensus would not write code and it generally does not take
technology into account to tell what is realistic and what is
not, so the result needs to be take with a grain of salt,
though.

Re: Cleaning up git user-interface warts

[Andy Parkins]

On Wednesday 2006, November 15 17:55, Junio C Hamano wrote:

> I think the latter is what clone has done always; take remote's
> HEAD and use that to initialize local master (there is no

It's this sort of thing that is confusing though - the remote HEAD branch 
could be anything, and yet that is made to be origin locally as a tracking 
branch and then master as the writable branch.  What if upstream /has/ a 
master but "next" is its HEAD?  You'd then get

 next:remotes/origin
 master:remotes/master

Then a local master which is actually upstream next!  Oh dear.

I may well have misunderstood what you've said above above clone always 
initialising master from remote's HEAD; if so please disregard what I'm 
saying.

> > that as soon as git-clone has special capabilities (like --shared,
> > --local and --reference) then you are prevented from doing magic with
> > existing repositories.
>
> That is not entirely true.  clone has convenience because people
> asked.  It does not have to mean you are not allowed to give
> similar convenience to other commands.  Patches?

Absolutely, that was why I said clone shouldn't have special abilities.  In 
fact, if you're willing you don't need clone at all; you just need 
git-init-db and to write the correct remotes file.  

> > branches from two other local repositories that have the objects hard
> > linked?
>
> fetch by second local repository with git-local-fetch perhaps.

Is that not plumbing?  I thought this was about porcelain.

> A consensus would not write code and it generally does not take
> technology into account to tell what is realistic and what is
> not, so the result needs to be take with a grain of salt,
> though.

Of course, I only suggested it because the same suggestions were popping up 
multiple times.  Anyway; I put it in the GitWiki at 
http://git.or.cz/gitwiki/Wishlist

Andy

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

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 10:17:22AM CET, Andy Parkins wrote:
> On Wednesday 2006 November 15 04:32, Nicolas Pitre wrote:
> 
> > 3) remote branch handling should become more straight forward.
> 
> I was completely confused by this origin/master/clone stuff when I started 
> with git.  In hindsight, now I understand git a bit more, this is what I 
> would have liked:
> 
>  * Don't use the name "origin" twice.  In fact, don't use it at all.  In a 
> distributed system there is no such thing as a true origin.
> 
>  * .git/remotes/origin should be ".git/remotes/default".   "origin" is only 
> special because it is the default to push and pull - it's very nice to have a 
> default, but it should therefore be /called/ "default".

  But "default" is way too generic a name, it's much more confusing I
think. As the one guilty of inventing master and origin, I agree that
they are somewhat silly, but if I would have to pick which one to
replace with something "better", I'd much rather pick master.

  Yes, Git can operate in a completely distributed manner. People do use
it as it. And there are also people that have no origin branch in their
repository. But the vast (overwhelming!) majority of people _does_ work
in some kind of hierarchical setup, and for them origin does have a
meaning. And origin URL can even change over time!

>  * git-clone should really just be a small wrapper around
>     - git-init-db
>     - create .git/remotes/default
>     - maybe create specific .git/config
>     - git-fetch default
>    If git-clone does anything that can't be done with settings in the config 
> and the remotes/default file then it's wrong.  The reason I say this is that 
> as soon as git-clone has special capabilities (like --shared, --local 
> and --reference) then you are prevented from doing magic with existing 
> repositories.  For example; how do you create a repository that contains 
> branches from two other local repositories that have the objects hard linked?

  Here I think that modulo the lack of remotes support (which is not a
fundamental thing here), the general setup of how Cogito does stuff is
much more saner than the current Git mess. It does basically exactly
what you've said above, and even the fetching itself is IMHO written
much more cleanly than in Git. In an ideal world, Git would just take
Cogito's code here. :-)

> While I'm writing wishes, I'd like to jump on Junio's integration with other 
> fetch-backends wish.  I use git-svn, and it would be fantastic if I could 
> replace:
> 
> git-svn init --id upstream/trunk svn://host/path/trunk
> git-svn fetch --id upstream/trunk
> git-svn init --id upstream/stable svn://host/path/branches/stable
> git-svn fetch --id upstream/stable
> 
> With a .git/remotes/svn
>  SVN-URL: svn://host/path
>  Pull: trunk:refs/remotes/upstream/trunk
>  Pull: branches/stable:refs/remotes/upstream/stable
> and
>  git fetch svn
> 
> Obviously, the syntax is just made up; but you get the idea.  Even better, 
> would be if it could cope with my "*" syntax suggested above:
>  SVN-URL: svn://host/path
>  Pull: trunk:refs/remotes/upstream/trunk
>  Pull: branches/*:refs/remotes/upstream/*

  It shouldn't be hard to do at all. Have the porcelain call "protocol
drivers" based on protocol in some generic way, like
/usr/lib/git/protocol/$proto.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Andreas Ericsson]

Nicolas Pitre wrote:

[ axed a lot of stuff that I didn't fully grok ]

> 
> This becomes formalized as:
> 
> 	git_pull [<URL>] [<local_name>]
> 
> If <URL> includes a branch name then <local_name> is a single branch 
> name.  If <URL> doesn't include any branch name then <local_name> 
> becomes a local branch group name containing all branches in the remote 
> repository.

I would change that so "local_name" is always a branch group name, but 
branch group names can be used as refs. That is,

git pull startrek.com/kirk.git:master kirk

would always create the branch-head .git/refs/remote/kirk/master which 
for short can be referenced as just "kirk" (barring clashes ofc), so 
long as it only has one branch tracked.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Andreas Ericsson wrote:

> Nicolas Pitre wrote:
> 
> [ axed a lot of stuff that I didn't fully grok ]
> 
>> 
>> This becomes formalized as:
>> 
>>      git_pull [<URL>] [<local_name>]
>> 
>> If <URL> includes a branch name then <local_name> is a single branch 
>> name.  If <URL> doesn't include any branch name then <local_name> 
>> becomes a local branch group name containing all branches in the remote 
>> repository.
> 
> I would change that so "local_name" is always a branch group name, but 
> branch group names can be used as refs. That is,
> 
> git pull startrek.com/kirk.git:master kirk

I'd rather use Cogito (not gitweb) notation startrek.com/kirk.git#master
This way we can change the name of local branch
   startrek.com/kirk.git#master:kirk
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 05:32:06AM CET, Nicolas Pitre wrote:
> 1) make "git init" an alias for "git init-db".
> 
> What's the point of "-db"?  Sure we're initializing the GIT database.  
> But who cares?  The user doesn't care if GIT uses a "database" or 
> whatever.  And according to some people's definition of a "database" it 
> could be argued that GIT doesn't use a database at all in the purist 
> sense of it. What the user wants is to get started and "init" (without 
> the "-db" is so much more to the point. Doesn't matter if incidentally 
> it happens to be the same keyword HG uses for the same operation because 
> we are not afflicted by the NIH disease, right? And it has 3 chars less 
> to type which is for sure a premium improvement to the very first GIT 
> user experience!

(This is somewhat related to the HEAD issue, e.g.
<7v1wo3d6g4.fsf@assigned-by-dhcp.cox.net>, by virtue of basically
eliminating it.)

Let's see. If you are adding the alias, you can as well add some
porcelain stuffing in it, too.

What are the 99% of use cases when doing "init"?

(a) You are going to do an initial commit right away; the repository is
at this point basically useless for anything but initial commit. So you
might have "init" well just perform it for you right away.

(b) You are setting up a bare repository on a server and you will push
to it in a minute. Cogito has a separate cg-admin-setuprepo command for
it, which will also prepare it for usage by dumb servers and optionally
for shared usage in a group of users. Git could have something similar.


> 2) "pull" and "push" should be symmetrical operations
..snip..
> Conclusion:  git-pull must not perform any merge.  It is the symmetrical 
> operation of a push meaning that it pulls content from a remote branch 
> and does no more.  People understands that pretty well, .  This makes 
> git-fetch redundant (or an alias to git-pull) in that case, and again we 
> don't mind it becoming similar to in HG because we admit HG was right 
> about it.

If you _really_ want to do it in Git, the only sensible way to do it is
to stop using the "pull" verb for a command name altogether for at least
some rather long period of time, otherwise that's a blatant backwards
compatibility breakage.

> 3) remote branch handling should become more straight forward.
> 
> OK! Now that we've solved the pull issue and that everybody agrees with 
> me (how can't you all agree with me anyway) let's have a look at remote 
> branches.  It should be simple:
..snip..

By the way, due to the way you describe it, it's not all that clear to
me how is this (in)compatible with the current way we do it, on other
than the usage and git-pull's auto-creation magic level.

Is it that what you are describing _is_ in fact what we do support now,
with "branch groups" meaning "remotes" etc, and you are only proposing
some enhancements to automatically create remotes in git-pull, or are
there some other differences I've missed?

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Tue, Nov 14, 2006 at 11:36:19PM CET, Junio C Hamano wrote:
> Commenting on the messages in this thread:
> 
>  - "resolve / resolved" are both confusing, when you are talking
>    about "mark-resolved" operation.

Well that's what "resolved" is saying. But speaking of which, it took me
_weeks_ of regular (though not extensive) usage to train my fingers to
write "stg resolved" and not "stg resolve".

>  - "pull/push/fetch" have undesired confusion depending on where
>    people learned the term.  I'd perhaps vote for replacing
>    fetch with download and push with upload.

It's too long. :-(

I think if some people have a real problem with something it's "pull",
not push or fetch. Without "pull" name, there's no confusion about
merging or not merging; and without it, there's also no confusion about
"push" and the fetch/push duality. I'm not saying that this is enough an
argument to ditch pull from Git at this point.

>  - I think it would be sensible to make remote tracking branches
>    less visible.  For example:
> 
> 	git diff origin
> 
>    where origin is the shorthand for your upstream (e.g. you
>    have .git/remotes/origin that records the URL and the branch
>    you are tracking) should be easier to understand than
> 
>    	git diff remotes/origin/HEAD
> 
>    The latter is an implementation detail.

Hmm, wait. I didn't start using refs/remotes/ yet for obvious reasons,
but wasn't it generally agreed when implementing them that what you
wrote above would work? (That a ref not found in refs/{heads,tags}/ is
looked up in remotes and if it's a directory, /HEAD is appended.) So it
doesn't for some reason?

>    I could imagine we might even want to allow
> 
> 	git diff origin#next
> 
>    to name the branch of the remote repository.  The notion of
>    "where the tips of remote repository's branches are" is
>    probably be updated by "git download" (in other words, the
>    above "git diff" does not automatically initiate network
>    transfer).

Yes, that little syntax extension would be cute to have.

> Of course, it could even be "cg" ;-).

So, here is an arbitrary list of random reasons why cg commands are not
part of git yet:

(i) Naming issues. Example: "pull" vs. "update".

(ii) Namespace issues. Big selling point of Cogito is that it's
_simple_. A very important part of that is that your command set is
limited, so that even someone who wants to fully grok Cogito is not
overwhelmed and has just few commands in front of him. I think we're
doing pretty good here, and I very carefully weight adding another
command to the set (I'm actually pondering removing some now). The
similar applies to actual commands' usage, though certainly not so
heavily; and there are few warts here.

But overally, I think this point is pretty much unsolvable and this is
where I actually think the main "incompatibleness" of Cogito and Git
with its free mix of high- and mid- and low- level commands lies. I
don't think the thread provided any solution to this either.

(ii) Behaviour issues. Example: Cogito tries to deal with uncommitted
local changes in your repository when doing stuff. It didn't shine at it
before recent improvements (post-v0.18), but it tried to preserve your
local uncommitted changes during various operations (merging,
fast-forwarding, switching branches, seeking, ...). I think historically
Git's stance to this was negative (it'd rather block the operation), I'm
not sure what the current situation is, though.

(iii) Output format issues. Example: "status" in Git and Cogito
has a completely different format in both. I'm a die-hard fan of
Cogito's format but there're surely die-hard fans of Git's.

(iv) Control issues. I'm reluctant to give up a final word on how the UI
looks like, mostly for the reason of enforcing (ii) and proper
documentation. But this is not a blocker point.

(v) Library issues. Cogito has a pretty neat shell library which it
prices; but that could be carried around. Also, Cogito requires
/bin/bash, but mostly for performance reasons (using builtins instead of
forking for external commands at some points); Git has the advantage of
simply putting that part in C, which is though something I should've
been doing more frequently too.

(vi) Coding issues. This is probably very subjective, but a blocker for
me. I have no issues about C here, but about the shell part of Git.
Well, how to say it... It's just fundamentally incompatible with me. I
*could* do things in/with it, but it's certainly something I wouldn't
_enjoy_ doing _at all_, on a deep level. I think the current shell code
is really hard to read, the ancient constructs are frequently strange at
best, etc. It's surely fine code at functional level and there'll be
people who hate _my_ style of coding and my shell code which isn't
perfect either, but it's just how it is with me.


Now, it would be absolutely awesome if we could start to bridge at least
some of these points, shuffle some functionality around and overally
reduce the code duplication, increase features count and improve general
level of world happiness.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

> (v) Library issues...
> Git has the advantage of
> simply putting that part in C, which is though something I should've
> been doing more frequently too.

It should be stressed that git-core plumbing written in C is not
just for git Porcelain-ish, and it will continue to be shared
service.  We would add core support for what Porcelains need and
we would try hard to keep them generic enough so that other
Porcelains can use them.  Keeping the core and Porcelain-ish in
the same project has made it easier to keep them in sync and to
find and add missing features that would benefit Porcelains (not
limited to git Porcelain-ish).  But that should not be mistaken
as plumbing somehow belongs more to git Porcelain-ish than to
Cogito or others.

I also think you should take credit for some core improvements
you did yourself (e.g "ls-files -t" format was originally added
for the sole purpose of helping Cogito, but now others use it,
too).

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Thu, Nov 16, 2006 at 11:45:46AM CET, Junio C Hamano wrote:
> Petr Baudis <pasky@suse.cz> writes:
> 
> > (v) Library issues...
> > Git has the advantage of
> > simply putting that part in C, which is though something I should've
> > been doing more frequently too.
> 
> It should be stressed that git-core plumbing written in C is not
> just for git Porcelain-ish, and it will continue to be shared
> service.  We would add core support for what Porcelains need and
> we would try hard to keep them generic enough so that other
> Porcelains can use them.  Keeping the core and Porcelain-ish in
> the same project has made it easier to keep them in sync and to
> find and add missing features that would benefit Porcelains (not
> limited to git Porcelain-ish).  But that should not be mistaken
> as plumbing somehow belongs more to git Porcelain-ish than to
> Cogito or others.

  Of course, I didn't mean to say that. I should do more often things
like adding --stdin to the fetchers. From one part, I'm used to work
with a fixed set of system tools and extending Git with the
functionality I want means changing my thinking mode and "jumping out of
the system" a bit. The other part is that I cannot use the improvements
in Cogito right away (at least not in the main branch) but I have to
wait for the next Git release; but this is mostly just an excuse. :-)

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

> (vi) Coding issues. This is probably very subjective, but a blocker for
> me. I have no issues about C here, but about the shell part of Git.
> Well, how to say it... It's just fundamentally incompatible with me. I
> *could* do things in/with it, but it's certainly something I wouldn't
> _enjoy_ doing _at all_, on a deep level. I think the current shell code
> is really hard to read, the ancient constructs are frequently strange at
> best, etc. It's surely fine code at functional level and there'll be
> people who hate _my_ style of coding and my shell code which isn't
> perfect either, but it's just how it is with me.

I've been thinking about revamping the style of shell scripts in
git-core Porcelain-ish for some time, and I have a feeling that
now may be a good time to do so, after one feature release is
out and the list is discussing UI improvements.

But before mentioning the specifics, let me mention one tangent.
I recently installed an OpenBSD bochs (it was actually a qemu
image) without knowing much about the way of the land, and after
adjusting myself to necessary glitches (like "make" being called
"gmake" there), I saw git properly built and pass its selftest.
I was pleasantly surprised when I noticed there was no 'bash' on
the system after all that.

I would like to keep it that way.

I'll list things I would want to and not want to change.
Comments from the list are very appreciated.  You can say things
in two ways:

 * I guarantee that the _default_ shell on all sane platforms we
   care about handle this construct correctly, although it was
   not in the original Bourne.  There is no reason to stay away
   from it these days.

or

 * You've stayed away from this construct but now you say you
   feel it is Ok to use it.  Don't.  It would break with the
   shell on my platform (or "it is a bad practice because of
   such and such reasons").

I do not think many people can say the former with authority
unless you have a portability lab (the company I work for used
to be like that and it was an interesting experience to learn
all about irritating implementation differences).  And "POSIX
says shell should behave that way" is _not_ what I want to hear
about.

But the latter should be a lot easier to say, and would be
appreciated because it would help us avoid regressions.

Things I would want to change:

 - One indent level is one tab and the tab-width is eight
   columns.  Some of our scripts tend to use less than eight
   spaces for indentation to avoid line wrapping.

 - More use of shell functions are fine.   Especially if the
   above change makes lines too long, the logic should be
   refactored.

 - It is so 80-ish to follow certain portability and performance
   wisdom.  The following should go:

   . Use "case" when you do not have to use "if test".

   . Avoid ${parameter##word} and friends and use `expr` instead
     to pick a string apart.

   . Avoid "export name=word", write "name=word; export name"
     instead.

   . Avoid ${parameter:-word} and friends when ${parameter-word}
     would do.

Things I do not want to change:

 - The shell scripts should start with #!/bin/sh, not
   #!/bin/bash (nor even worse "#!/usr/bin/env sh").

 - Shell functions are written as "name () { ... }" without 
   "function" noiseword.

 - 'foo && bar || exit' exits with the error code of what
   failed; no need to say 'exit $?'.

 - String equality check for "test" is a single =, not ==. 

 - Do not use locals.

 - Do not use shell arrays.

 - In general, if something does not behave the same way in ksh,
   bash and dash, don't use it (that does not mean these three
   are special; it just means if something is not even portable
   across these three, it is a definite no-no).

I do not think I need to list other common-sense shell idioms in
the latter category (e.g. 'using "test z$name = zexpected" when
we do not know what $name contains' falls into that).

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Thu, Nov 16, 2006 at 10:49:36PM CET, Junio C Hamano wrote:
> I would like to keep it that way.

I agree - I certainly don't want to infect Git with bash dependency.

> And "POSIX says shell should behave that way" is _not_ what I want to
> hear about.

Actually, which sane platforms we care about have /bin/sh that is NOT
POSIX compatible?

> Things I would want to change:

What about [ instead of test? And

	if foo; then

instead of

	if foo
	then

?


Am I the only one who hates

case "$log_given" in
tt*)
        die "Only one of -c/-C/-F can be used." ;;
*tm*|*mt*)
        die "Option -m cannot be combined with -c/-C/-F." ;;
esac

instead of having this stuff in explicit variables and writing out some
explicit boolean expressions? (There _are_ few cases where the case is
cool, but they are rare.)


It would be really great if Git would have something alike the Cogito's
optparse infrastructure. I'm not sure if you can implement it in Bourne
sh with reasonable performance, though...


I think addressing these three particular points would make the scripts
hugely more coder-friendly. (And well, I usually say that coding style
is not *that* important and is frequently overemphasised. But that holds
only to a certain point. ;-)


> Things I do not want to change:
..snip all those I agree with..
>  - Do not use locals.

It's a pity. :-( Which shell doesn't support them?

It's not that huge a deal, though.

>  - Do not use shell arrays.

This is quite a larger deal, I think; but the portability concerns are
very real, I guess. :|

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

You already said this kind of details are subjective so I'd omit
the usual "I would think" and answer them without worrying about
a big style flamewar.  People, please be civil ;-).

> What about [ instead of test?

[ ] is not more readable.

> 	if foo; then
>
> instead of
>
> 	if foo
> 	then

Having "then" on the beginning of line is much more readable.

> Am I the only one who hates
>
> case "$log_given" in
> tt*)
>         die "Only one of -c/-C/-F can be used." ;;
> *tm*|*mt*)
>         die "Option -m cannot be combined with -c/-C/-F." ;;
> esac

This is much more readable without "case".  "abandon the old
rule that told us to avoid if when case would do" applies.
Although it is about multiple possibility switch (so a case can
be made that "case" is appropriate here), we should reduce the
use of "case" to cases like the outermost big "case" you find in
git-merge-one-file-script.

> It would be really great if Git would have something alike the Cogito's
> optparse infrastructure. I'm not sure if you can implement it in Bourne
> sh with reasonable performance, though...

getopt(1) is fine, unless somebody screams that it is not
available on his platform.

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Petr Baudis escreveu:
> (vi) Coding issues. This is probably very subjective, but a blocker for
> me. I have no issues about C here, but about the shell part of Git.
> Well, how to say it... It's just fundamentally incompatible with me. I

(on a tangent)

I concur, but probably in a different way.

some 10 years ago I vowed never to write perl code again, and some 5
years ago, I made the same pledge for shell scripts, because I spent
inordinate amounts of time debugging them.

When I see the GIT shell scripts, my hands start to itch to make a
nice object oriented Python wrapper for it.

-- 

Re: Cleaning up git user-interface warts

[Alan Chandler]

On Tuesday 14 November 2006 22:36, Junio C Hamano wrote:
...
>
> And I agree with Pasky that fixing UI is hard unless you are
> willing to get rid of historical warts.  Syntax of the command
> line arguments the current set of Porcelain-ish takes are
> sometimes just horrible.  It may not be a bad idea to start
> building the fixed UI from scratch, using different prefix than
> "git" (say "gu" that stands for "git UI" or "gh" that stands for
> "git for humans").
>
> Of course, it could even be "cg" ;-).

I have been away on business last week and have been following this thread 
from the archives.  There is a comment I want to make about split of 
Porcelain and Plumbing namespaces that is not particularly an answer to this 
particular post, but it does seem an appropriate place to insert it.

I think there were three (historic) mistakes in the development of git
	- to split git and cogito so that some of the commands started git and some 
cg (aided and abetted by putting them in separate repositories).
	- to try and make the distinction between plumbing and porcelein a line in 
the sand (after all this is exactly why git and cg separated) when in 
practice it isn't that straight forward
	- for cogito to (initially) not support the internal branches, but in fact 
deal with them via cloned repositories

On the other hand, it was a good move to bring gitk and gitweb into the core 
repository.

These were not technical mistakes, but social ones.

Much of the discussion on UI warts doesn't exist in the cogito world (not that 
I use it at all anymore, despite its more user friendly interface - just 
because I didn't want to learn two parallel sets of commands and I prefered 
git's branch model so stuck with the slightly less friendly git command set) 
but if you look at any of the SCM comparison discussions that happen now, 
they are always comparing the core git with the other SCM, not git plus all 
its porcelains.

So I think it would be a mistake (which hopefully does seem to be the 
concensus reached in the list) to try and introduce new namespaces to the 
command set.
-- 
Alan Chandler