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

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

Hi,

On Thu, Oct 30, 2008 at 8:39 AM, Theodore Tso <tytso@mit.edu> wrote:
> Here are my favorites:
>
> * Add the command "git revert-file <files>" which is syntactic sugar for:
>
>        git checkout HEAD -- <files>
>
>  Rationale: Many other SCM's have a way of undoing local edits to a
>  file very simply, i.e."hg revert <file>" or "svn revert <file>", and
>  for many developers's workflow, it's useful to be able to undo local
>  edits to a single file, but not to everything else in the working
>  directory.  And "git checkout HEAD -- <file>" is rather cumbersome
>  to type, and many beginning users don't find it intuitive to look in
>  the "git-checkout" man page for instructions on how to revert a
>  local file.

I agree with the rationale, but the suggested implementation (as with
the original suggestion for "git undo") is somewhat problematic.  I
have a write-up somewhere documenting the ways various individual git
commands fail to be an appropriate replacement for svn/hg/bzr
revert[1], but in short the "git checkout HEAD -- <file>"
implementation for svn/hg/bzr-like revert fails in the following ways:
  * It does not work for the initial commit
  * It won't untrack or remove files (this is related to the previous
and following items)
  * It doesn't allow reverting a file or directory to a revision prior
to HEAD (making it like svn; note though that both bzr and hg have
such an option and I have found it handy a few times)
  * It's inappropriate to use during an incomplete merge.

The incomplete merge case is particularly interesting.  If the user
specifies a file or subdirectory, they should also specify a branch to
revert relative to (and it should be an error if they don't).  If the
user specifies "." then there's the question of whether they are
attempting to undo the merge (meaning that .git/MERGE_MSG and
.git/MERGE_HEAD should be removed).

Just as food for thought, here's what eg does in the incomplete merge case:

$ eg revert foo
Aborting: Cannot revert the changes since the last commit, since you are in
the middle of a merge and there are multiple last commits.  Please add
  --since BRANCH
to your flags to eg revert, where BRANCH is one of
  master, devel
If you simply want to abort your merge and undo its conflicts, run
  eg revert --since HEAD


There's a couple more issues here that I could go on about, but I'll
mention just one more thing for this email:  Since users often get
confused between different kinds of "reverting" or "undoing", a plain
'eg revert' is also pretty helpful in a wide variety of circumstances
(it always aborts with an error message, but one that detects what the
user might want and suggests appropriate commands in the various
cases.)

Elijah


[1] There are a number of different commands that people suggest for
new users to replace other systems' revert behavior, but each has
areas in which it will fail to do what users expect or do additional
things users don't want (including discarding data)  Interestingly,
I've tried four different alternative git porcelains and each one
implemented their svn/hg/bzr-like revert incorrectly.  One of these
was EasyGit, in which I got it wrong not once but three separate
times.  (And if alternative porcelain authors can't easily get it
right, we clearly can't expect normal users to know how to do so; I
think this is a pretty good argument for providing a function for this
behavior in core git.)  I think I finally have it implemented
correctly now in EasyGit, after my fourth try...