PlaylistFS

PlaylistFS is a FUSE filesystem that allows to easily fill a directory with disparate files, similar to UnionFS, but much simpler.

PlaylistFS uses "playlists" to organize files conveniently, and provides a way to mount them automatically, but can also use multiple lists to pull everything in one place. Files in PlaylistFS work similar to symlinks, but are presented as regular files by default, with all operations proxied to original files.

Some examples of what PlaylistFS can be used for:

• presenting your playlists in filesystem, not just in an audio player (that's where the name comes from!)
• organizing a library by genres or authors without copying files
• putting header files of libraries into a single directory for reference

Compiling

PlaylistFS has following library dependencies:

• libfuse3 (recommended) or libfuse2 (for old systems)
• glib2

On systems with separate development packages those need to be installed as well. Of course, basic development environment is also needed: pkg-config, make, gcc.

Warning

Ubuntu has fuse2 packages incompatible with important GUI (and other) packages. Installing them may break your system. Please use fuse3.

Ubuntu and Ubuntu-based distros (like Linux Mint):

apt install libfuse3-dev libglib2.0-dev

Archlinux and Archlinux-based distros (like Manjaro):

pacman -S fuse3 glib2

To compile playlistfs, it is enough to run make (or make bin) in its directory:

make # Compile with libfuse3 (recommended)
FUSE=2 make # Compile with libfuse2
# If something is messed up, remaking may help:
make remake

If you want to also generate a very simple man page, run make man (this requires help2man and gzip).

All artifacts and supplementary files are stored in dist/ directory.

Testing

You can run tests using any Bourne shell:

make test

make test recompiles the binary automatically before testing. make test-current can be used to run tests without recompilation.

Installing

Quick install of the whole package:

make install-full

Installation can be done in several steps:

• make install will install the compiled binary and man page;
  • make install-bin and make install-man install binary and man page separately;
• make install-supplementary will install MIME definitions, auto-mounting script and .desktop file for it;
  • make install-mime-package installs only MIME definitions;
• make install-set-default will register the auto-mounting script as the default handler for .playlist files. It is recommended not to run this with sudo.

By default, files are installed in ~/.local tree. This can be changed by supplying a PREFIX variable to invocation of make:

PREFIX=/usr make install
# XDG_DATA_HOME is also respected if set
make install-supplementary
make install-set-default

Note

~/.local/bin is usually not in PATH, so installed executables won't be found. Either add it to PATH in your shell profile file or install system-wide.

Everything can be uninstalled using make uninstall-full or more specific targets corresponding to parts that you want to uninstall (except install-set-default which has no uninstall counterpart).

Usage

If you have a compiled binary, and your system has separate development packages, those aren't needed to just run playlistfs.

For example, on Ubuntu it is enough to install libfuse3-3 and libglib2.0-0t64.

Note

Check all options with playlistfs --help-all. Options that are passed along to FUSE are not shown with plain --help.

Playlist files

Playlist file format is inspired by M3U and is extremely simple:

• Completely empty lines (not even with spaces) are ignored.
• If a line contains any characters (besides new line), it is considered a file path:
  • if the line starts with '/', it is an absolute path,
  • otherwise, it is a path relative to the directory in which playlist is located.
• Currently, a line starting with '#' is considered a file path.

This file format allows for almost any character to be used in paths, except for new lines (LF, 0xA).

Example playlist (referred to as example.playlist later):

file1
../bin/program
/etc/default/keyboard
documents/file1

This playlist contains one absolute path (/etc/default/keyboard), other paths are relative. Note that documents/file1 shadows the earlier file1.

Mounting on command line

When using command line, it is possible to specify files to mount in several ways. The user can specify several playlists and individual files to include in the mounted file system. When encountering several paths with the same basename, later paths take precedence, and individual files take precedence over files in playlists. It is not possible to add directories, except as symlinks.

Example of command line use:

playlistfs lists/example.playlist --file ~/keyboard --symlink /etc/mtab --file program ~/mount_point

This will mount a directory at ~/mount_point with following files:

• file1 : <current directory>/lists/documents/file1
• keyboard : /home/<user>/keyboard
• mtab → /etc/mtab (a symbolic link)
• program : <current directory>/program

By default, files are presented as regular files to make copying in file managers easier. Supplying --symlinks/-S option presents all files as symbolic links.

Unmounting can be done with fusermount program, which is provided by FUSE, or umount:

fusermount3 -u ~/mount_point
# or
umount ~/mount_point

Automatic mounting

PlaylistFS comes with text/x-playlistfs-playlist MIME type. It is defined by *.playlist glob. Corresponding definition is installed by make install-supplementary. make install-set-default will also register the provided handler as default.

If a default handler is registered, it is possible to automatically mount and unmount playlists. This is done by 'opening' .playlist files in file manager. Provided handler script will create an empty directory, with name formed by removing .playlist extension from the file and adding " playlist", and mount this playlist there. If the directory already exists, it will be unmounted and deleted instead. Note that a non-empty directory will not be removed if it happens to be named like the playlist, and the automatic mounting will not work.

After mounting

PlaylistFS does not allow creating any new files (as they would not have any backing file) or directories (not supported in general). However, symbolic links can be created, as they follow the intended semantics.

Additionally, new hard links can be created (see ln) and files can be deleted.

License

PlaylistFS, Copyright ® 2018-2026 Alexander Bulancov

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

See LICENSE for more information.