[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Usability issue : "svn switch --relocate" should become "svn switch --relocation"

From: Michel Nolard <michel.nolard_at_gmail.com>
Date: 2005-06-03 23:04:32 CEST

Hi everybody !

I am using svn for quite some time now and I find it very professional. Here
is my little touch to help you improve it. This is a very little usability
issue which can be corrected by improving naming consistency.

Now, I'll explain the problem and propose a solution with respect to the users
who already know svn and for the newcomers also.

The problem is very easy to understand and I found it while using svn.
Interface consistency is very important as it helps users to avoid losing
time by seeking how a command is formated as they know how the other are.
This relies in part upon grammar. The problem we face here concerns the
"--relocate" option of "svn switch".

When you type "svn switch", you mean "svn, let's switch" so switch it is
logical for "switch" to be a verb. Svn is very consistent in this regard as
all svn commands are verbs. Now, let's compare the "--relocate" with the rest
of "svn help switch" :

---------8<---------------8<---------------8<---------------8<------
switch (sw): Update the working copy to a different URL.
usage: 1. switch URL [PATH]
       2. switch --relocate FROM TO [PATH...]

  1. Update the working copy to mirror a new URL within the repository.
     This behaviour is similar to 'svn update', and is the way to
     move a working copy to a branch or tag within the same repository.

  2. Rewrite working copy URL metadata to reflect a syntactic change only.
     This is used when repository's root URL changes (such as a schema
     or hostname change) but your working copy still reflects the same
     directory within the same repository.

Valid options:
  -r [--revision] arg : ARG (some commands also take ARG1:ARG2 range)
                             A revision argument can be one of:
                                NUMBER revision number
                                "{" DATE "}" revision at start of the date
                                "HEAD" latest in repository
                                "BASE" base rev of item's working copy
                                "COMMITTED" last commit at or before BASE
                                "PREV" revision just before COMMITTED
  -N [--non-recursive] : operate on single directory only
  -q [--quiet] : print as little as possible
  --diff3-cmd arg : use ARG as merge command
  --relocate : relocate via URL-rewriting
  --username arg : specify a username ARG
  --password arg : specify a password ARG
  --no-auth-cache : do not cache authentication tokens
  --non-interactive : do no interactive prompting
  --config-dir arg : read user configuration files from directory ARG
---------8<---------------8<---------------8<---------------8<------

As you can see, apart "--relocate", all the other options are nouns or
adjectives+nouns. This is very intuitive as we build our sentence like this :
 subject + verb [+ adjective] + noun
which becomes, in the case of svn :
 svn command --option --small-option

So, to improve svn consistency, I propose to replace "--relocate" by a noun.
As I am not a native english speaker, I am not sure that "relocation" is
really what we need, but this is my proposition to improve the consistency of
Subversions Command Line Interface (CLI).

I propose that
 - the "--relocate" option is still supported silently, aside the new
"--relocation" until subversion 2.x where, maybe, we can deprecate or remove
it.
 - the svn documentation ("svn help switch" and svn book) reads "--relocation"
instead of "--relocate" to help the newcomers to adapt to the new, more
consistent option's name

What do you think of this ?

I hope this helps svn to become more usable :)

-- 
Michel Nolard

  • application/pgp-signature attachment: stored
Received on Sat Jun 4 00:50:05 2005

This is an archived mail posted to the Subversion Users mailing list.