You know Git. You know GitHub and many other git-related tools. But do you know git-annex?

With git-annex you can create repositories on a local machine (one of which can be, say, a locally mounted Dropbox share) and then keep the files housed within in sync. It’s not the easiest method of doing this, but it’s one that offers some pretty great potential. Even better, unlike standard git, git-annex allows you to sync large files.

See: Cloud computing policy (Tech Pro Research)

I want to walk you through the steps of installing and using git-annex to sync two locations. There are a couple of ways to do this: with a GUI tool and from the command line. I’m going to demonstrate the command-line version here (I’ll demonstrate the GUI method in a future how-to). I’ll demonstrate on Ubuntu Server 18.04 and will sync a locally mounted Dropbox folder to a local folder on the server.

With that said, let’s get to work.


You can install git-annex with a single command. However, you want to first make sure you have git installed on the machine. So to install both, open a terminal and issue the following command:

sudo apt install git git-annex

The git-annex installation does pull down some 325 dependencies (depending on what you already have installed on your machine), so it can take a bit of time (dictated by the speed of your network). Once the installation completes, you’re ready to go.

SEE: 20 quick tips to make Linux networking easier (free TechRepublic PDF)

Creating a repository

As I mentioned, we’re going to sync a local folder with a locally mounted Dropbox folder. I’ll assume the Dropbox folder is in ~/Dropbox. First, we’re going to create a local directory. Open a terminal window and issue the command:

mkdir ~/myrepo

Change into that new folder with the command cd ~/myrepo. Next we must initialize the repository with the command:

git init

Now we initialize the repository with git-annex, only with the addition of a name. I’m going to name this UbuntuServer, so the initialization command would be:

git annex init "UbuntuServer"

Next we’ll move some files into ~/myrepo. For testing purposes, you can create an empty file with the command touch test1. Once you’ve created the test file, add it with git annex using the command:

git annex add test1

Because we’re using git, you must commit the new file (otherwise git won’t know about it). For this, issue the command:

git commit -m "Added a test file"

Adding the second location

We already have our ~/Dropbox folder, so change into that with the command cd ~/Dropbox. Because this folder must also be initialized, we probably don’t want to initialize the entire contents of the ~/Dropbox folder, so let’s create a subfolder called annex with the command:

mkdir annex

Change into that new folder with the command cd annex. Initialize the folder with the command:

git init

Initialize the folder with git-annex (and name it Dropbox) with the command:

git annex init "Dropbox"

Make them aware

For our next trick, we must make the two locations aware of one another. To do this, change into the ~/myrepo folder, and then make it aware of Dropbox with the command:

git remote add Dropbox ~/Dropbox/annex

Next, change into the ~/Dropbox/annex folder and make it aware of the ~/myrepo folder with the command:

git remote add UbuntuServer ~/myrepo

Sync ’em

With each location aware of the other, let’s sync them. Change into the ~/myrepo folder and issue the command:

git annex sync

Now, change into the ~/Dropbox/annex folder and issue the same command:

git annex sync

At this point, all we’ve done is create symlinks between the two locations. To actually sync the content, the command would then be (run in each location):

git annex sync --content

And there you go: Both locations are now in sync. Congratulations, you’ve used git-annex to sync a local folder to a locally mounted cloud location.

Keep learning

For more information, issue the command man git-annex. The manual page offers plenty of information for you to keep learning about this incredibly powerful tool.