tmsu /


TMSU is a program that allows you to organise your files by associating them with tags. It provides a tool for managing these tags and a virtual file system to allow tag-based access to your files.

TMSU's virtual file system does not store your files: it merely provides an alternative, tagged-based view of your files stored elsewhere in the file system. That way you have the freedom to choose the most suitable file system for storage whilst still benefiting from tag-based access.


A command overview and details on how to use each command are available via the integrated help:

$ tmsu help

Full documentation is maintained online on the wiki:


Binary builds for a limited number of architectures and operating system combinations are available:

You will need to ensure that both FUSE and Sqlite3 are installed for the program to function. These packages are typically available with your operating system's package management system.

  1. Install the binary

Copy the program binary. The location may be different for your operating system:

$ sudo cp bin/tmsu /usr/bin
  1. Optional: Zsh completion

Copy the Zsh completion file to the Zsh site-functions directory:

$ cp misc/zsh/_tmsu /usr/share/zsh/site-functions


The following steps are for compiling from source.

  1. Installing Go

    TMSU is written in the Go programming language. To compile from source you must first install Go and the packages that TMSU depends upon. You can get that from the Go website:

    Go can be installed per the instructions on the Go website or it may be available in the package management system that comes with your operating system.

  2. Set Up the Go Path

    Go (as of verison 1.1) requires the GOPATH environment variable be set for the 'go get' command to function. You will need to set up a path for Go packages to live if you do not already have one:

    $ mkdir $HOME/gopath
    $ export GOPATH=$HOME/gopath
  3. Install the dependent packages.

    These will be installed to your $GOPATH directory.

    $ go get -u
    $ go get -u
  4. Clone the TMSU respository:

    $ hg clone
  5. Make the project

    $ cd tmsu
    $ make

    This will compile to 'bin/tmsu' within the working directory.

  6. Install the project

    $ sudo make install

    This will install TMSU to '/usr/bin/tmsu'.

    It will also install the Zsh completion to '/usr/share/zsh/site-functions'.

    To change the paths used override the environment variables in the Makefile.


TMSU itself is written and maintained by Paul Ruane

TMSU is written in Go:

Much of the functionality the program provides is made possible by the FUSE and Sqlite3 libraries, their Go bindings and the Go language standard library.

Release Notes

v0.3.0 (in development)

  • Added support for file queries, e.g. 'fish and chips and (mushy-peas or ketchup)'
  • Added support for file queries in the virtual filesystem: create a query directory under the 'queries' directory.
  • Added script to allow the virtual filesystem to be mounted via the system mount command or on startup via the fstab.
  • Added global option --database for specifying database location.


  • Fixed virtual file system.


  • Fixed bug where excluding multiple tags would return incorrect results.
  • Fixed Go 1.1 compilation problems.


  • Added support for tag implications, e.g. tag 'a' implies 'b'. New 'imply' command for managing these.
  • Added --force option to 'repair' command to remove missing files (and associated taggings) from the database.
  • Added --from option to 'tag' command to allow tags to copied from one file to another. e.g. 'tmsu tag -f a b' will apply file b's tags to file a. ('tag -r -f a a' will recursively retag a directory's contents.)
  • Added --directory option to 'status' command to stop it recursively processing directory contents.
  • Added --print0 option to 'files' command to allow use with xargs.
  • Added --count option to 'tags' and 'files' command to list tag/file count rather than names.
  • Bug fixes and unit-test improvements.

Copyright 2011 Paul Ruane

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.