Re: EasyGit Integration

Sam Vilain [off-list ref] writes:

We talked about this much at GitTogether '08. It's true that for
'reverting' a change in the past, that is the right thing to do. However
I don't think there is a first principles case that this is always what
people mean by 'revert'....

Sorry; what you think people mean by 'revert' does not matter at this
point, unless you are building a brand-new system from scratch.

I think as long as there is a deprecation cycle, and that users can
select the old behaviour (either via an alias or a config option), then
we shouldn't upset many long-time users of revert. Do you agree?

I actually don't.

I do not think introducing "git revert-file" (or "git revert -- path") is
a problem at all.  But "git revert $commit" has been and is an integral
part of the established git workflow, and I do not see a point in changing
it to mean something else, with any deprecation period.

By the way, I have a bigger issue.

Some changes in "eg" may port well as a new command to git-core, and some
change (like this "revert" thing that has different semantics and breaks
established workflow) will never be in git-core.  People may think that it
would not cause many problems if we picked only the non-conflicting bits,
but I actually have some reservations about that.

It will bloat the total number of subcommands you can give git, with the
end result being

 (1) old timers won't use "revert-commit" and "revert-file" at all but use
     "revert" and "checkout -- path"; while

 (2) new people will behave the other way; and

 (3) the documentation will list all of commands from these two disjoint
    sets under "git".

When a "eg" minded person teaches git, the students may have to be told to
ignore "revert" and "checkout -- path", because there are other ways to do
the same thing in the lingo they are being taught, which is a subset of
git commands.  The manual pages will be littered with descriptions like
"this command, when used this way, is synonymous to using that other
command with this option", leaving the reader wondering why there are so
many ways to do the same thing.

If "eg" (I do not have _anything_ against it; the discussion applies to
other Porcelains as well) were kept independent _and_ offered complete set
of features that users need without resorting to git-core, on the other
hand, the students do not have to know about "revert", and the manuals
they need to consult will not have to talk about "if you are using
git-core, this is done differently in this way".  The learning curve will
get a lot smoother for new people.

If new and useful features (e.g. "creating a remote repository over SSH in
one shot") are supported by another Porcelain (e.g.  "eg") they may be
worth porting over to git-core, in order to make git-core more usable.
There is a precedent for that kind of side port (e.g. "filter-branch" that
came from Cogito).

But aliases for doing essentially the same thing in slightly different
syntax?  I'd rather not to see them called "git foo".  In the end, I think
it will harm the users, both new and old.

If you go back to the list archive, you will find me suggesting a new set
of commands with "gh" prefix, back in 1.3.X days, I think.

I was not joking.  The reasoning was exactly the same, and it remains so.

Junio C Hamano wrote:

quoted

I think as long as there is a deprecation cycle, and that users can
select the old behaviour (either via an alias or a config option), then
we shouldn't upset many long-time users of revert. Do you agree?
    

I actually don't.

I do not think introducing "git revert-file" (or "git revert -- path") is
a problem at all.  But "git revert $commit" has been and is an integral
part of the established git workflow, and I do not see a point in changing
it to mean something else, with any deprecation period.
  

Ok. Off-hand I can't remember why we excluded "git revert -- path" as
workable. Whatever that reason was led to the group of core developers
coming up with these "clearly" "_inferior_" names.

That could solve the problem, switching behaviour on the type of
argument passed rather than including it in the command name. I think
that was my preferred option at the time, too. Perhaps some other
attendees can recall more clearly...

Some changes in "eg" may port well as a new command to git-core, and some
change (like this "revert" thing that has different semantics and breaks
established workflow) will never be in git-core.  People may think that it
would not cause many problems if we picked only the non-conflicting bits,
but I actually have some reservations about that.

It will bloat the total number of subcommands you can give git, with the
end result being

 (1) old timers won't use "revert-commit" and "revert-file" at all but use
     "revert" and "checkout -- path"; while

 (2) new people will behave the other way; and

 (3) the documentation will list all of commands from these two disjoint
    sets under "git".

When a "eg" minded person teaches git, the students may have to be told to
ignore "revert" and "checkout -- path", because there are other ways to do
the same thing in the lingo they are being taught, which is a subset of
git commands.  The manual pages will be littered with descriptions like
"this command, when used this way, is synonymous to using that other
command with this option", leaving the reader wondering why there are so
many ways to do the same thing.
  

Yes, I agree that if the old behaviour is not being deprecated it
probably shouldn't be replicated as well.

In fact that may have been the argument for excluding 'git revert
filename' - because you can already do that with 'git checkout HEAD --
filename'; but perhaps in this case it is acceptable, because the
'checkout' command can also check out from other revisions, but revert
can't.

Sam.

On Tue, 9 Jun 2009, Junio C Hamano wrote:

Some changes in "eg" may port well as a new command to git-core, and some
change (like this "revert" thing that has different semantics and breaks
established workflow) will never be in git-core.  People may think that it
would not cause many problems if we picked only the non-conflicting bits,
but I actually have some reservations about that.

It will bloat the total number of subcommands you can give git, with the
end result being

 (1) old timers won't use "revert-commit" and "revert-file" at all but use
     "revert" and "checkout -- path"; while

 (2) new people will behave the other way; and

 (3) the documentation will list all of commands from these two disjoint
    sets under "git".

Nah.  This doesn't have to be so extreme.  Your example above is 
relevant, and I agree with you that this is unnecessary bloat.

However there are many other examples, such as "git branch -s" being 
equivalent to "git checkout -b" which I think are rather nice to have.

The 'git resolved' command for staging resolved conflicts is also nice.

Also does the streamlining of --abort/--continue for a couple commands.

This is why I said that such additions should be proposed piecemeal and 
judged separately.

When a "eg" minded person teaches git, the students may have to be told to
ignore "revert" and "checkout -- path", because there are other ways to do
the same thing in the lingo they are being taught, which is a subset of
git commands.  The manual pages will be littered with descriptions like
"this command, when used this way, is synonymous to using that other
command with this option", leaving the reader wondering why there are so
many ways to do the same thing.

This is not necessarily a good strategy to always list all equivalences.  
If someone learns from the git-branch man page that -s also switches to 
the newly created branch, then that person won't gain anything nor care 
to know that 'git checkout -b' does the same.

If "eg" (I do not have _anything_ against it; the discussion applies to
other Porcelains as well) were kept independent _and_ offered complete set
of features that users need without resorting to git-core, on the other
hand, the students do not have to know about "revert", and the manuals
they need to consult will not have to talk about "if you are using
git-core, this is done differently in this way".  The learning curve will
get a lot smoother for new people.

On the other hand, having multiple porcelains simply divide the user 
base which is not always a good thing.  Look at what happened to cogito 
for example: some people were using it, some people didn't and those two 
groups couldn't help each other efficiently.  Yet git used to do things 
badly that cogito did well, and the other way around too, which gave the 
impression that each system was suboptimal.  When git picked up the good 
things in cogito and cogito finally died then everybody was focusing on 
a single command-line-based porcelain for the better health of git which 
really gained momentum at that point.

In that sense, an alternative (command line) porcelain is effectively a 
fork.  Forks are good for experimental stuff and the like, but 
eventually it is always best for everyone involved if the better parts 
of the fork are merged back.  Any project with a fork that grew big and 
didn't merge back made the whole community weaker in the long run.

If new and useful features (e.g. "creating a remote repository over SSH in
one shot") are supported by another Porcelain (e.g.  "eg") they may be
worth porting over to git-core, in order to make git-core more usable.
There is a precedent for that kind of side port (e.g. "filter-branch" that
came from Cogito).

But aliases for doing essentially the same thing in slightly different
syntax?  I'd rather not to see them called "git foo".  In the end, I think
it will harm the users, both new and old.

Again this should be evaluated on a case by case basis.  I think this is 
clear already that re-targeting commands like revert is _not_ a good 
idea.  But some other examples are not so controversial.

If you go back to the list archive, you will find me suggesting a new set
of commands with "gh" prefix, back in 1.3.X days, I think.

I was not joking.  The reasoning was exactly the same, and it remains so.

And my opinion as explained above is that it is not a good idea.  Your 
suggestion didn't take off for a good reason.


Nicolas

Sam Vilain [off-list ref] writes:

Junio C Hamano wrote:

quoted

quoted

I think as long as there is a deprecation cycle, and that users can
select the old behaviour (either via an alias or a config option), then
we shouldn't upset many long-time users of revert. Do you agree?
    

I actually don't.

I do not think introducing "git revert-file" (or "git revert -- path") is
a problem at all.  But "git revert $commit" has been and is an integral
part of the established git workflow, and I do not see a point in changing
it to mean something else, with any deprecation period.
  

Ok. Off-hand I can't remember why we excluded "git revert -- path" as
workable. Whatever that reason was led to the group of core developers
coming up with these "clearly" "_inferior_" names.

"git revert -- path" is perhaps not unambiguous (but for the fact
whether it reverts from index, or from HEAD), but "git revert <rev> -- path"
can be understood as "git cherry-pick -R <rev> -- path" i.e. reverting
changes to given file or files in a commit.

And we have "git reset -- file", don't we.
-- 
Jakub Narebski
Poland
ShadeHawk on #git

Hey,

On Tue, Jun 9, 2009 at 7:18 PM, Junio C Hamano[off-list ref] wrote:

I do not think introducing "git revert-file" (or "git revert -- path") is
a problem at all.  But "git revert $commit" has been and is an integral
part of the established git workflow, and I do not see a point in changing
it to mean something else, with any deprecation period.

I would vote for simply adding 'revert-file' rather than overloading
another command with two completely different actions.

It will bloat the total number of subcommands you can give git, with the
end result being

It just seems that this is sort of a paving the cow paths practice - I
see a lot of people creating aliases for 'unstage' and 'revert-file'
and 'uncommit' and things that are relatively common but difficult to
remember how to do because they have very obscure syntaxes
(syntaxen?).

Worrying about subcommand bloat seems a tad silly at this point given
that there are over 150 valid verbs now, right?  If existing commands
do categorically different things depending on input values, doesn't
it make sense to simply have different verbs exist for each separate
action?  I mean, worrying about the usability issue of having too many
commands but not thinking that making users learn 'git reset HEAD
path' is an issue seems really strange to me.

If "eg" (I do not have _anything_ against it; the discussion applies to
other Porcelains as well) were kept independent _and_ offered complete set
of features that users need without resorting to git-core, on the other
hand, the students do not have to know about "revert", and the manuals
they need to consult will not have to talk about "if you are using
git-core, this is done differently in this way".  The learning curve will
get a lot smoother for new people.

I think I understand the argument here, but I really, really don't
want to suggest to people to install Git and then install a separate
porcelain, and then have them spend time learning a command set that
is completely absent from other machines that have Git installed.  I
realize this is also an issue with adding new commands (in that they
would be absent from machines with older Git installed) but that issue
fades away after a few years, where the previous does not - in fact,
it becomes a far more difficult problem.

If it's not installed with 'apt-get git-core' or what have you, then I
(and I assume others) are never going to waste everyones time teaching
them a niche tool they will never find elsewhere.

But aliases for doing essentially the same thing in slightly different
syntax?  I'd rather not to see them called "git foo".  In the end, I think
it will harm the users, both new and old.

It would be one thing if I were suggesting that 'git revert' be
changed to 'git regress' or something - it's not a simple naming
issue.  It's more that things like "git reset HEAD <file>..." to
unstage simply makes no sense unless you have a pretty technical
understanding of reset, the index and HEAD - none of which a beginning
user should need to learn right off the bat.  Unstaging files _is_,
however, something that a brand new user will need to do right off the
bat.  The only paths left to them, then, are either learning the
technical details of the index and 'reset' to understand why that
command makes sense, or to simply learn the command by rote - which is
nearly always what ends up happening, since it's incredibly difficult
to learn the index well.  Hell, I've been using Git pretty extensively
for years now and I still have a hard time remembering exactly what
'reset' will do in different circumstances.

Easy things that users have to do a lot should be easy, is all.
Besides just being nice for users, it would probably save a lot of
grief for you guys with people asking and complaining about these
things on this list and the IRC channel.

If you go back to the list archive, you will find me suggesting a new set
of commands with "gh" prefix, back in 1.3.X days, I think.
I was not joking.  The reasoning was exactly the same, and it remains so.

Again, having to explain to people "most of the time you use gh for
all this stuff, but occasionally you use 'git'" or vice-versa is just
confusing and error prone.   Introducing some command denormalization
for the sake of getting new users on their feet with less friction
seems less painful both for the developers and experts having to help
said users and for the users themselves.

I wasn't suggesting a core rewrite, I just thought that hitting some
of this low hanging fruit - again, paving the cow paths as it were -
might be relatively painless and save everyone a lot of time.

Scott

On Wed, Jun 10, 2009 at 5:18 AM, Junio C Hamano[off-list ref] wrote:

Sam Vilain [off-list ref] writes:

quoted

We talked about this much at GitTogether '08. It's true that for
'reverting' a change in the past, that is the right thing to do. However
I don't think there is a first principles case that this is always what
people mean by 'revert'....

Sorry; what you think people mean by 'revert' does not matter at this
point, unless you are building a brand-new system from scratch.

Subversion is by far the most widely used VCS, it's quite likely that
new git users will come from the svn camp (I know I did), and it's
quite likely they will assume 'revert' is doing what svn does. Do you
think that doesn't matter at all?

You might think that 'git revert' is superior to 'svn revert' (and I
happen to agree with that statement), but at least you should take
into consideration the huge amount of users that would find this
behavior strange.

Personally, I would add a note to the 'git revert' documentation to be
extra-clear what 'git revert' is not.

-- 
Felipe Contreras