TMSU is a tool for tagging your files. It provides a simple command-line tool for applying tags and a virtual file-system so that you can get a tagged 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 tag-based view based upon the tags you set up.
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 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 folk $ 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
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: folk mp3 music summer.mp3: big-jazz mp3 music winter.mp3: mp3 music
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
Putting more than one tag, as we did above, lists the files that have all of the tags. It is also possible to run more complicated queries:
$ tmsu files "mp3 and (big-jazz or folk)" spring.mp3 summer.mp3 $ tmsu files not folk summer.mp3 winter.mp3
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 queries tags $ 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
↑ 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/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 create directories containing a file query:
$ ls mp/queries README.md $ mkdir "mp/queries/mp3 and not folk" $ ls "mp/queries/mp3 and not folk" summer.1.mp3 winter.3.mp3 $ ls "mp/queries/mp3 and big-jazz" summer.1.mp3 $ ls mp/queries mp3 and big-jazz
As demonstrated above, it is not even necessary to first create the directory: any attempt to access a directory with a valid query brings it to life. This makes it possible to use new file queries within the file chooser of a graphical program simply by typing it in. (The query directories can be removed again with 'rmdir', even when not empty.)
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 there are two options:
- Pass the database path on the command line using the --database global option.
- Set the TMSU_DB environment variable with the path.
(The bundled Zsh completion is aware of the --database option and will suggest tags from the correct database.)
$ tmsu --database=~/music.db tag song flac $ 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