-+- |\/| (  | |
 |  |  |  ) |_|

TMSU is an application 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 in the TMSU wiki:



Binary builds for a limited number of architectures and operating system
combinations are available on the project's download page:


You will need to ensure that both FUSE and Sqlite3 are installed for the
program to function.


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

TMSU is currently built against the Go weekly builds. See VERSIONS for the
latest version that is known to work with the dependent packages.

2. Install the dependent packages.

  $ go get github.com/mattn/go-sqlite3
  $ go get github.com/hanwen/go-fuse/fuse

3. Clone the TMSU respository:

  $ hg clone https://bitbucket.org/oniony/tmsu

4. Make the project

  $ cd tmsu
  $ make

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

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


The project website is at:


There is a TMSU mailing list which can be used for asking questions, making
suggestions, reporting bugs, &c. Release announcements are also made on this


TMSU is written in Go. For more information visit:


TMSU itself is written and maintained by Paul Ruane <paul@tmsu.org>, however
much of the functionality it provides is made possible by the Fuse and Sqlite3
libraries, their Go bindings and, of course, the Go language standard library.

Release Notes


  IMPORTANT: This release changes the database format so that implicit taggings
  are stored rather than calculated on the fly. If you wish to use an existing
  database it must be first upgraded:
    $ cp ~/.tmsu/default.db ~/.tmsu/default.db~  # back up
    $ sqlite3 -init misc/db-upgrades/0.0.9_to_0.1.0.sql ~/.tmsu/default.db
    $ tmsu repair

  * Implicit taggings are now stored in the database rather than calculated on
    the fly.
  * Improved command-line parsing: now supports global options, short options
    and mixed option ordering.
  * Added upgrade script to convert old databases to new format (and to remove
    any invalid timestamps which cause problems with the latest Sqlite3
  * 'repair' command updated to create missing implicit taggings.
  * Fixed bug where 'repair' command was operating upon all files in the
    database with the same name as the arguments rather than those with
    matching path.
  * 'repair' command now updates stored modification time if it has changed but
    fingerprint has not.
  * Size field was not being read from the database preventing 'files' command
    from functioning.
  * Fingerprints for directories no longer calculated. (Implicit tagging means
    that duplicate files are identified instead. I may revisit this decision.)
  * Removed the 'export' command: Sqlite3 database is already in a readily
    queryable format.
  * Tags containing '/' confuse the VFS. Such tags are no longer legal.
  * File lists are now shown sorted alphanumerically.
  * Updated Zsh completion.
  * Improved unit-test coverage.
  * Minor bug fixes.


  * Fixed bug which caused process hosting the virtual file-system to crash if
    a non-existant tag directory is 'stat'ed.
  * Untagged files now inherit parent directory tags.


  Files can now be tagged within tagged directories. Files within tagged
  directories will inherit the directory's tags.

  * Fixed bug with 'untag' command when non-existant tag is specified.
  * Updated with respect to go-fuse API change. 
  * 'mount' command now lists mount points if invoked without arguments.
  * Improved 'mount' command help.
  * 'rename' command now validates destination tag name.
  * Fixed bug with 'unmount --all' returning an error if there are no mounts.
  * Removed dependency upon 'pgrep'; now accesses proc-fs directotly for mount
  * 'files' command will now show files that inherit the specified tags
    ('--explicit' option turns this off).
  * 'tags' command will now shows inherited tags ('--explicit' turns this off).
  * 'status' command now reports inherited tags.
  * 'stats' command formatting updated.
  * Other minor bug fixes.


  Files larger than 5MB now use a different fingerprinting algorithm where the
  fingerprint is produced by taking a 500KB of the start, middle and end of the
  file. This should dramatically improve performance, especially on slow file-

  NOTE: it is advisable to run 'repair' after upgrading to this version to update
        large files with fingerprints produced using the new algorithm.


  IMPORTANT: This version adds a column to one of the database tables to record
  the file's modification timestamep. The new code will not work with an
  existing TMSU database until it has been upgraded.

  To upgrade the database, run the upgrade script using the Sqlite3 tooling:

      $ sqlite3 -init misc/db-upgrade/0.0.5_to_0.0.6.sql

  It is also advisable to run 'repair' after upgrading which will populate the
  new column and also fix the directory fingerprints which have a new algorithm.

  * Upgraded to Go 1.
  * Added 'repair' command to fix up database when files are moved or modified.
  * Added 'version' command.
  * Added 'copy' command (duplicates a tag).
  * Added modification timestamp which is used in preference to fingerprint.
  * Command output now includes 'tmsu' to make it clear where output is coming
    from when piping.
  * Relative paths now calculated more accurately.
  * Zsh completion now supports tags containing colons.
  * 'status' command performance and functionality improvements.
  * Added directory fingerprinting.
  * Added 'repair' command to Zsh completion.
  * The 'files' command now allows tags to be excluded by prefixing them with a
    minus, e.g. -jazz.

- - -

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.