Use git to collaboratively work on bibliographic collections

Home \ Documentation \ Use git to collaboratively work on bibliographic collections

Problem

Managing collections of bibliographic references is something that all people trying to learn anything need to do, whether it is a simple list of bookmarks in a web browser, a file with some notes in it, or something more formal like a bibtex or bibjson file. In order to store and share those files with others, whilst making and tracking changes, some form of shared version control system is required.

Solution – distributed version control systems

Luckily, these already exist – they were created for software development projects. So let’s use one to manage some files. There are various types of distributed version control systems available, and for this example we are going to use git. It is possible to install and run git yourself, on your own computer, or on a shared server – but we don’t even need to worry about the complexities of sharing our service, because http://github.com does it for us.

Viewing a repository

Viewing the content of a github repository is easy – just go to the URL of the repository, which in this case is at http://github.com/cottagelabs/bibliofiles. There you can see all the files and folders in the repository (which at the time of writing is just one file called README). Clicking on the name of a file will show you the file in the browser, but you can also get at the file directly, which is nice.

You can get at the file directly from the browser version by clicking the “raw” link.

Getting an account

sign up to github. You can start creating your own repositories if you want, but I have already made one for this project. So, email me with your github account name, and I will assign read and write privileges for you on the account I have set up.

Setting your public key

You should have a public key assigned to your account, so that you can authenticate when you want to edit files. When logged in, go to “ssh public keys” in “account admin” – https://github.com/account/ssh. Follow the instructions, and view the “help with public keys” section if necessary.

Editing files

Once you have permissions, you can edit files directly in the browser on the github website – for example, click the “edit” button when viewing the README file.

But the real purpose of git is that you can pull the files down to your local computer, make changes, and push them back up. You do this using git directly from your own PC.

To do this from a linux command line:




install git



sudo apt-get install git



copy the repository to a local folder



git clone git@github.com:CottageLabs/bibliofiles.git



enter the directory



cd bibliofiles



edit files as you see fit



NOTE: if you create new files in the repo, you must tell git about them



git add .



update the status of your local repository version by doing



a commit, and include a message explaining your recent changes



git commit -a -m 'some explanatory message'



check if there are any changes on the remote repository



you can do this any time to update your copy with other peoples changes



git pull



push your local changes back to the repository to share them with



other people. do this regularly



git push origin master

Things get more complicated when other people are making lots of changes – you may find there are conflicts. Then it is time to learn about merging… http://book.git-scm.com/3_basic_branching_and_merging.html

Doing this with windows

There will be some way to do this on a Windows machine, but I do not have the details. But here are some links I have found about the subject:

The advantages

By doing this, we can share updates to files. We will also have a revision history and remote storage. Plus, we can use a raw file from within the repository on github as the source for a bibserver collection!

An Open Knowledge Foundation Site