Putting Your org Files Under Version Control.

The first step is to create a repository in the directory where you keep your org files:

cd ~/Documents/org
bzr init

If you are using git:

git init  

Now you need to add your org files to the repository. In the directory where you keep you org files:

bzr add *.org  

For git users:

git add *.org  

Once you have added your files to the repository you need to commit the changes to update the repository:

bzr commit -m "Imported sources."  

For git users:

git commit -a -m "Imported sources."  

Commit makes a snapshot of the working state of the files. You can choose to commit changes at any time. There are several Emacs packages, which will let you do this directly from Emacs. I also run a cron job which commits any changes automatically each evening. The shell script I use is:

#!/bin/sh
cd ~/Documents/org
bzr commit -m "automatic commit via cron."  

If you want to commit files selectively, rather than all uncommited files, you can specify the file names on the command line:

bzr commit -m "Made some changes." myfile.org another_file.org  

First create a local copy of your org files by making a branch. You can then continue working on your files locally and then use bzr or git to merge changes back to your main copy of org when required.

To create an initial working branch on your local computer:

bzr branch ~nfs/firewall/Documents/org ~/Documents/org  

For git users:

git clone ~nfs/firewall/Documents/org ~/Documents/org

This command creates a local branch on my notebook from the repository on my file server. Note that bzr and git will create the directory for the branch. If the directory already exists you will get an error.

The general format of the branch command is:

bzr branch location directory

bzr understands a wide variety of transport protocols, which you could use to create your initial branch:

You now have a complete copy of your org files from the file server and their version history in ~/Documents/org. You can simply fire up Emacs and work on the org files in that directory.

If you use git the syntax is very similar. This example uses ssh:

git clone url directory
git clone ssh://ian@mycomputer.co.uk/~/Documents/org ~/Documents/org

At any point you can commit your changes to the local repository using the commit command:

bzr commit -m "Committing changes made on my notebook."

When you return back home or to the office, you will probably want to update the copy of org on your local server from your notebook:

• First you need to commit any local changes that you have made.
• Next you need to use the push command to send your changes back to

the server. The basic command is:

bzr push  

If you don't specify a destination location the push is made to the branch that this branch originated from. If you are the only person working with your org files, the push should update your remote copy without requiring any further action. If there are any conflicts take a look at the bzr manual on Resolving Conflicts for more information on how to fix the conflicts.

Note that once the push has completed the it needs to be committed on the server to update your working tree:

cd ~/nfs/firewall/Documents/org
bzr commit -m "Merged changes from my notebook."  

Up to the point of committing the merge you can choose to throw away any changes by using the revert option in bzr.

Git uses the same command:

git push 

Unlike bzr, git will auto commit changes after a merge. If you don't like this behaviour use the –no-commit option to make it behave like bzr.

Once you have a local branch on your computer, you can update it from your server at any time using the following command:

bzr pull  

By default pull uses the location where you originally branched from. this will pull any changes from the remote location and merge them with your local copy.

The command with git is the same

git pull   

You can create a central repository on a USB stick. You might want to do this if you take files between your home and work computers and can't use the internet to synchronize your files because there is a firewall in the way.

There are some special considerations required when using a usb stick:

• You need to specify that you can used mixed case in filenames, or you will have problems creating names like HEAD with git. Note this is only a problem with usb sticks formatted as FAT or VFAT.

If you are using the gnome desktop fire up gconf-editor and navigate to system->storage->default\_options->vfat. Edit the key "mount_options" and change its value to [shortname=mixed,uid=].

This option is the default with recent versions of Ubuntu such as Intrepid.

Sometimes you might want to update your local branch from your central repository, rather than from your local server. One reason for wanting to do this is if you are away from home and your local computer's branch is quite out of date. If you automatically update your central repository daily from a cron script, the files on there should never be more than one day old, so if you have an Internet connection you can get a more recent version of your files from the central repository.

The pull command will do this, but you need to specify the location on the command line:

bzr pull sftp://myserver.co.uk/my_repo/org  

My org files are on my home server in a directory accessible via nfs. I can either load my files via an nfs share, or run Emacs in a terminal on the file server.

Update the files on my laptop before I leave:

cd ~/Documents/org
bzr pull

Launch Emacs using a different .emacs, which has its org configuration set to point to the files on my local hard disk, rather than the nfs share.

When I get back home I can update the files on my server by doing a

cd ~/Documents/org
bzr push  

Note that push updates the repository, but not the working copy of the files. To update the working copy on your server you need to run bzr update. Alternatively, you can use the Push and Update plugin from https://launchpad.net/bzr-push-and-update , which automates this process for you.

You can set up anacron to update the org files on your laptop when you startup, or shutdown which keeps the files on your local hard drive up to date in most circumstances.

If the files on my laptop aren't up to date, I can use bzr to pull a copy from my web server via my mobile phone. If I can't get a signal, or find a wifi hotspot, the files on my laptop shouldn't be more than 24 hrs out of date. I can just work on my local copy and merge the changes when I get back home.

While I was writing this tutorial I needed to move my data between my bzr repository and a git repository, so I could test out the various git commands. In the process I learnt quite a bit about moving data between bzr and git, which I thought I would record here in case someone finds it useful.

I find screencasts a good way of learning things. Unfortunately there don't seem to be any for bzr at the time of writing. However, there are several excellent ones for git:

• Linus Torvalds (author of git) on Git
• Randal Schwartz on Git
  Randal's screencast gives an excellent overview of git, without getting too bogged down in the details.
• Gitcasts
  Gitcasts are a series of short screencasts (approximately 5 mins), each covering a particular aspect of git.

Maybe a full versioning system is not what you're looking for and backups are enough. Greg Newman has a blog entry about backing up Org-mode files under Mac.