TMSU is a tool for tagging your files. It provides a simple command-line tool for applying
tags and a virtual filesystem so that you can get a tag-based view of your files from within any other program.
TMSU does not alter your files in any way: they remain unchanged on disk, or on the network,
wherever you put them. TMSU maintains its own database and you simply gain an additional
view, which you can mount, based upon the tags you set up. The only commitment required is your time
and there's absolutely no lock-in.
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.
Use the tag command to apply tags to files:
$ tmsu tag summer.mp3 music big-jazz mp3
tmsu: New tag 'music'
tmsu: New tag 'big-jazz'
tmsu: 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 folk
$ tmsu tag winter.mp3 umsic mp3
tmsu: 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
In addition to simple tags, it is possible to specify values for tags when
applying them to files. For example:
$ tmsu tag spring.mp3 year=2003
$ tmsu tag summer.mp3 year=2008
$ tmsu tag winter.mp3 year=2010
We can view the tags for our newly created tagged files with the tags command:
$ tmsu tags summer.mp3
$ tmsu tags *.mp3
spring.mp3: folk mp3 music year=2003
summer.mp3: big-jazz mp3 music year=2008
winter.mp3: mp3 music year=2010
Now we have a set of tagged files we can start using the tag information to do some simple queries.
Let's list our mp3 files with the files command:
$ tmsu files mp3
Or we could get more specific and list just our big-jazz collection:
$ tmsu files mp3 big-jazz
There is an implicit 'and' when you list tags one after another.
You can also specify the logical 'and' explicitly if you so wish:
$ tmsu files mp3 and big-jazz
The basic logical operators 'and', 'or' and 'not' are supported, as are parentheses.
So it is possible to search our music collection to find exactly what we are looking for, such as our mp3 or flac files excluding the big-jazz ones:
$ tmsu files "(mp3 or flac) and not big-jazz"
You can also retrieve files based upon the values of tags.
We can retrieve all of our files from the year 2010, for example:
$ tmsu files year = 2010
Or perhaps just music from the naughties:
$ tmsu files "music and year >= 2000 and year < 2010"
Some characters may be interpretted by your shell: the query can typically
be enclosed in quotation marks to avoid this.
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
$ ls mp/tags
big-jazz mp3 music
$ ls -l mp/tags/music
drwxr-xr-x 0 paul paul 0 2012-04-13 20:00 big-jazz
drwxr-xr-x 0 paul paul 0 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
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/tags/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.
In addition to the tags view, there is also a queries directory in which you can run view queries
just like those we ran earlier with the files command.
To get a query based view you need merely create a directory (under 'queries') containing the query
$ ls mp/queries
$ mkdir "mp/queries/mp3 and not folk"
$ ls "mp/queries/mp3 and not folk"
In fact, it's even easier than that, as TMSU will automatically create the directory for you:
$ ls mp/queries
mp3 and not folk
$ ls "mp/queries/mp3 and big-jazz"
$ ls mp/queries
mp3 and not folk mp3 and big-jazz
This automatic creation of the query directories makes it possible to use new file queries within the
file chooser of a graphical program simply by typing the query in.
Unwanted query directories can be removed with 'rmdir'.
TMSU also allows you to limited tag management operations via the virtual filesystem. For example,
you can create a new tag by creating a new directory:
$ mkdir mp/tags/lounge
Remove specific tags from a file by deleting the symbolic link in the tag directory:
$ rm mp/tags/mp3/summer.1.mp3
Delete an unused tag by removing the empty tag directory:
$ rmdir mp/tags/house
Or delete a used tag by performing a recursive delete:
$ rm -r mp/tags/big-jazz
The best place for more information is on the TMSU wiki.
TMSU also has integrated help:
$ tmsu help
$ tmsu help tag