tmsu

Tag a specific file with multiple tags

$ tmsu tag [path/to/file.mp3] [music] [big-jazz] [mp3]

$ tmsu tag --tags "[music mp3]" [*.mp3]

$ tmsu tags [*.mp3]

$ tmsu files [big-jazz] [music]

$ tmsu files "[(year >= 1990 and year <= 2000)] and [grunge]"

$ tmsu mount [path/to/directory]

tmsu [GLOBAL_OPTIONS] [OPTIONS] [ARGUMENTS]

Common commands include:
tmsu tag [OPTIONS] FILE... TAG...     # Add tags to files
tmsu untag [OPTIONS] FILE... TAG...   # Remove tags from files
tmsu mount [OPTIONS] [MOUNTPOINT]   # Mount the FUSE filesystem
tmsu files [OPTIONS] [QUERY]           # List files matching a tag query
tmsu tags [OPTIONS] [QUERY]            # List tags

--config
    Specify an alternative configuration file.
Defaults to ~/.tmsu/tmsu.conf.

--database
    Specify an alternative database file.
Defaults to ~/.tmsu/db.sqlite3.

--force
    Force an operation that would otherwise require confirmation.

--no-confirm
    Do not ask for confirmation for destructive operations.

--quiet
    Suppress output messages.

--version
    Display version information and exit.

--help
    Display help information and exit.

tmsu is a powerful command-line utility for tagging files and directories. Instead of relying on rigid directory structures, tmsu allows you to attach arbitrary keywords (tags) to your files, providing a flexible and dynamic way to organize and retrieve them. It stores these tags in a lightweight SQLite database. One of its most distinctive features is the ability to mount a FUSE filesystem, which presents a virtual view of your files organized by their tags. For instance, you can navigate to a directory like ~/tmsu/mount/photos+vacation to see all files tagged with both "photos" and "vacation". This enables powerful multi-dimensional searching and browsing without duplicating or moving your original files. tmsu supports operations like adding, removing, renaming, and listing tags, as well as complex tag queries.

tmsu relies on the FUSE (Filesystem in Userspace) kernel module for its virtual filesystem capabilities. This means FUSE must be installed and properly configured on your system.
The performance of the virtual filesystem might be less than native filesystems, especially with very large numbers of files or complex tag queries, as it involves database lookups and FUSE overhead.
tmsu's database (db.sqlite3) is crucial; damaging or corrupting it can lead to loss of tag information. Regular backups are recommended.
The FUSE mount presents a symbolic view of your files. Operations like deleting files via the tmsu mount will typically remove the file from your actual filesystem, not just its tags. Be cautious.

By default, tmsu stores its tag database in ~/.tmsu/db.sqlite3. It is important to back up this file regularly to prevent loss of your tagging information.

tmsu supports a simple yet powerful query language for retrieving files. Tags can be combined using Boolean operators such as AND (implicit space), OR (|), and NOT (- or !). Parentheses can be used for grouping. For example, "photos and (vacation or travel) -europe" would find photos from vacations or travel that are not from Europe.

While not a core feature, tmsu can be integrated with scripts to automatically tag files based on their content, metadata, or other criteria, expanding its utility beyond manual tagging.

tmsu was created by Paul H., with initial public releases and development activity around 2013-2014. It's written in C++ and designed to be fast and robust, leveraging SQLite for its backend. While development activity has seen periods of varying intensity, it remains a stable and functional tool, prized by users who prefer command-line interfaces and highly customizable file organization.

find(1): Traditional command for finding files based on name, type, size, modification time, etc., locate(1): Fast database-driven file lookup, primarily by name., etik(1): Another command-line file tagging utility.