Updating documentation on a Bitbucket wiki

Bitbucket is a code hosting service. People sign up for an online repository, then share and contribute code using either Mercurial or Git. (Both are DVCSes, or distributed version control systems). When you get your repo, you also get a wiki. This week, I needed to update some documentation that was hosted on a Bitbucket wiki. It was fun! Here’s how it went.

As far as Bitbucket is concerned, a wiki is just another repository. I needed to update the wiki for Charles Miller’s Confluence JSON-RPC API plugin:
Bitbucket supports both Mercurial and Git. In this case, the repository uses Mercurial (hg).

I have used Bitbucket before, so I had already installed Mercurial and set up my configuration file. (The Bitbucket 101 guide explains how to do that.)

So all I needed to do was:

  • Get a copy of the wiki documentation, by cloning the Bitbucket wiki repository.
  • Make the updates in my local copy.
  • Push the updates up to the online repository in Bitbucket.

The details

I’m using a Windows computer. These are the steps I followed.

1) Create a directory on my computer where I want to store the Bitbucket repository. This is what I called the directory:


2) Open a Windows command window and go to the new directory:

cd \atlassian\bitbucketrepos\json-rpc-docs

3) Enter a Mercurial command to clone the Bitbucket repository that contains the documentation. This puts a copy of the repo onto my computer:

hg clone http://bitbucket.org/cmiller_atlassian/confluence-json-rpc-plugin/wiki

Here’s what it looked like in my command window:

C:\Atlassian\BitbucketRepos\JSON-RPC-docs>hg clone http://bitbucket.org/cmiller_atlassian/confluence-json-rpc-plugin/wiki
real URL is https://bitbucket.org/cmiller_atlassian/confluence-json-rpc-plugin/wiki
destination directory: wiki
requesting all changes
adding changesets
adding manifests
adding file changes
added 13 changesets with 13 changes to 2 files
updating to branch default
2 files updated, 0 files merged, 0 files removed, 0 files unresolved

4) Open a text editor and edit the file that contains the wiki page I need to change.

The wiki pages are normal files, with the .wiki extension. You can edit them locally, as well as creating new ones.

This is what my directory looks like in Windows Explorer, with the “Home.wiki” file open in Notepad++

The directory structure of the cloned wiki repository on my Windows computer

5) Make my changes to the text file.

Yaayyy! Wiki markup. It’s slightly different to the Confluence wiki markup that I’m used to. Bitbucket uses the Creole syntax.

This was a bit unnerving, because there is no preview in a text editor. I was facing the prospect of pushing the file to Bitbucket before I knew what it would look like.

Then I found this site, where you can enter Creole markup and see a live preview:

Magic! I pasted in the content of my updated file and checked the results. All good.

6) Save the text file.

7) In my command window, go to the directory that contains my Mercurial repository. In this case, it’s the “wiki” directory:

cd wiki

8 ) Commit the changes to my local Mercurial repository, including a commit message:

hg commit -m “Linked to the documentation on the Atlassian Developers site for full instructions”

9) Push the changes to the online repository at Bitbucket:

hg push

It worked! Here is what I saw in my command window:

C:\Atlassian\BitbucketRepos\JSON-RPC-docs\wiki>hg push
real URL is https://bitbucket.org/cmiller_atlassian/confluence-json-rpc-plugin/wiki
pushing to http://bitbucket.org/cmiller_atlassian/confluence-json-rpc-plugin/wiki
searching for changes
http authorization required
realm: Bitbucket.org HTTP
user: sarahmaddox
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 1 changesets with 2 changes to 2 files

Here is the wiki page before my updates:

The Bitbucket wiki page before my updates

And after:

The wiki page after I had pushed my updates to Bitbucket

Here is the page history:

The page history

And yes, to the eagle eyed who spotted the number of files updated, I did update another wiki page at the same time. 😉

Here is the Bitbucket documentation on how to use the wiki.


About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 27 October 2011, in atlassian, technical writing, wiki and tagged , , , , , , . Bookmark the permalink. Leave a comment.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: