Finishing relative svn:externals

I'm picking up feature to support relative URLs in svn:externals:

http://subversion.tigris.org/issues/show_bug.cgi?id=1336

I would like to get this into 1.5 if possible. The main thing holding
it up is consensus on the relative URLs that we will support and their
representations. There's been a large amount of discussion on this, all
of it on what relative URLs will be allowed and the format of them. The
discussion stalled in January 2005.

Threads
=======

Links to threads:

http://subversion.tigris.org/issues/show_bug.cgi?id=1336
http://subversion.tigris.org/issues/show_bug.cgi?id=1829

Relative Externals - format debate
    http://svn.haxx.se/dev/archive-2005-01/0027.shtml

Relative externals - take 2
    http://svn.haxx.se/dev/archive-2005-01/0052.shtml

Final(?) Relative Externals format
    http://svn.haxx.se/dev/archive-2005-01/0929.shtml

Different relative URLs
=======================

This is the justification for each type of relative URL.

There are four locations in an absolute URL where you may want to
"anchor" a relative URL:

1) Relative to the current directory

    You never pull an external from a subdirectory where you are, you
    always go up, so relative URLs will always start with a ..

    This form works well if you have a trunk containing a number of
    projects and components and you want to share the components in
    the multiple projects. When you branch or trunk, the externals
    continue to work.

    This doesn't work well when you branch or tag and have externals
    to a project outside your trunk, since the number of directories
    you need to go up changes.

    This relative URL will never break if you move the repository.

2) Relative to the repository root

    You want to refer to a directory in the same repository by the root
    of the repository. With this relative URL to a directory outside
    the project's trunk, it will not break when you branch or tag.

    There is the potential to refer to external repositories that are
    in the same level as the repository using the .. past the repository
    root.

    This relative URL will never break if you move the repository.

3) Relative to the site root

    You have a svn server that hosts multiple repositories and the
    server is known by different names, say 'svn' inside a firewall,
    but 'svn-external' outside the firewall. Without this relative
    URL type, one set of clients, either inside or outside, will not
    be able to check out the externals.

    In a distributed environment with multiple repositories, you have
    read-only mirrors set up using svnsync, you would like the externals
    to different repositories on the same server to be pulled from the
    local mirror.

4) Scheme relative

    You have multiple servers and want to a different server using the
    same scheme as the scheme used to check out.

Representations
===============

The relative URL to the current directory is easy: ../ You don't have
externals to subdirectories, so these all start with ../.

The issue is with the remaining ones.

RFC 3986 Compliance
-------------------

One line of thought is that we should use RFC 3986 to guide our relative
URLs, which is the specification for absolute and relative URLs. The
main issue is if we should keep the Subversion relative URLs compliant
to RFC 3986.

http://www.ietf.org/rfc/rfc3986.txt

So the question is, what degree of non-compliance do we mind.

RFC 3986 specifies these two clearly:

    relative to site root
       /svn/repos/trunk
    relative to scheme
       //svn.collab.net/svn/repos/trunk

It appears that /// has the same meaning as /, that is the same scheme
and host, so we can't really use it for repository root relative names.
  There is precedence for using a new scheme, such as Mozilla's chrome
scheme, as pointed out by Brane:

    relative to repository root
       svn-root://branches/1.4.x

It appears that while the URL is an "absolute" URL since it has an
explicit scheme, it does not have to mean absolute in the server's URL
space, so it can be relative to the repository root.

However, if we extend relative URLs to the command line, then using a
new scheme will require custom checking for the special svn-root scheme.

My proposal is to introduce the ^ as the repository root character, as
suggested by the regex anchor character, so

    ^branches/1.4.x

would point to the http://svn.collab.net/svn/repos/branches/1.4.x

While RFC 2396 is now obsolete, there is this section:

    Other characters are excluded because gateways and other transport
    agents are known to sometimes modify such characters, or they are
    used as delimiters.

    unwise = "{" | "}" | "|" | "\" | "^" | "[" | "]" | "`"

    Data corresponding to excluded characters must be escaped in order to
    be properly represented within a URI.

So people aren't likely coding this into URLs. Also, if we extend
relative URLs to the command line interface, then ^ doesn't appear to
interact poorly with the Unix shells using it with a leading space, from
my quick tests. I haven't tried Windows yet.

RFC 3986 Non-Compliance
-----------------------

I don't see the scheme relative URL as being as important, so you could
make that one be non-standard and use // for the repository root.

    relative to repository root
       //branches/1.4.x
    relative to scheme
       ://svn.collab.net/svn/repos/trunk (not a legal URL)

However, // is used by svk, so it's not clear how that would interact.

Rebuttal to Fitz's -0.9 on repository root relative URLs
========================================================

This is my rebuttal to Fitz's -0.9 on repository root relative URLs. He
would rather see server root than repository root URLs:

http://svn.haxx.se/dev/archive-2005-01/0959.shtml
http://svn.haxx.se/dev/archive-2005-01/0978.shtml

If I had to prioritize, I would rather see repository root relative URLs
than server rooted ones, but would like to have both.

Reasons to implement them:

1) I don't want people using directory relative URLs to get repository
    root URLs, say using ../../../../../branches/1.4.x.

2) It should be possible to use externals to have multiple projects,
    each with their own trunk, that share a common set of libraries
    outside the trunk, where the libraries are at a known location
    under the repository root. Branching or tagging the project
    would break externals.

3) It should be possible to have externals that never break, even
    if the repository is moved.

4) With mirroring of Subversion repositories to remote facilities,
    using svnsync, it should be possible to have the externals
    check out.

These reasons combined together, in a more complicated network setup,
you would want them.

Proposal
========

1) Be as RFC 3986 compliant as we can.

2) The relative URLs are:

    relative to current directory
       ../../branches/1.4.x
    relative to repository root
       ^branches/1.4.x
    relative to server root
       /svn/repos/branches/1.4.x
    relative to scheme
       //svn.collab.net/svn/repos/branches/1.4.x

Unspecified behavior is how far up ..'s go in relative to the current
directory URLs.

Regards,
Blair

-- 
Blair Zajac, Ph.D.
Subversion training, consulting and support
http://www.orcaware.com/svn/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org