.. -*-restructuredtext-*-

============
hgsubversion
============

hgsubversion is an extension for Mercurial that allows using Mercurial
as a Subversion client.

At this point, hgsubversion is usable by users reasonably familiar with
Mercurial as a VCS. It's not recommended to dive into hgsubversion as an
introduction to Mercurial, since hgsubversion "bends the rules" a little
and violates some of the typical assumptions of early Mercurial users.

Installation
------------
You need to have Subversion installed with the SWIG Python bindings
from Subversion 1.5 or later. You need Mercurial 1.3 or later.

.. _mercurial: http://selenic.com/repo/hg
.. _mercurial-stable: http://selenic.com/repo/hg-stable
.. _crew: http://hg.intevation.org/mercurial/crew
.. _crew-stable: http://hg.intevation.org/mercurial/crew-stable

If you are unfamiliar with installing Mercurial extensions, please see
the UsingExtensions_ page in the Mercurial wiki. Look at the example
for specifying an absolute path near the bottom of the page. You want
to give the path to the top level of your clone of this repository.

.. _UsingExtensions: http://mercurial.selenic.com/wiki/UsingExtensions

Before using hgsubversion, I *strongly* encourage you to run the
automated tests. Just use nose_ if you have it (or ``easy_install
nose`` if you want it), or use ``python tests/run.py`` to run the
suite with the conventional test runner. Note that because I use nose,
there's a lot of stdout spew in the tests right now. The important
part is that all the tests pass.

.. _nose: http://code.google.com/p/python-nose/

Basic Use
-----------
Get a new clone of an svn server::

 $ hg clone <svn URI> [destination]

Real example::

 $ hg clone http://python-nose.googlecode.com/svn nose-hg

Note: there are two slightly different ways of cloning
repositories. The most common desire is to have all the
branches/tags/trunk from the svn repo, in which case you should clone
from one level above trunk (as in the example above.) If you instead
want to clone just a single directory rather than the complete
branches/tags/trunk structure of the repo, clone the specific
directory path. In the example above, to get *only* trunk, you would
clone `http://python-nose.googlecode.com/svn/trunk`.

Pull new revisions into an already-converted repo::

 $ hg pull

For more information, see ``hg help svn`` while in a converted repo.

Support for ``svn:externals``
-----------------------------
All ``svn:externals`` properties are serialized into a single
``.hgsvnexternals`` file having the following syntax::

  [.]
   common1 http://path/to/external/svn/repo1
   ...additional svn:externals properties lines...
  [dir2]
   common2 -r123 http://path/to/external/svn/repo2
   ...additional svn:externals properties lines...

A header line in brackets specifies the directory the property applies
to, where '.' indicates the project root directory. The property content
follows the header, **with every content line being prefixed by a single
space**. Note that the property lines have a format identical to
svn:externals properties as used in Subversion, and do not support the
hgsubversion extended svn+http:// URL format.

Issuing the command ``hg svn updateexternals`` with the
``.hgsvnexternals`` example above would fetch the latest revision of
repo1 into the subdirectory ./common1, and revision 123 of repo2 into
dir2/common2.  Note that ``.hgsvnexternals`` must be tracked by Mercurial
before this will work.  If ``.hgsvnexternals`` is created or changed, it
will not be pushed to the related Subversion repository, *but its
contents will be used to update ``svn:externals`` properties on the
related Subversion repository*.