In the tutorial below we will set up a basic system using a USB stick that has the data repository, and one or more users that collaborate. The stick needs to be physically carried from one user to the other for collaboration to work.
Normally a USB stick has been formatted with the FAT or FAT32 filesystem. Such filesystems are not supported for collaboration. The stick needs to formatted to the ext3 filesystem for collaboration to work. How this is done will be described here.
Insert the stick into the computer, and wait a little for it to mount. It is supposed to mount automatically. If it does not mount on its own, then automatic mounting needs to be set up. Setting up automatic mounting goes beyond the scope of this tutorial.
In the terminal, give the command
df
The output of this command can be something like:
Filesystem 1K-blocks Used Available Use% Mounted on /dev/sda1 93539428 76882380 11905428 87% / tmpfs 1038428 0 1038428 0% /lib/init/rw udev 10240 104 10136 2% /dev tmpfs 1038428 0 1038428 0% /dev/shm /dev/hda 629742 629742 0 100% /media/cdrom0 /dev/sdb5 306619956 189335920 101708620 66% /media/293gig /dev/sdc1 240362656 64350876 163801980 29% /media/250gb /dev/sdd1 1960684 660896 1200188 36% /media/usbdisk
Looking through the list of mounting points, we assume that the USB stick that was inserted mounts at /media/usbdisk. From there we can see that the device is /dev/sdd1. Once we have that information, we are ready for the next step.
Before the stick can be formatted, it must be unmounted first. Issue the following command to unmount the stick:
sudo umount /media/usbdisk
The "sudo" in the command means that root privileges are needed to execute the command.
To format the USB stick to the ext3 filesystem, issue the following command:
sudo mkfs.ext3 /dev/sdd1
The formatting process will be visible and at the end some information about it will be given. At this point it is important to see if no errors occurred.
Note that the formatting command is very powerful. One could even format the main drive of the computer, wiping out all information. Extreme care should be used to ensure that the USB stick is going to be formatted, and not something else.
A label needs to be written to the USB stick. The reason of this is so as to make sure that this stick will always mount at the same mounting point. In this tutorial we write the label "repo" to it.
We take it that the same device is being used as we used for formatting the stick. That is device /dev/sdd1. To write the label to the stick, issue the following two commands:
sudo e2label /dev/sdd1 repo
sync
After the label has been written to it, remove the stick from the computer, and insert it again. It should now mount to the name of the label. In this case it should mount under /media/repo.
This can be verified with command "df":
df
The output of this command:
Filesystem 1K-blocks Used Available Use% Mounted on /dev/sda1 93539428 76882380 11905428 87% / tmpfs 1038428 0 1038428 0% /lib/init/rw udev 10240 104 10136 2% /dev tmpfs 1038428 0 1038428 0% /dev/shm /dev/hda 629742 629742 0 100% /media/cdrom0 /dev/sdb5 306619956 189335920 101708620 66% /media/293gig /dev/sdc1 240362656 64350876 163801980 29% /media/250gb /dev/sdd1 1960684 660896 1200188 36% /media/repo
This shows that it now mounts under the new name.
The USB stick will hold the data repository.
To make this stick fit for collaboration, there are a few steps to be taken. These steps are:
1. The first step will be to create a directory for the repository, and to make that directory writable. If we assume that the stick mounts at /media/repo, then the command to create a directory called "repository" is:
sudo mkdir /media/repo/repository
Notice the "sudo" command, which means that this usually needs to be done by user root. If this is done by an ordinary user, permission would be denied.
Once the directory for the repository is there, this directory needs to be made writable for ordinary users. This is the command:
sudo chmod -R 0777 /media/repo/repository/
Note the "sudo" again.
Now it is time to check whether the USB stick is writable. We do this by trying to create a file in the repository. If this succeeds, then it is writable. Note that this step can be skipped, because Bibledit itself also tests whether the stick is writable. Here's the command in case you'd like to do it:
touch /media/repo/repository/testfile
This command should complete without errors. After that the file needs to be removed again:
rm /media/repo/repository/testfile
2. The second step is to make the USB stick the current working directory. Type:
cd /media/repo/repository
3. The next step is to create a repository on the USB stick, and to copy the data to it.
To create a shared repository on the USB stick, type:
git --bare init --shared
Git will respond saying that an empty shared Git repository has been created.
Before removing the stick, ensure that the data gets written to it, by issuing the command
sync
This finishes setting up the stick.
We are now going to setup the first user. This user needs a project on his computer. The project can be empty or have books.
The user inserts the USB stick into his computer. In Bibledit he opens the project he wishes to work on with others.
He goes to menu Preferences / Git repository.
In that dialog, he ticks "Use remote repository".
Under "Repository", he enters file:///media/repo/repository
In the dialog he verifies that write access has been granted.
He then ticks "Push my data to the remote repository". This is to push all the local books onto the stick.
He then clicks Apply.
This finishes the setup of the user. He can now work in Bibledit as before, and his data will automatically be updated in the repository.
Setting up a second user, a third, a fourth, and so on, goes similar. But there are important two differences:
1. The project "Ndebele", in this example, needs to be created first for each of the other users.
2. When it comes to copying the data, he presses "Copy the remote repository to me".