Re: [PATCH] Documentation/git-reset.txt: Use HEAD~N syntax everywhere (unify examples)

[Dmitry Potapov <dpotapov@gmail.com>]

On Sat, Feb 02, 2008 at 02:59:43PM +0200, Jari Aalto wrote:
> 
> I use HEAD~1 always, because I think the consistency in learning the
> most important factor.

People may have different preferences and there is nothing wrong with
that. However, imposing a single style on everyone is *wrong*. What you
propose is to hide a legitimate syntax on the ground that you do not use
it, and I don't think that is a good enough reason.

> It does not matter what advanced users use. The documentation should
> primarily focus the newcomers.

Wrong... and wrong again. First, this documentation is intended for all
users.  It is not "SVN Crash Course" or something like that intended for
newcomers. Second, there is nothing wrong with having more than one way
to express the same thing, and newcomers should be aware of that even if
they prefer to use HEAD~1 all the time.  If you don't tell them that,
they may be confused when encounter it later, and they will encounter it
sooner or later, because many of us use this ^-syntax.

> Those used to git may prefer ^, but it does not follow that others
> necessarily do so and that that should be the "proper learning path".

It seems to me that your "proper learning path" is based solely on
what you prefer, and not everyone shares your preferences here. In fact,
^-syntax is very natural to specify the _previous_ commit. Have you
notice we usually say "previous", not "one commit before"?

> People usually migrate to git from other VCSs, which have very
> consistent UI - There are no alternatives
> 
>     -r1:10      Subversion
>     -r1..19     Bzr
>     ...etc

First of all, this comparison is incorrect, because SVN uses fixed
numbers, which does not change over time. The true equivalent of that
numbers in Git is SHA-1. ~N-syntax is *alternative*, which is useful
when you think in relative terms, and it is rarely used with for large
N. Second, deficiency of other SCMs is not a good enough reason for Git
to impose the same restriction on its users.

Besides, I don't know about Bzr, but SVN CLI is insane. If you need to
do something simple, like compare your working directory with some tag,
you end up typing:

 $ svn diff --old=A_VERY_LONG_URL/tags/tagname --new=.

with Git you can do that as simple as

 $ git diff tagname

Before SVN 1.4, there was no option to show the change made by some
revision, so you had to type: svn diff -r PREV_REV:REV. One would think
that after they added '-c' in SVN 1.4, no one needs to do that manually,
but this option does not work in one of most common case:

 $ svn diff -c HEAD
 svn: Non-numeric change argument given to -c

so you need to figure out what is the number of the HEAD manually, and
only then you can use 'svn diff -c'.

With git, you can do that easily:
 $ git show


Also, using 'svn switch' to switch between branches is slow and painful
as hell. First, you have to type A_VERY_LONG_URL and if you happen to
forgot to check in some changes, you end up with completely mess in your
working directory. 'git checkout' has much more consistent behavior, and
it does not destroy your work...


So, IMNSHO, recent versions of Git is way easier to use than SVN even
in those cases where SVN provides similar functionality...



Dmitry