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
$ 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
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.
$ cd mp/tags $ ls good mp3 music rock trance
If we drill down into the
mp3 directory we can get symbolic links to our
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
trance. If we
change into one of these directories we can get a view of the files that have
mp3 and this further tag (e.g.
$ 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 blue green red
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
$ 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 vista.2.jpg $ rm mp/tags/photo/panorama/vista.2.jpg $ ls mp/tags/photo vista.2.jpg
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 0
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.)
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
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.
It is also possible to mount the VFS using regular
First, ensure that the
mount.tmsu helper script is installed in
script is included with the TMSU binary in the
bin directory or is available
in the repository at
Check that a TMSU filesystem can be mounted with
mount. (This must be done as
root until the mount is configured in
$ 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
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
enable this functionality:
Then, when mounting the VFS pass the
$ tmsu mount -o allow_other mp
$ mount -t tmsu ~/.tmsu/default.db -o allow_other mp
Or add this option to
# /etc/fstab /home/paul/.tmsu/default.db /home/paul/mp tmsu user,noauto,allow_other 0 0