TMSU: tag your files

terminalYou have a collection of files which you want to classify based on a certain criteria to find them easily. Wouldn’t it be easier if the filesystem provided a way to tag the files to group them? Unfortunately, none of the popular filesystems of today support this. One solution is to create separate directories and store the files. Another option is to use a collection manager.

TMSU is a new tool that solves the problem with a unique approach. It allows you to tag files on the fly and maintains its own database to handle the tags.


Get the latest release for your architecture from the releases page. Currently TMSU is distributed as an executable which you can copy in your $PATH.

Note that TMSU needs FUSE and Sqlite3 to work.


Common example scenarios:

  • Tag files
    $ tmsu tag movie1.mkv movie action-movie genre=5 yr2014
    tmsu: New tag 'movie'
    tmsu: New tag 'action movie'
    tmsu: New tag 'genre=5'
    tmsu: New tag 'yr2014'

    TMSU shows the new tags it creates. You can also specify the value of a tag as we have done in genre=5.

  • Add tag to multiple files
    $ tmsu tag --tags "movie yr2014" *.mkv
  • Change mis-spelt tag to correct tag
    $ tmsu merge movei movie
  • Show tags applied to a file (or set of files)
    $ tmsu tags *.mkv
  • Search files by tag
    $ tmsu files movie yr2014

    and is the implicit operator.

  • Combining operators and parenthesis (and, or, not supported)
    $ tmsu files "(movie or tvseries) and not action-movie"
  • Search files by value of tag (or conditions)
    $ tmsu files genre = 7
    $ tmsu files movie and genre >= 5 and genre < 7
  • Get help
    $ tmsu help

Virtual Filesystem

TMSU supports mounting its database as a virtual filesystem and operating on it. The filesystem has two directories:

  1. tags: stores all user-created tags as directories under it. Inside each tag directory are the symbolic links to the files with the tag.
  2. queries: stores user-created queries as directories under it. Inside each query directory are the files those match the query

Example virtual filesystem usage:

  • Mount to a directory
    $ mkdir /mnt/tmsumnt
    $ tmsu mount /mnt/tmsumnt
    $ ls /mnt/tmsumnt
    queries    tags
  • List tags and files within
    $ ls /mnt/tmsumnt/tags
    action-movie    movie    yr2014
    $ ls /mnt/tmsumnt/tags/movie
    action-movie    movie1.1.mkv    yr2014

    The additional ‘1’ between movie1. and .mkv is the file id. You can pass the symbolic link movie1.1.mkv to a player to play it.

  • List queries and create new ones
    $ ls /mnt/tmsummnt/queries
    $ mkdir /mnt/tmsummnt/queries/"movie and not drama"
    $ ls "/mnt/tmsummnt/queries/movie and not drama"
  • mkdir is the above example is redundant as running ls within queries directory automatically creates the directory with the query name
    $ ls /mnt/tmsummnt/queries
    movie and not drama
    $ ls "/mnt/tmsummnt/queries/movie and not thriller"
    $ ls /mnt/tmsummnt/queries
    movie and not drama    movie and not thriller

On GitHub: TMSU

One thought on “TMSU: tag your files”

Leave a Reply

Your email address will not be published. Required fields are marked *