Using Bitbucket

(If you haven't read the introduction, "Getting started with Mercurial", we suggest you do so now.)

Getting started with Bitbucket

Starting a new project or importing your current project into Bitbucket is easy! If you haven't already, you can create a fresh repository on the "Create repository" page, which is also accessible from your personal home page.

We will assume that you have created a new repository named testrepo and begin from scratch. If you already have a code base you want to import, skip ahead to the section "Importing existing files".

The first thing you should do is clone the repository from us. This gets you a local copy of the entire repository, including all changes, but that won't matter much since the repository you have just created is empty.

$ hg clone http://bitbucket.org/jespern/testrepo
destination directory: testrepo
no changes found
updating working directory
0 files updated, 0 files merged, 0 files removed, 0 files unresolved

You now have an exact copy of what we had on our end. This means that you are ready to start work!

Lets add a few files:

$ cd testrepo
$ echo 'Hey this is a file I am about to add' > README
$ echo 'This is some other file.' > textfile.txt
$ ls
README    textfile.txt
$ hg add README textfile.txt
$ hg commit -m "Adding initial README file, as well as a file with text in it"

OK, hg is now tracking both README and textfile.txt, and has recorded their changes. Here comes the fun part, let's publish it:

$ hg push
pushing to http://bitbucket.org/jespern/testrepo
searching for changes
http authorization required
realm: Bitbucket.org HTTP
user: <your username>
password: <your password>
adding changesets
adding manifests
adding file changes
added 1 changesets with 2 changes to 2 files

...and our changes are published. We comitted 1 changeset, which held 2 changes to 2 files. Makes sense? Great!

Importing existing files

Chances are you are either coming from a different version control system such as Subversion or CVS, and you want to get started using Mercurial instead. Luckily, you can push anything into an empty repository. This allows you to easily move any number of files into your new repository at Bitbucket.

Let's say I have a project in ~/Work/Blonk, and I want to add it to Bitbucket. The first thing to do is create a new empty repository via the "Create repository" page. Again, we will assume that this repository is named blonk and is to be found on http://bitbucket.org/jespern/blonk.

First, we will make a local copy, by cloning it:

$ hg clone http://bitbucket.org/jespern/blonk
destination directory: blonk
no changes found
updating working directory
0 files updated, 0 files merged, 0 files removed, 0 files unresolved

Now let's enter the directory, and copy all of our previous work in:

$ cd blonk
$ cp -R ~/Work/Blonk/* .

Now all that remains is to add and commit the files:

$ hg add
$ hg ci -m "Initial import of the old Blonk files"

And we can go ahead and push:

$ hg push
pushing to http://bitbucket.org/jespern/blonk
searching for changes
http authorization required
realm: Bitbucket.org HTTP
user: <your username>
password: <your password>
adding changesets
adding manifests
adding file changes
added 1 changesets with 162 changes to 162 files

We're done. You may now browse to the repository online and see your files appear.

Importing existing files already in Mercurial

You may also have an existing Mercurial repository locally, and want to import it to Bitbucket directly. Thankfully this is extremely easy. Again, the first thing to do is create a new empty repository via the "Create repository" page. We will assume that this repository is named blonk and is to be found on http://bitbucket.org/jespern/blonk.

Now, just push to it:

$ cd ~/Work/blonk # our existing hg repository
$ hg push http://bitbucket.org/jespern/blonk
...

Done!

You can edit .hg/hgrc in your repository to include the default path to Bitbucket:

$ cat .hg/hgrc
[paths]
default = http://bitbucket.org/jespern/blonk

Now you can simply enter hg push and hg pull without having to specify the full URL.

Continuing on from here

You now know how to create a new repository, and either work with it from scratch, or import pre-existing files. Of course, you are going to want to make changes to those files now.

The workflow remains the same:

• To add files to the repository, you hg add
• To commit changes, you hg commit
• To publish your changes, you hg push

If you have several people in your team, be sure to read our article on "How to use Bitbucket for collaboration".