Overview
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.
does not alter your files in any way: they remain unchanged on disk, or on the network,
wherever you put them. maintains its own database and you simply gain an additional
tag-based view based upon the tags you set up.
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.
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 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/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 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 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