Source

VersionControl_Hg / Trunk / Documentation / Tutorials / src / en / Instantiating.txt

The default branch has multiple heads

Full commit
% Tutorial: Instantiating VersionControl_Hg
% Michael Gatto <mgatto@lisantra.com>
% June 20, 2011

Tutorial: Instantiating VersionControl_Hg
=========================================

The basis of all operations is instantiating the base class:

~~~{.php .numberLines}
require_once 'VersionControl/Hg.php';
$hg = new VersionControl_Hg('/path/to/repository');
~~~

The path to a repository is currently only tested with local repositories. It
may "just work" with a url, however. I have not yet decided on the security
and privacy implications for providing access to remote repositories, even
public ones. Also, I have not yet formulated a way to handle automated,
server-side access to repositories over SSH or various authentication
methods provided by other software such as Bitbucket or mercurial-server.

Setting the repository also automatically finds and sets the local
path of the Mercurial binary it will use. If multiple installations of
Mercurial are found, this package will employ only the first one found on the
system path.

Not setting a repository path while instantiating is fine. For commands such
as `hg init` or `hg clone`, a blank argument simply makes the most sense.
If you do supply a path and then attempt to init or clone a repository over it,
the underlying Mercurial command-line client will return an error, resulting
in a PHP exception. This is because the CLI will not allow a user to clone
over or init over an existing repository.

In this case, the to() method will supply the path (which must be an empty
directory) to which to create or clone a repository:

~~~{.php .numberLines}
require_once 'VersionControl/Hg.php';
$hg = new VersionControl_Hg();
$hg->clone('/path/to/repo')->to('/path/to/future/repo')->run();
~~~

You may also provide a location of a repository after instantiation:

~~~{.php .numberLines}
require_once 'VersionControl/Hg.php';
$hg = new VersionControl_Hg();
$hg->setRepository('/path/to/repository');
~~~

or

~~~{.php}
$hg->repository = '/path/to/repository';
~~~

Calling all commands other than 'version' without having already set a
valid repository will raise an exception.

Do note that you can only set the path once since Repository is a singleton;
All subsequent attempts will *silently* fail after the path has already been
set.