Bitbucket, EasyMercurial and Version Control

Update: The following tutorial details how we will manage our code. This includes both applied scripts and tutorial work.

Version Control is used with Archaeopy to allow multiple users to modify and contribute source code. The method chosen is Mercurial due to its simplicity and the availability of free hosting for academic users.

A large number of software packages exist to manage Mercurial Repository's and the easiest to get to grips with is EasyMercurial. We recommend downloading and installing EasyMecurial when you download and install Anaconda.

Notes and a presentation from a lecture I attended on using easyMercurial are available here. I'd recommend following the recipe example.

ArchaeoPY source code is hosted at Bitbucket; although you'll need to request access to the repository using this link (you will need to register and log into WordPress).

Once you've got access to ArchaeoPY on Bitbucket you can download the ArchaeoPy repository using the following steps:

1. Download the Repository:

To access the repository from your computer, log into Bitbucket and navigate to the ArchaeoPy repository. Copy the URL from the right-hand side of the screen (in the box next to HTTPS):

bitbucket url

2. Load EasyMercurial: 

 Go to File -> Open. Remote Repository. Paste the URL you have just coped into the URL box. You can specify where this repository is downloaded to on your computer through the Folder box.

Downloading Repository

You will be asked to log-in. Simply enter your Bitbucket account details.

Autho

Add Files to Repository

You are now able to access the ArchaeoPy repository through you computer! To add files to the repository, you can simply save or copy and paste them into the folder directory where you have downloaded the repository to.

Folders Repository

EasyMercurial keeps track of any changes, additions and deletions from the file system but doesn't automatically add or delete items from version control.

To add new scripts into version control click on the My Work tab and select the file(s) you want to track. Then click Add on the bottom left hand toolbar.

New File

These Files will then move into the Added window.

Add to Repository

Commit Changes

Once you've made all the changes you want, to click commit. This creates a snapshot of the repository at that moment in time and allows you to enter comments. I recommend committing frequently (at least once per session) to ensure you don't accidentally delete code you've got working.

Commit

After committing, you'll see your commit added to the Repository History.

After Commit

Sharing your changes with the world

One of the benefits of Version Control is it's easy to add your changes into the online ArchaeoPy repository. After committing your changes, click Push in the top toolbar and, after logging in, your changes will be added to the group Bitbucket. Similarly to obtain the latest repository and see other peoples changes click Pull.

Rolling back to a previous version

Should you make a change to some code that breaks it, or if you just want to see how you did something in the past you can roll back your local repository to a previous version.

Simply right click on the commit you want to view and select 'Update to this revison'. The version currently being used has a 'Star' in the upper right side.

Roll Back Repository