From 9e4e1295eddc5c717723bb8f6a772eaeda9357dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Moritz=20B=C3=B6hme?= <mail@moritzboeh.me>
Date: Sun, 23 Feb 2025 17:15:04 +0100
Subject: [PATCH] docs: Add comprehensive README with usage, installation, and
 examples

---
 README.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5082c30
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+# 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:
+
+```bash
+filetags list "document -- tag1 tag2.pdf" "notes -- tag2 tag3.txt"
+# Output:
+# tag1
+# tag2
+# tag3
+```
+
+#### Add Tags
+Add one or more tags to files:
+
+```bash
+filetags add --tag=work --tag=draft document.pdf
+# Result: document -- draft work.pdf
+```
+
+#### Remove Tags
+Remove specified tags from files:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+# 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