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

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

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

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.

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

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.

Nicolas Pitre wrote:

On Tue, 14 Nov 2006, Jakub Narebski wrote:

quoted

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

On Tue, 14 Nov 2006 18:55:51 +0000, Andy Whitcroft wrote:

Carl Worth wrote:

quoted

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

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!

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

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

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Carl Worth wrote:

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.

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

Carl Worth [off-list ref] 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.  :-)

-- 

On Tue, 14 Nov 2006, Jakub Narebski wrote:

Nicolas Pitre wrote:

quoted

On Tue, 14 Nov 2006, Jakub Narebski wrote:

quoted

quoted

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.

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

On Tue, 14 Nov 2006, Jakub Narebski wrote:

Nicolas Pitre wrote:

quoted

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

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