= mercurial-ruby

Ruby API for Mercurial DVCS. Uses command line interface to communicate with Mercurial repositories.

== Documentation

Please refer to YARD documentation here:

http://rubydoc.info/gems/mercurial-ruby/file/README.rdoc

Github doesn't support some YARd-specific syntax so this README can look broken.

== Installation

 gem install mercurial-ruby
 
== Compatibility

Tested with Mercurial versions 1.9, 1.9.1 and 2.1; Ruby version 1.8.7.

== Configuration

There are several settings you can configure. Do it like this:

 Mercurial.configure do |conf|
   conf.hg_binary_path = "/usr/bin/hg"
 end
 
See {Mercurial::Configuration Configuration} class for details.
 
== Usage

All actions are performed through {Mercurial::Repository Repository} object.
So before you can start doing anything you need to initialize one. Either by creating a new repository:

 repository = Mercurial::Repository.create("/path/to/new_repository")

or opening an existing one:

 repository = Mercurial::Repository.open("/path/to/existing_repository")
 
Now feel free to invoke various methods to get changesets, branches, nodes, etc:

 repository.commits.by_hash_ids('291a498f04e9', '63f70b2314ed')
 repository.branches.all
 repository.hooks.by_name('commit')
 ...
 
See Features section below for a full list of entities and their methods.
 
== Features

=== Mercurial Entities

* {Mercurial::Commit Commits}
* {Mercurial::Node Nodes} — files and directories
* {Mercurial::Branch Branches}
* {Mercurial::Tag Tags}
* {Mercurial::Diff Diffs}
* {Mercurial::Manifest Manifest}
* {Mercurial::FileIndex File Index}
* {Mercurial::ConfigFile Repository config} — hooks and various settings

=== Built-in Caching

There's a simple caching mechanism built into the gem. If you pass Rails CacheStore compatible
caching store to the Configuration block, mercurial-ruby will cache output of all hg commands
it's executing. Then if you execute same method again and it will run the same command,
the gem will return the output from cache.

Here's how you configure it:

 Mercurial.configure do |conf|
   conf.cache_store = Rails.cache
 end
 
The gem is using a single method of the CacheStore called +fetch+.
Cache expires automatically when repository's mtime changes, and it's your job to update it.

== Contributing to mercurial-ruby
 
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
* Fork the project
* Start a feature/bugfix branch
* Commit and push until you are happy with your contribution
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2012 Ilya Sabanin. See LICENSE.txt for
further details.