Clone wiki

tmsu / Virtual Filesystem


The virtual filesystem (VFS) provides a filesystem from which you can browse your tagged files. It provides virtual directories to represent the tags and symbolic links for the tagged files: linking back to their original file locations. It allows you to access your files by way of tags from any other program.

Mounting The VFS

The easiest way to mount the VFS is with TMSU itself:

$ mkdir mp
$ tmsu mount mp
$ ls mp
quries  tags

To unmount:

$ tmsu unmount mp

Alternatively unmount with the FUSE tool. (This approach will work even in the highly unlikely event that TMSU crashes.)

$ fusermount -u mp

Tags Directory

The virtual file system's tags directory contains virtual directories for each tag you have created. Within these directories are symbolic links to the files that have that particular tag applied. In addition, each tag directory contains directories for the other tags applied to the set of files visible so that you can hone in on the file you want.

For example:

$ cd mp/tags
$ ls
good  mp3  music  rock  trance

If we drill down into the mp3 directory we can get symbolic links to our mp3 tagged files and see how our mp3 files have been further tagged.

$ cd mp3
$ ls
total 0
lrwxr-xr-x 1 paul...06:55 01 - Some Song.1.mp3 -> /home/paul/music/Some Band/Debut Album/01 - Some Song.mp3
lrwxr-xr-x 1 paul...06:56 02 - Another Song.2.mp3 -> /home/paul/music/Some Band/Debut Album/02 - Another Song.mp3
lrwxr-xr-x 1 paul...06:56 03 - Yet Another.3.mp3 -> /home/paul/music/Some Band/Debut Album/03 - Yet Another.mp3
drwxr-xr-x 0 paul...07:03 good
drwxr-xr-x 0 paul...07:03 music
drwxr-xr-x 0 paul...07:03 rock
drwxr-xr-x 0 paul...07:03 trance

You'll probably notice that the filenames contain a number where the originals did not. This number is TMSU's internal file identifier: it's present in the filename as otherwise there will be a name clash if you tag two files that have the same name with the same tag.

We also have further tag directories indicating that our MP3 files have been further (and variously) tagged good, music, rock and trance. If we change into one of these directories we can get a view of the files that have both mp3 and this further tag (e.g. rock) applied:

$ cd rock
$ ls -l
total 0
lrwxr-xr-x 1 paul...06:56 02 - Another Song.2.mp3 -> /home/paul/music/Some Band/Debut Album/02 - Another Song.mp3
lrwxr-xr-x 1 paul...06:56 03 - Yet Another.3.mp3 -> /home/paul/music/Some Band/Debut Album/03 - Yet Another.mp3
drwxr-xr-x 0 paul...07:12 good
drwxr-xr-x 0 paul...07:12 music

Virtual File System Operations

It's possible to perform a limited set of tag management operations via the virtual filesystem itself:

* Create new tags
* Remove tags from a file

Create New Tags

To create a new tag using the virtual filesystem, simply create a new directory under 'tags':

$ cd mp/tags
$ ls
blue  red
$ mkdir green                      # tmsu tag --create green
$ ls
blue  green  red
$ tmsu tags --all

Rename Tags

To rename a tag, simply rename the tag directory:

$ cd mp/tags
$ ls
blue  green  red
$ mv red maroon                    # tmsu rename red maroon
$ ls
blue green maroon

Untagging a File

Files can be untagged by removing the symbolic link from the tag directory you wish to remove. For example, to remove a panorama tag from file mountain.jpg:

$ ls -l mp/tags/panorama
total 0
lrwxr-xr-x 1 ... mountain.1.jpg -> /tmp/mountain.jpg
lrwxr-xr-x 1 ... vista.2.jpg -> /tmp/vista.jpg
$ rm mp/tags/panorama/mountain.1.jpg
$ tmsu tags /tmp/*.jpg
/tmp/mountain.jpg: photo
/tmp/vista.jpg: panorama photo

If you remove a symbolic link from a nested tag directory, e.g. mp/tags/photo/panorama, then only the nested tag, panorama, is removed:

$ ls mp/tags/photo/panorama
$ rm mp/tags/photo/panorama/vista.2.jpg
$ ls mp/tags/photo

Deleting Tags

A tag can be deleted by removing the tag directory. A tag directory can only be deleted if the tag is no longer applied so it is necessary to first delete any symbolic links immediately under the tag directory.

It is not necessary to delete the symbolic links under any nested tag directories and doing so will remove those tags from the files.

$ ls mp/tags
photo  panorama
$ rmdir mp/tags/photo
rmdir: failed to remove 'mp/tags/photo': Directory not empty
$ ls mp/tags/photo
panorama  vista.2.jpg
$ rm mp/tags/photo/vista.2.jpg      # removes 'photo' from vista.jpg
$ ls mp/tags/photo
$ rmdir mp/tags/photo               # deletes the 'photo' tag

Recursive deletion should be avoided as it will delete the tag intended but not before it has stripped the files that are tagged with it of all tags! For example:

$ tmsu tag /tmp/baa.jpg animal sheep photo
$ ls mp/tags/
animal  sheep
$ ls mp/tags/animal
photo  sheep  baa.1.jpg
$ rm -r mp/tags/animal              # WARNING non-obvious result
$ tmsu tags --count /tmp/baa.jpg

Applying Tags

Currently it is not possible to tag a file via the virtual filesystem.

(The technical reason for this is that TMSU adds an identifier to the symbolic link names to avoid name clashes within the tag directories. In order to create a symbolic link in a tag directory you would have to know, in advance, what that number should be. I hope to work around this problem in a subsequent version.)

Queries Directory

Whilst the tags directory provides an immediately view of your tags and files, it does have some limits: it is not possible to exclude tags or perform more complicated tag queries. The queries directory lets you access a query-based view of your files instead using the same query language as the files command. Simply access the directory with the query text as the directory name to view the set of files:

$ cd mp/queries
$ ls
$ ls "good and music"
02 - Another Song.2.mp3
$ ls
good and music
$ ls "good and (music or photo) and not rainy"

Note that any accessed query directory is created and saved automatically so it is not necessary to first create them. The directories can be removed using rmdir when you are finished with them or left to ease subsequent access.

Advanced Mounting

It is also possible to mount the VFS using regular mount command.

First, ensure that the mount.tmsu helper script is installed in /sbin. This script is included with the TMSU binary in the bin directory or is available in the repository at misc/bin.

Check that a TMSU filesystem can be mounted with mount. (This must be done as root until the mount is configured in /etc/fstab.)

$ mkdir mp
$ sudo mount -t tmsu ~/.tmsu/default.db mp
$ sudo umount mp

The VFS can then be configured in the /etc/fstab for convenience:

# /etc/fstab
/home/paul/.tmsu/default.db /home/paul/mp tmsu user,noauto 0 0

This allows the filesystem to be mounted more simply:

$ mount /home/paul/mp

(For some reason FUSE only allows root to unmount the filesystem: the 'users' option appears not to be valid for a FUSE filesystem.)

To have the TMSU VFS automatically mount at start up, change noauto to auto in /etc/fstab.

Allowing Other Users Access

FUSE allows only root and the mounting user access to the mounted filesystem by default. To grant access to other users you must edit /etc/fuse.conf and enable this functionality:


Then, when mounting the VFS pass the allow_other option:

$ tmsu mount -o allow_other mp


$ mount -t tmsu ~/.tmsu/default.db -o allow_other mp

Or add this option to /etc/fstab:

# /etc/fstab
/home/paul/.tmsu/default.db /home/paul/mp tmsu user,noauto,allow_other 0 0