TMSU bitcoin address

Overview

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.

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
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

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
year=2008

$ tmsu tags *.mp3
spring.mp3: folk mp3 music year=2003
summer.mp3: big-jazz mp3 music year=2008
winter.mp3: mp3 music year=2010

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 mp3 files with the files command:

$ tmsu files mp3
spring.mp3
summer.mp3
winter.mp3

Or we could get more specific and list just our big-jazz collection:

$ tmsu files mp3 big-jazz
summer.mp3

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
summer.mp3

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"
spring.mp3
winter.mp3

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
winter.mp3

Or perhaps just music from the naughties:

$ tmsu files "music and year >= 2000 and year < 2010"
spring.mp3
summer.mp3

 Some characters may be interpretted by your shell: the query can typically be enclosed in quotation marks to avoid this.

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
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
[####>-------] 34%

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.

Queries

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 text:

$ 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

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"
summer.1.mp3
$ 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'.

Tag Management

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

Where Next?

The best place for more information is on the TMSU wiki.

TMSU also has integrated help:

$ tmsu help
$ tmsu help tag