TMSU is a program that allows you to organise your files by associating them with tags.
It provides a command-line tool for applying tags and a virtual file-system for browsing by tag.
TMSU's virtual file-system can be used with virtually any other program. Tags appear
as directories and you can narrow in on what you are looking for by drilling down into the tag directories.
TMSU does not store your files: it merely provides an alternative, tag based view of your
files stored elsewhere. You can have a tag based view of your files stored in whatever file-system suits you best.
Quick Tour
This tour will show you how to use the command-line tool to tag and query your files and how to mount and
peruse the virtual file-system.
Tagging Files
Use the tag command to apply tags to files:
$ tmsu tag summer.mp3 music big-jazz mp3
New tag 'music'
New tag 'big-jazz'
New tag 'mp3'
If you have a set of files and would like to apply the same tags to each, then there is an alternative
form of the command that lets you put the files last. For example we can tag all of the MP3 files in the
current directory as both music and mp3:
$ tmsu tag --tags "music mp3" *.mp3
The 'New tag' messages let you know that you have created new tags, which makes it easy to notice mispellings:
$ tmsu tag spring.mp3 music mp3
$ tmsu tag winter.mp3 umsic mp3
New tag 'umsic'
But it's ok! We can fix this with the merge command, merging the accidentally created umsic tag into the
existing music tag:
$ tmsu merge umsic music
Listing Tags
We can view the tags for our newly created tagged files with the tags command:
$ tmsu tags summer.mp3
big-jazz
mp3
music
$ tmsu tags *.mp3
spring.mp3: mp3 music
summer.mp3: big-jazz mp3 music
winter.mp3: mp3 music
Listing Files
Now we have a set of tagged files we can start using the tag information to do some simple queries.
Let's list our MP3s with the files command:
$ tmsu files mp3
spring.mp3
summer.mp3
winter.mp3
$ tmsu files mp3 big-jazz
summer.mp3
Virtual File-System
Listing files from the command line is all very well but it is not very useful when we want to access
our files from other programs, especially those with graphical interfaces. TMSU
also sports a virtual file-system (VFS) that we can mount:
$ mkdir mp
$ tmsu mount mp
$ ls mp
tags
$ ls mp/tags
big-jazz mp3 music
$ ls -l mp/tags/music
drwxr-xr-x 0 paul paul 1 2012-04-13 20:00 big-jazz
drwxr-xr-x 0 paul paul 2 2012-04-13 20:00 mp3
drwxr-xr-x 0 paul paul 0 2012-04-13 20:00 spring.2.mp3 -> /home/paul/spring.mp3
drwxr-xr-x 0 paul paul 0 2012-04-13 20:00 summer.1.mp3 -> /home/paul/summer.mp3
drwxr-xr-x 0 paul paul 0 2012-04-13 20:00 winter.3.mp3 -> /home/paul/winter.mp3
↑ ↑
file count file id
Files in the virtual file-system are actually just symbolic links back to the tagged file's
real location elsewhere on the file-system. This means they can be used just like regular
files from any application:
$ acmeplayer mp/music/summer.1.mp3
[####→-------]
The entries contain an ID number which ensures the filename is unique within the tag directory
(even when multiple files with the same name are tagged with the same tag.)
The tag directories report the number of tagged files as their size, e.g. above the 'mp3' tag directory
has a size of two so there are two files that are tagged both music and mp3.
Databases Location
By default TMSU creates a database at '$HOME/.tmsu/default.db'. If you
want to locate the database elsewhere or work with mulitple databases then you need to set the TMSU_DB
environment variable so that TMSU knows where to look:
$ export TMSU_DB=/mnt/sdcard/tmsu.db
$ tmsu tag /mnt/sdcard/DC-143.jpg photo location:spain mountain
$ tmsu tag /mnt/sdcard/DC-144.jpg photo location:spain chicken
