Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Mercurial Bitbucketize Extension

Project Description

Publish your next repo to bitbucket without clicking through the web interface. Also switch it easily from private to public (or back), set description, enable or disable wiki and issue tracker…

1   Synopsis

In simplest configuration extension works just as generic BitBucket client:

hg bitbucket_create acme-toolkit --wiki --private --forks=private

hg bitbucket_modify acme-toolkit --public -m "THE toolkit above all toolkits"

hg bitbucket_status acme-toolkit

hg bitbucket_delete acme-toolkit

hg bitbucket_goto acme-toolkit

Those commands operate on«USER»/acme-toolkit where «USER» is your BitBucket username (configured in extension configuration).

Paired with Path Pattern it can also deduce appropriate name for the current repository:

# Create private bitbucket clone of current repo
hg bitbucket_create
# ... or maybe public one
hg bitbucket_create --issues --public -l python -m "Webapp for"

hg bitbucket_status

hg bitbucket_modify --language=perl

hg bitbucket_goto --issues

hg bitbucket_delete

To save typing, all commands have shorter aliases (hg bb_create, hg bb_status, etc).

2   Enabling and configuring the extension

Install the extension as described below (see Installation section). Then enable it and configure a few crucial parameters by writing in ~/.hgrc:

mercurial_bitbucketize =

user = John
login =
path_alias = bitbucket

Here: user is your short BitBucket username (the name present in URLs of your repositories) and login is your Atlassian login (the username you enter while performing browser login),

The path_alias is optional and means, that in case such alias (here: bitbucket) is defined for current repository, it can be used to deduce the name of BitBucket repository to operate on. That works great if you install and enable Path Pattern and define appropriate pattern, for example:

mercurial_bitbucketize =
mercurial_path_pattern =

user = John
login =
path_alias = bitbucket

bitbucket.local = ~/devel/{below}
bitbucket.remote ={below:/=-}

(with such settings bitbucketize will know that ~/devel/libs/acme should be paired with on BitBucket).

It is also strongly recommended that you install Keyring to avoid being repeatably prompted for BitBucket password (bitbucketize happily uses Keyring to save password in secure storage).


In case you happen to issue hg pull bitbucket or hg push bitbucket over HTTP (instead of ssh), you will likely want to add:

bitbucket.prefix =
bitbucket.username =

Those settings are irrelevant from the Bitbucketize point of view, but one usually wants to keep them in sync with bitbucketize settings.

3   Commands

Standard help is available for all commands (hg help bitbucket_create, etc), check it out for detailed list of all options.

All commands have shorter aliases prefixed with bb_ (instead of hg bitbucket_modify you can type hg bb_modify).

3.1   Creating BitBucket repository (hg bitbucket_create)

Creates new repository on BitBucket. You can give the name:

hg bitbucket_create tinyapps-acme

(then the command is context-less) or rely on deduction:

hg bitbucket_create

(the latter depends on proper path_alias configuration).

By default repository is private, has no wiki, no issue tracker, and no description. Some of those can be specified, for example:

hg bb_create --wiki --issues --descr="My repo" --public


I usually prefer to create repository as private, push the code, verify README appearance, and later, when I am generally happy and ready for the release, switch to public.

The bitbucket_create command does not push the code (created repository is empty). This is done on purpose, to let you verify the name and settings before you push.

3.2   Toggling repository features (hg bitbucket_modify)

Use bitbucket_modify command to modify repository features.

It can be used to switch it to public:

hg bitbucket_modify --public

or back to private:

hg bitbucket_modify --private

and correct metadata:

hg bitbucket_modify --lang=Perl --descr="TIMTOWTDI"

Examples above operated on deduced repository. Of course specifying the name is also possible:

hg bitbucket_modify tinylibs-acme --public --wiki

Similarly toggle wiki and issues:

hg bitbucket_modify --wiki
hg bitbucket_modify --no-wiki
hg bitbucket_modify --issues
hg bitbucket_modify --no-issues


Disabling wiki or issue tracker is destructive, dangerous operation. At the moment there is no additional warning or prompt (I plan to add one in the future).

3.3   Checking repository status (hg bitbucket_status)

Use bitbucket_status command to check whether repository exists, and print it’s metadata:

hg bitbucket_status


hg bitbucket_status tinylibs-acme

3.4   Deleting the BitBucket clone (hg bitbucket_delete)

Use bitbucket_delete to remove BitBucket clone:

hg bitbucket_delete

or, to delete repository with specific name:

hg bitbucket_delete acme


This is irrecoverable operation. Even if you still have the code (and can push it back), there is no way to recover issues, wiki, downloads, or permissions.

Use this command to delete temporary ad hoc repos, for more serious removals consider web interface.

3.5   Visiting BitBucket web pages (hg bitbucket_goto)

Simple shortcut to open respository related web pages on BitBucket.

To visit overview:

hg bitbucket_goto tinylibs-acme

or (with name deduction):

hg bb_goto

To visit specific page:

hg bitbucket_goto tinylibs-acme --issues

or (with name deduction):

hg bb_goto -l

(see hg help bb_goto for list of all pages supported).

Default system browser is used (established according to various system-specific conventions). If that guess is incorrect, it can be configured in .hgrc. Either by something like:

type = firefox

where type is one of webbrowser supported values (firefox, chrome, safari, opera, konqueror, …) or:

command = /usr/bin/firefox

(the former is slightly preferable as it can give browser incentive to raise the window).

4   Installation

4.1   Linux/Unix

4.1.1   Installing from PyPi

To install for the first time, just:

pip install --user mercurial_bitbucketize

This should install both the extension itself, and all it’s dependencies. Of course other methods of installing Python packages work too (like sudo easy_install mercurial_bitbucketize).

Activate by writing in ~/.hgrc:

mercurial_bitbucketize =

To upgrade:

pip install --upgrade --user mercurial_bitbucketize

As I already said, it is strongly recommended that you install also Keyring and Path Pattern.

4.1.2   Installing for development

Clone the extension itself, and it’s dependencies (PyBitBucket and mercurial_extension_utils):

hg clone git+
# Or git clone

hg clone

hg clone

Update to newest tags if you prefer to work on stable versions.

Install them for development (dependencies first):

pip install --user --edit python-bitbucket
pip install --user --edit mercurial-extension_utils
pip install --user --edit mercurial-bitbucketize

Activate as usual:

mercurial_bitbucketize =

To upgrade just pull changes and update in appropriate repositories.

4.2   Windows

If you have Python installed, install necessary modules with pip, just like on Linux:

pip install --user mercurial_bitbucketize

As Mercurial (whether taken from TortoiseHg, or own package) uses it’s own bundled Python, you must activate by specifying the path:

mercurial_bitbucketize = C:/Python27/Lib/site-packages/
;; Or wherever pip installed it

Extension will take care of finding necessary modules.

If you don’t have Python, you may try the method described above in Installing for development, but I suspect you will face missing dependencies. So preferably install Python.

7   Development, bug reports, enhancement suggestions

Development is tracked on BitBucket, see

Use BitBucket issue tracker for bug reports and enhancement suggestions.

8   Known problems

Value error on repository creation

If hg bitbucket_create ends with:

ValueError: dictionary update sequence element #0 has length 1; 2 is required

you observe effect of recurring bug in pybitbucket.

Upgrading pybitbucket to version 0.6.1 or newer should resolve the problem.

If this is not feasible at the moment, you can also ignore the error (failure happens after repository was created, it’s only consequence is that you do not see the confirmation message). Use hg bitbucket_details to check whether repository state is correct.

9   Additional notes

Information about this extension is also available on Mercurial Wiki:

Check also other Mercurial extensions I wrote.

Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
mercurial_bitbucketize-0.9.0.tar.gz (16.5 kB) Copy SHA256 Checksum SHA256 Source May 18, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting