agendafs

A filesystem for your calendar.

commit 3128a0db1cfa346329d22ac74294542d90cd5aa5
parent 285439b534100ff0fa53eaabb2411a04fe151bcf
Author: Marc Coquand <marc@coquand.email>
Date:   Fri,  1 Aug 2025 11:38:44 +0200

README

Diffstat:
M
README.md
 | 
48
++++++++++++++++++++++++++++++------------------

1 file changed, 30 insertions(+), 18 deletions(-)
diff --git a/README.md b/README.md
@@ -35,11 +35,16 @@ make install
 
 Agendafs uses a [vdir storage](https://pimutils.org/specs/vdir/) as a backend to allow users to sync VJOURNAL entries to a remote caldav server.
 
-Each VJOURNAL vdir entry is represented as a file or directory in Agendafs. Edit these files like you would on a regular filesystem. VJOURNAL entries that have a parent relationships are represented as directories. Some VJOURNAL attributes can also be accessed via xattr(7). Currently supported attributes are:
+Each vdir entry is represented as a file or directory in Agendafs. Edit these
+files like you would on a regular filesystem. VJOURNAL entries that have a
+parent relationships are represented as directories. Some VJOURNAL attributes
+can also be accessed via xattr(7). Currently supported attributes are:
 
 - `user.categories` - comma separated list of categories
 - `user.class` - Can be either private, public, confidential.
 
+You can also store arbitrary data.
+
 Agendafs pairs well with file explorers like `ranger`, `lf` or `nnn`.
 
 ## Usage
@@ -60,29 +65,36 @@ Some major features are missing before a beta release:
 - [Attachment support is missing](https://todo.sr.ht/~marcc/agendafs/2)
 - [Symlink support is missing](https://todo.sr.ht/~marcc/agendafs/11)
 
+Depending on the calendar you use, there might be limitations as to how big
+a file can be. Usually the limit of one entry is ~5MB, but agendafs does
+currently not enforce any file limit.
+
 ## Motivation
 
 Note-taking tools like Obsidian and Logseq have great syncing capabilities,
-but they restrict you to only those editors. Tools like Syncthing offers file
-syncing between devices, but require you setting up a private cloud if you want
-to backup to a remote server. Most people are signed up to an email provider,
-and thus probably already have a caldav server for their calendar. Agendafs
-leverages that as a server to sync notes, and any tool that takes advantage
-of VJOURNALs can access those notes.
-
-Agendafs also has a few other advantages to other note-taking tools. Other
-note-taking tools tend to work only on a single file-format, like Markdown or
-Org-mode. They leverage tags, frontmatter metadata or properties to link notes,
-which they store within the file-content itself. This has some advantages,
-but also restrics you to those particular file-format. With Agendafs, you can
-store metadata in xattributes: categories (tags), classifications (public
-vs private) or any other arbitrary data. Since Agendafs is a shim over vdir
-storages, those attributes are easily backed up, which normally is not the
-case with xattributes on other file systems.
+but they restrict you to only those editors. I wanted a solution that is more
+Unixy, allowing me to combine tools and build automation on top. However,
+when I stored my notes in plain-text, I struggled to find a good solution
+for syncing and editing notes on other devices. Since I had signed up to an
+email provider, and thus had a caldav server for my calendar, I thought it'd
+be a great place to store my notes. Storing notes in ical-format means that
+I can also take advantage of mobile apps for editing my notes, such as jtx
+Board on Android.
+
+Agendafs also takes advantage of Xattributes to store categories (aka tags),
+classification (public vs private) and allows you to store arbitrary metadata
+to the file. This means that it frees you from just using one file-format
+while still giving you capabilities to link notes, either via directories
+or via categories (sibling linking exists in the ical spec, but this is
+not supported yet). This means Agendafs pairs well with CLI tools,  file
+explorers like nnn, lf, ranger and also editors like Kakoune and Neovim.
+
+Of course, you can also ignore all of that and just use Agendafs
+as a way to just backup your [todotxt](http://todotxt.org/) or
+[jrnl](https://jrnl.sh/en/stable/).
 
 ## Appendix
 
-
 ### VJOURNAL support in Nextcloud calendar
 
 To have vjournal support on Nextcloud, I needed to create the calendar manually. This is probably also required in Fastmail.