Proposal for "VersionControl_Hg"

» Metadata » Status
  • Category: Version Control
  • Proposer: Michael Gatto 
  • License: MIT License
  • Status: Proposed
» Description

VersionControl_Hg is a PEAR PHP wrapper for the Mercurial version control system. The API interface is designed to be fluid with chainable methods:

include 'VersionControl/Hg.php';

$hg = new VersionControl_Hg('/path/to/repository');
$unformatted_text_log = $hg->log()->after('Dec 27, 2010')->excluding('**.xml')->format('raw')->run();

All mercurial commands are represented by a base method in this package:

hg log = $hg->log()->run();

However, there is not an exact 1-to-1 corresponence between Mercurial option names and chained helper methods. Instead, I have chosen to use full, semantic method names to make it clear how the option should modify the command. I have used Mercurial long-option names wherever they make sense, but modified them to better fit into the fluid interface.

The initial use case is to make a useful interface to Mercurial for Phing and other deployment & build systems. Eventually, I plan to support all Mercurial commands.

A Mercurial installation is required. Either the stock CLI client or TortoiseHg, which includes the CLI client. VersionControl_Hg is smart enough to search the Path to find a viable Mercurial executable. Platform independence is a primary design goal.

Code, build script, and documentation is available at: https://bitbucket.org/mgatto/versioncontrol_hg/overview

» Dependencies » Links
  • PHP >= 5.2.0
  • PHP Extensions: pcre, json, SimpleXML, date
  • Mercurial command-line client, or TortoiseHg installed
» Timeline » Changelog
  • First Draft: 2011-06-20
  • Proposal: 2011-06-27