#pragma section-numbers 2
= Hg-Github Extension =

Extension to allow mirroring Mercurial repositories inside Bitbucket to Github.

<<TableOfContents>>

== Status ==

'''This extension is not distributed with Mercurial.'''

''Author: Stephen !McDonald''

Repository: https://github.com/stephenmcd/hg-github

== Overview ==

hg-github is a Mercurial extension that wraps hg-git, and supports a work-flow where
repositories are hosted on Bitbucket and mirrored on GitHub. This work-flow normally
requires adding Git paths to each repository's config file, and creating Mercurial
bookmarks pointing to the GitHub repository's branch name. The hg-github extension
takes care of these for you automatically.

== Configuration ==
The easiest way to install hg-github is directly from [[https://pypi.python.org/pypi|PyPi]]
using ''pip'' or ''setuptools'' by running the respective command below:

{{{
$ pip install -U hg-github
}}}
or:
{{{
$ easy_install -U hg-github
}}}

Otherwise you can download hg-github and install it directly from source:
{{{
$ python setup.py install
}}}

Once installed, add `hggithub` to the extensions section in your global ''`.hgrc`'' file:
{{{
[extensions]
hggithub =
}}}
Note that there isn't a dash in hggithub in your ''`.hgrc`'' file. The hg-git extension does
not need to be installed, as it is wrapped and used automatically by hg-github.

=== Repository Paths ===
As mentioned above, the GitHub path is given the name github when the default remote
location is on Bitbucket. For other named Bitbucket locations, the name `github-NAME`
is given, where ''NAME'' is the name of the path located on Bitbucket. For example,
consider the following ''`.hg/hgrc`'' repo config:
{{{
[paths]
default = ssh://hg@bitbucket.org/stephenmcd/hg-git
somefork = ssh://hg@bitbucket.org/stephenmcd/hg-git-temp
}}}

hg-git will add entries to the config file as follows. Note that the config file
isn't actually written to:
{{{
[paths]
default = ssh://hg@bitbucket.org/stephenmcd/hg-github
somefork = ssh://hg@bitbucket.org/stephenmcd/hg-github-temp

github = git+ssh://git@github.com/stephenmcd/hg-github.git
github-somefork = git+ssh://git@github.com/stephenmcd/hg-github-temp.git
}}}

=== GitHub Username ===
hg-github assumes you have the same username on GitHub and Bitbucket. If you
have a different GitHub username, you can specify it by adding the following
section to your global ''`.hgrc`'' file:
{{{
[github]
username = stephenmcd
}}}
== Usage ==
Once installed, assuming the default remote location of your repository is on
Bitbucket, the GitHub path is automatically added and given the name `github`,
so you can push to it with the following command:
{{{
$ hg push github
}}}

== See also ==
 * HgGit extension
----
CategoryExtensionsByOthers