filetags-rs

A command-line tool for managing tags in file and directory names. Tags are embedded directly in filenames using a specific delimiter pattern.

Installation

This is a nix flake :)

Usage

Tags in filenames use the following format:

filename -- tag1 tag2 tag3.ext

Where:

• Tag delimiter is -- (space, double dash, space)
• Tags are separated by spaces
• Tags are stored in alphabetical order
• Tags cannot contain spaces, NUL, ":", or "/"

Commands

List Tags

List all unique tags found in the specified files:

filetags list "document -- tag1 tag2.pdf" "notes -- tag2 tag3.txt"
# Output:
# tag1
# tag2
# tag3

Add Tags

Add one or more tags to files:

filetags add --tag=work --tag=draft document.pdf
# Result: document -- draft work.pdf

Remove Tags

Remove specified tags from files:

filetags remove --tag=draft "document -- draft work.pdf"
# Result: document -- work.pdf

Create Tag Tree

Create a directory tree with symlinks based on file tags:

filetags tree --dir=./tagged --depth=2 "document -- tag1 tag2.pdf"

This creates a directory structure like:

tagged/
├── document.pdf -> /path/to/document -- tag1 tag2.pdf
├── tag1/
│   ├── document.pdf -> /path/to/document -- tag1 tag2.pdf
│   └── tag2/
│       └── document.pdf -> /path/to/document -- tag1 tag2.pdf
└── tag2/
    ├── document.pdf -> /path/to/document -- tag1 tag2.pdf
    └── tag1/
        └── document.pdf -> /path/to/document -- tag1 tag2.pdf

Shell Completions

Generate shell completions for your preferred shell:

# For fish shell
filetags completion fish > ~/.config/fish/completions/filetags.fish

# For bash
filetags completion bash > ~/.local/share/bash-completion/completions/filetags

# For zsh
filetags completion zsh > ~/.zsh/completions/_filetags

Error Handling

The tool provides clear error messages for:

• Invalid characters in tags
• Empty tags
• Missing arguments
• File permission issues
• Symlink creation failures
• Directory creation failures

License

GPL-3.0-or-later