Exploring command-line relative url behavior and syntax

Apparently people like Karl Fogel and Julian Foad want a well thought out and
well reasoned design and implementation for relative url support, what's up with
that? :)

Ok so here I go. I'm taking off my potential/wanna-be Subversion dev hat and I
am putting on my simple Subversion user hat: What do I expect from the relative
url syntax?

== Which commands? ==
The first step is to determine which commands the syntax applies to and which
commands present a potentially confusing situation. Here I'll divide them up
based on whether URLs are valid arguments for the command, and if so whether
URLs pointing to different repositories is supported.

Working Copy Only
-----------------------
add
changelist
cleanup
commit
resolved
revert
status
update

Single Repository URLs
-----------------------
log
lock
unlock
copy
delete
diff
export
import
merge
mkdir
move
propget
propset
propdel
propedit
proplist
switch

Multi-Repository URLs
-----------------------
blame (praise, annotate, ann)
cat
info
list
checkout
mergeinfo

== What does '^/' mean? ==

For the first case, subcommands that operate on working copy paths only, the
answer is simple. '^/' means an error. Any URL, absolute or relative, is not
valid for this case.

The second case, subcommands that operate on urls from only one repository at
time, is almost as easy. '^/' refers to the One True Repository. If
there are other arguments to one of these commands, then you expect '^/' to
represent the root url of the repository represented by the other arguments,
else if you are in some working copy it should be that repository root url.

The third case is the tricky one, what does '^/' mean in a command that can
contain URLs spanning N different repositories? Here is really where we need
to flesh out all the different scenarios to determine what makes the most
sense.

1. One relative url, one (or more) "other" arguments:
   - In a working copy of 'file:///repo/trunk' you want the info for
'index.html'
     and a related file off some branch 'file:///repo/branches/a/index.html':

     [~/wc/repo_trunk]# svn info index.html ^/branches/a/index.html

     It doesn't matter whether you use the "other arguments" (index.html) or
     the current working directory to get the root url, they will be the same
     here.

   - In a working copy of 'file:///repo/trunk' you want the info for
     'file:///repo/branches/a/index.html' and a similar file in a different
     repo 'file:///repo1/trunk/index.html':

     [~/wc/repo_trunk]# svn info ^/branches/a/index.html
file:///repo1/trunk/index.html

     Should this do what I described, or should the root url be to 'repo1'?
     It does seem a little intuitive to look to URLs provided *before* the
     relative url for a root URL, and if none are available use the working
     copy. But that would mean:

     [~/wc/repo_trunk]# svn info ^/branches/a/index.html
file:///repo1/trunk/index.html
     [~/wc/repo_trunk]# svn info file:///repo1/trunk/index.html
^/branches/a/index.html

     Mean two different things. That could be kind of confusing. Especially
     if you consider the third case coming up...

   - This time you are *not* in any Subversion working copy and you issue:

     [/]# svn info ^/branches/a/index.html file:///repo1/trunk/index.html

     The only choices here are to error or use the second argument's url with
     the expectation probably being to use the second argument's url. But
     this breaks the "use preceding" arguments algorithm.

2. One relative url, two other arguments, pointing to different repos:
   - [~/wc/repo_trunk]# svn info file:///repo/trunk/index.html
^/branches/a/index.html \
                        file:///repo1/branches/a/index.html

     I think the expecation here would be that '^/' points to 'file:///repo'
     because you are in a 'repo' working copy and your first argument is also
     from 'repo'.

   - [~/wc/repo_trunk]# svn info file:///repo1/trunk/index.html
^/branches/a/index.html \
                        file:///repo/branches/a/index.html

     This case is a little more interesting. You are in a 'repo' working copy,
     and one of the arguments also points to 'repo'. Yet a 'repo1' URL was
     before the relative url. I guess as you are typing along you would expect
     '^/' to match what you were just typing (a repo1 URL), not what you are
     about to type, or where you are (in a repo wc).

   - [~/wc/repo_trunk]# svn info file:///repo1/trunk/index.html
file:///repo/trunk/index.html \
                        ^/branches/a/index.html

     You typed a 'repo' url just before typing '^/' AND you are in a 'repo'
     working copy, so you'd probably expect '^/' to be 'file:///repo'.

   - [~/wc/repo_trunk]# svn info file:///repo/branches/a/index.html
file:///repo1/trunk/index.html \
                        ^/branches/a/index.html

     A little less straight-forward, but having just typed the 'repo1' URL,
     you'd probably expect '^/' to point to 'repo1', despite being in a 'repo'
     working copy.

3. Two relative urls, two (or more) other arguments, pointing to
different repos:
   - [~/wc/repo_trunk]# svn info file:///repo/trunk/index.html
^/branches/a/index.html \
                        file:///repo1/trunk/index.html ^/branches/a/index.html

     Now it get even more interesting. I suspect that as you are typing this
     you probably intend for the first relative url to point to 'repo' and the
     second to 'repo1'. But now you have two arguments that are identical on
     the command-line, resolving to two completely different things. Of course
     this is a very synthesized example and it would be unlikely to have
     multiple arguments be this similar.

   - [~/wc/repo_trunk]# svn info ^/branches/a/index.html
file:///repo1/trunk/index.html \
                        file:///repo/trunk/index.html ^/branches/a/index.html

    Looking at the command-line you might well associate the first relative url
    to 'repo1' since the 'repo1' url is the closest to it. However, typing it
    out you would probably intend it to be relative to the root url of your
    working directory, 'file:///repo'. The second url would certainly be
    associated with 'file:///repo'.

Are there any use cases that I didn't cover that are important?

== Solutions ==
I really think that having a single consistant behavior that applys to all
subcommands is essential to making this functionality useful. It would get
very confusing quickly if different subcommands treated relative urls
differenctly. Here is a possible solution that I believe addresses the cases I
mentioned above.

- If the other arguments contain non-relative urls or working copy paths to a
  single repository, use the root url of that repository, else
- If the other arguments contain non-relative urls or working copy paths to
  more than one repository, then use the first non-relative url or
path preceding
  the relative url to get the root url else
- If the current directory is a working copy, use it to generate the root url,
    else
- Error, nothing to substitute '^/' with.

My only concern is that it might be a bit complicated/long-winded to explain.
Comments?

Troy

-- 
"Beware of spyware. If you can, use the Firefox browser." - USA Today
Download now at http://getfirefox.com
Registered Linux User #354814 ( http://counter.li.org/)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org