Mounting repositories

Using commands like brig cp might not feel very seamless, especially when being used to tools like file browsers. And indeed, those commands are only supposed to serve as a low-level way of interacting with brig and as way for scripting own, more elaborate workflows.

For your daily workflow it is far easier to mount all files known to brig to a directory of your choice and use it with the tools you are used to. To accomplish that brig supports a FUSE filesystem that can be controlled via the mount and fstab commands. Let’s look at brig mount:

$ mkdir ~/data
$ brig mount ~/data
$ cd ~/data
$ cat hello-world
Hello World
$ echo 'Salut le monde!' > salut-monde.txt
# There is no difference between brig's "virtual view"
# and the contents of the mount:
$ brig cat salut-monde.txt
Salut le monde!

You can use this directory like a normal one, but check for the CAVEATS below. You can have any number of mounts. This proves especially useful when only mounting a subdirectory (let’s say we have a directory called /Public) with the --root option of brig mount and mounting all other files as read only (--readonly).

$ brig mount ~/data --readonly
$ brig mkdir /writable
$ brig touch /writable/please-edit-me
$ mkdir ~/rw-data
$ brig mount ~/rw-data --root /writable
$ echo 'writable?' > ~/data/test
read-only file system: ~/data/test
$ echo 'writable!' > ~/rw-data/test
$ cat ~/rw-data/test

An existing mount can be removed again with brig unmount <path>:

$ brig unmount ~/data
$ brig unmount ~/rw-data
$ brig rm writable

Remote access

Working with remote data does often not work extremely well with the file abstraction that does not play well with timeouts. This often causes applications to hang for indefinite times, since they are not most of the time not build for data that might not be delivered immediately. For this very common case we have the --offline flag. It will error out immediately on files that are not in our local cache:

$ brig mount /tmp/mount --offline
# Or with fstab:
$ brig fstab add some-mount /tmp/mount --offline

If you have a remote file you want to read, you can do this to make it cached locally:

$ brig cat /remote-file > /dev/null

After brig cat run, you should be able to view the file normally in the mount.

Making mounts permanent

All mounts that are created via brig mount will be gone after a daemon restart. If you a typical set of mounts, you can persist them with the brig fstab facility:

$ brig fstab add tmp_rw_mount /tmp/rw-mount
$ brig fstab add tmp_ro_mount /tmp/ro-mount -r
$ brig fstab
NAME          PATH           READ_ONLY  ROOT  ACTIVE
tmp_ro_mount  /tmp/ro-mount  yes        /
tmp_rw_mount  /tmp/rw-mount  no         /
$ brig fstab apply
$ brig fstab
NAME          PATH           READ_ONLY  ROOT  ACTIVE
tmp_ro_mount  /tmp/ro-mount  yes        /     ✔
tmp_rw_mount  /tmp/rw-mount  no         /     ✔
$ brig fstab apply -u
NAME          PATH           READ_ONLY  ROOT  ACTIVE
tmp_ro_mount  /tmp/ro-mount  yes        /
tmp_rw_mount  /tmp/rw-mount  no         /

Et Voilà, all mounts will be created and mounted once you enter brig fstab apply or restart the daemon. The opposite can be achieved by executing brig fstab apply --unmount.

CAVEATS: The FUSE filesystem is not yet perfect and somewhat experimental. Keep those points in mind:

  • Performance: Writing to FUSE is currently somewhat memory and CPU intensive. Generally, reading should be fast enough for most basic use cases, but also is not enough for high performance needs. If you need to edit a file many times, it is recommended to copy the file somewhere to your local storage (e.g. brig cat the_file > /tmp/the_file), edit it there and save it back for syncing purpose. Future releases will work on optimizing the performance.
  • Timeouts: Although it tries not to look like one, we’re operating on a networking filesystem. Every file you access might come from a different computer. If no other machine can serve this file we might block for a long time, causing application hangs and general slowness. This is a problem that still needs a proper solution and leaves much to be desired in the current implementation.