= !BitBucket

[[Image(bitbucket_logo.png, align=right)]]

[http://bitbucket.org/ BitBucket] is a Mercurial repository hosting service with a project view similar to Trac in spirit. It is a proprietary licensed platform, and uses a cloud that is free for small teams with unlimited private and public repositories.

As they say:
 '''Develop code as a team. Keep all your development in one place, be it issue tracking, documentation or sharing code.'''

Lots of good stuff to steal there ;-)

Among other things, they use WikiCreole all over the place, the same way Trac uses its own Trac WikiFormatting everywhere.
Furthermore, the wiki is itself stored in a secondary Mercurial repository, much like described in TighterSubversionIntegration#Aprivaterepository.

Note that we maintain an official Mercurial mirror of the SubversionRepository there, see [http://bitbucket.org/edgewall/trac edgewall/trac].

== Basic Mercurial Setup

Obviously, you will need a Mercurial client:
- The "raw" command-line client can be downloaded here: https://www.mercurial-scm.org/
- A GUI client for Windows also exists, surprisingly named [http://tortoisehg.bitbucket.org/ TortoiseHG]

It is considered Good Practice to first get things working with command-line, before moving to GUI-based solutions.

Once the client is installed, some basic configuration is in order. Create the global configuration file, depending on your platform:
- On Windows XP and earlier: `C:\Documents and Settings\USERNAME\Mercurial.ini`
- On Windows Vista and newer: `C:\Users\USERNAME\Mercurial.ini`
- TODO: Other OS?

This configuration file is ini-style.
Important settings for working with the Trac BitBucket mirror:
{{{#!ini
[extensions]
convert =
eol =
graphlog = 
; See below concerning external extensions
hgsvnutils = /path/to/HgExts/HgSvnUtils/HgSvnUtils.py

[diff]
git = true
}}}

=== Mercurial Extensions

For details on the concept of extensions see https://www.mercurial-scm.org/wiki/UsingExtensions

An important external extension for Trac development with Mercurial is the [http://rc.c-space.org/hg/HgSvnUtils HgSvnUtils] extension (maintained by RemyBlank).

To install it, go to some local directory and run (from command-line)
{{{
hg clone http://rc.c-space.org/hg/HgSvnUtils
}}}
and then set the `hgsvnutils` option mentioned above to the checked-out location.

=== Working with BitBucket

Once you installed Mercurial command-line client, you can `hg clone http://bitbucket.org/edgewall/trac` (or any other public repository).

After creating an account and a repository (or Trac-fork), you will also be able to push & pull changes against the remote repository:
- Using `https://USERNAME@bitbucket.org/USERNAME/reponame` over SSL (built-in support in the Mercurial client); or
- Using `ssh://hg@bitbucket.org/USERNAME/reponame` over SSH (note that this uses `hg` as username!)[[BR]]
  For this you will need `ssh` client and SSH key-pair
  - See http://confluence.atlassian.com/display/BITBUCKET/Using+SSH+to+Access+your+Bitbucket+Repository for instructions
  - If you're on Linux, you probably already have `ssh` and keys, so good for you.
  - If you're on Windows, `ssh` is not native. You may obtain a `ssh` client for Windows (like `plink.exe`), but why bother, when you have the SSL option?