Overview

TMSU is a tool for tagging your files. It provides a simple command-line utility for applying tags and a virtual filesystem to give you a tag-based view of your files from any other program.

TMSU does not alter your files in any way: they remain unchanged on disk, or on the network, wherever your put them. TMSU maintains its own database and you simply gain an additional view, which you can mount where you like, based upon the tags you set up.

Usage

Before you can get tagging, you'll need to initialise a TMSU database:

$ cd ~
$ tmsu init

This database will be used automatically whenever you are under that directory. In this case we created one under the home directory.

You can tag a file by specifying the file and the list of tags to apply:

$ tmsu tag banana.jpg fruit art year=2015

Or you can apply tags to multiple files:

$ tmsu tag --tags="fruit still-life art" banana.jpg apple.png

You can query for files with or without particular tags:

$ tmsu files fruit and not still-life

Mount the virtual filesystem to an empty directory:

$ mkdir mp
$ tmsu mount mp

A subcommand overview and detail on how to use each subcommand is available via the integrated help:

$ tmsu help
$ tmsu help tags

Documentation is maintained online on the wiki:

• https://github.com/oniony/TMSU/wiki

Installing

Packages

Thanks to the efforts of contributors using these platforms, packages are available for the following GNU/Linux distributions:

• Ubuntu
  • Stable https://launchpad.net/~tmsu/+archive/ubuntu/ppa
  • Daily https://launchpad.net/~tmsu/+archive/ubuntu/daily
• Arch
  • Stable https://aur.archlinux.org/packages/tmsu/
• Nix/NixOS
  • Stable https://search.nixos.org/packages?query=tmsu&show=tmsu
  • Unstable https://search.nixos.org/packages?query=tmsu&show=tmsu&channel=unstable

These packages are not maintained by me and I cannot guarantee their content.

Binary

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

• https://github.com/oniony/TMSU/releases

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. (If you install TMSU using one of the above packages, these should be installed automatically.)

1. Install the binary

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

    $ sudo cp bin/tmsu /usr/bin
   

2. Optional: Zsh completion

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

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

From Source

If you would rather build from the source code then please see COMPILING.md in the root of the repository.

About

TMSU itself is written and maintained by [Paul Ruane](mailto:Paul Ruane paul@tmsu.org).

The creation of TMSU is motivation in itself, but if you should feel inclinded to make a small gift via Pledgie or Bitcoin then it shall be gratefully received:

• https://pledgie.com/campaigns/31085
• 1TMSU5TL3Yj6AGP7Wq6uahTfkTSX2nWvM

TMSU is written in Go: http://www.golang.org/

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.

• Website: http://tmsu.org/
• Project: https://github.com/oniony/TMSU/
• Wiki: https://github.com/oniony/TMSU/wiki
• Issue tracker: https://github.com/oniony/TMSU/issues
• Mailing list: http://groups.google.com/group/tmsu

Release Notes

v0.8.0 (in development)

• VFS now uses relative paths -- thanks to foxcpp
• Support for Blake2b-256 fingerprints -- thanks to foxcpp
• Hidden files are no longer tagged by default when tagging recursively. To include hidden files use the --include-hidden option -- thanks to foxcpp
• Fixes to Zsh completion -- thanks to taiyu-len and Shadoukan

v0.7.5

• Fixed issue with broken stderr pipe if VFS produces an error
• '--name' option on 'tags' subcommand now takes argument to control when file/value names are printed

v0.7.4

• Fixed further regressions with the set of files returned by files command.

v0.7.3

• VFS directories were showing incorrect files and tags

v0.7.2

• VFS directories were not showing for tag values

v0.7.1

• Fixed a bug where wrong files would be returned when an tag=value implied another tag -- thanks to Fornost461
• Specifying empty FUSE options would cause Fusermount to fail -- thanks to metafex
• Manual repair would drop the file fingerprint -- thanks to c7nh7r

v0.7.0

Note: this release changes how symbolic links are handled. See below.

• TMSU now compiles for Mac O/S. (Thanks to https://github.com/pguth.)
• The VFS no longer lists files alongside the tag directories under tags. Instead there are results directories at each level, within which you can find the set of symbolic links to the tagged files.
• Symbolic links are now followed by default. This means that if you tag a symbolic link, the target file is tagged instead. To instruct TMSU to not follow symbolic links (previous behaviour) use the new --no-dereference option on the relevant subcommands.
• Added new setting symlinkFingerprintAlgorithm to allow the fingerprint algorithm for symbolic links to be configured separately to regular files.
• By default duplicate files will now be reported when tagging. A new setting reportDuplicates can be used to turn this off.
• Slashes are now permitted within tags and values, useful for recording URLs. In the virtual filesystem, similar looking Unicode characters are used in their place.
• Added --where option to tag subcommand to allow tags to be applied to the set of files matching a query.
• The VFS tags directory will now relist tags that have values so that multiple values can be specified, e.g. tags/color/=red/color/=blue.
• It is now possible to list tags that use a particular value with the new --value option on the 'tags' subcommand.
• Made it possible to upgrade the database schema between releases.
• Added --count option to untagged.
• Bug fixes.

v0.6.1

• Fixed crash when opening an empty tag directory in the VFS.

v0.6.0

Note: this release changes the database schema by adding additional columns to the 'implication' table. TMSU will automatically upgrade your database upon first use but you may wish to take a backup beforehand.

• Relaxed restrictions on tag and value names, allowing punctuation and whitespace characters. Problematic characters can be escaped with backslash.
• Values are no longer automatically deleted when no longer used: it is now up to you to manage them.
• Added --force option to 'tag' subcommand to allow tagging of missing or permission denied paths and broken symlinks.
• 'imply' now creates tags if necessary (and 'autoCreateTags' is set).
• Performance improvements to the virtual filesystem.
• Fixed 'too many SQL variables' when merging tags applied to lots of files.
• Added --name option to 'tags' to force printing of name even if there is only a single file argument, which is useful when using xargs.
• Replaced 'stats' subcommand with 'info' subcommand (with --stats and --usage options for tag statics and usage counts respectively).
• Included a set of scripts for performing filesystem operations whilst keeping the TMSU database up to date. If you wish to use these scripts I recommend you alias them to simpler names, e.g. 'trm'.
  • tmsu-fs-rm Removes files from the filesystem and TMSU
  • tmsu-fs-mv Moves a file in the filesystem and updates TMSU
  • tmsu-fs-merge Merges files (deleting all but the last)
• Tag values can now be renamed, deleted and merged using the new --value option on the corresponding subcommands.
• Tag values can now be used in implications.
• Tag values can be explicitly created: tmsu tag --create =2015. (It may be necessary to enclose the argument in quotes depending upon your shell.)
• It is no longer possible to add a circular tag implication. (These were not correctly applied anyway. An alias facility will be provided in a later version.)
• The output of 'files' can now be sorted in various ways using --sort.
• Case insensitive queries can now be performed with the --ignore-case option on the 'files' subcommand.
• Added integration tests covering CLI.
• Bug fixes.

v0.5.2

• Fixed bug where concurrent access to the virtual filesystem would cause a runtime panic.

v0.5.1

• Fixed bug with database initialization when .tmsu directory does not already exist.

v0.5.0

Note: This release has some important changes, including the renaming of some options, the introduction of local databases and a switch from absolute to relative paths in the database. Please read the following release notes carefully.

• The --untagged option on the 'files' and 'status' subcommands has been replaced by a new 'untagged' subcommand, which should be more intuitive.
• The --all option on the 'files', 'tags' and 'values' subcommands has b