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.
The easiest way to mount the VFS is with TMSU itself:
$ mkdir mp
$ tmsu mount mp
$ ls mp
queries 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
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
Here, we have tags: 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
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
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
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
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.)
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.
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.
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:
user_allow_other
Then, when mounting the VFS pass the allow_other option:
$ tmsu mount -o allow_other mp
Or:
$ 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