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

From: Elijah Newren <newren@gmail.com>
Date: Nov 1, 2008, 20:27 UTC
Message-ID: <51419b2c0811011327j492b520dq2388fc8972b48cab@mail.gmail.com>
In-Reply-To: <1225389068.19891.28.camel@maia.lan>

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:

Show 12 quoted lines

> 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