Re: [PATCH] Documentation: add a planning document for the next CLI revamp

["Elijah Newren" <newren@gmail.com>]

Hi,

(Sorry for sending so many emails, and being late to the conversation.
 There's a couple others that I wanted to respond to but I'll wait off
on those and finish with this email to avoid spamming everyone any
more right now.)

On Thu, Oct 30, 2008 at 11:51 AM, Sam Vilain <sam@vilain.net> wrote:
> Well, I don't have strong feelings on the exact command name used; I
> suggested "undo", probably also ambiguous.  But still, a significant
> number of users are surprised when they type 'git revert' and they get a
> backed out patch.  It's such an uncommon operation, it doesn't deserve
> to be triggered so easily.  And reverting files to the state in the
> index and/or HEAD is a common operation that deserves being short to
> type.
>
> Making it plain "revert" would violate expectations of existing users;
> it seems a better idea to just deprecate it, and point the users to the
> new method - cherry-pick --revert - or the command they might have meant
> - whatever that becomes.

There is another option, though it has its own problems too.  There
are basically two kinds of reverting here -- reverting all the changes
*in* a given revision (which I'll called 'revert-in') and reverting
all the changes *since* a given revision (typically HEAD; I'll call
this 'revert-since').  These two operations can be supported from the
same command, though their use cases are different enough that it may
seem slightly weird:

     revert-since                        revert-in
     * is usually used in a dirty tree   * is typically used in a clean tree
     * specific paths are usually        * specific paths are not often
       specified                           specified
     * it is rare to want to commit      * making a commit after reverting
       immediately after reverting         is what you usually want
     * it is uncommon to need to
       specify a revision

I decided to combine them in EasyGit, simply because that made things
the most discoverable for both existing git and svn/bzr/hg users.  The
big problem here is that --commit is turned on by default when --in is
specified, and --no-commit is the default when --since is specified.
Anyway, some examples:

eg revert REVISION   =>   Error -- you must specify either --since or
--in when specifying a revision
eg revert --in REVISION  =>  Same as git revert REVISION
eg revert --since HEAD FILE1 FILE2  =>  Same as svn revert FILE1 FILE2
eg revert FILE1 FILE2  => shorthand for the previous command; --since
HEAD is default when no revision is specified
eg revert --since HEAD~3 SUBDIRECTORY => should be clear; an extension
over what svn revert can do

Then there's also the possibility that users only want to revert
unstaged changes, or only want to revert staged changes...


Anyway, just some food for thought.  I've spammed the list enough in
this thread, so I'll break for now.  Thanks for listening.

Elijah