agendafs

A filesystem for your calendar.

commit 68d736a30ab67c18fff6420c12c161e4036779e2
parent 946d532f554afc6e932364d2aae5e77d392b9854
Author: Marc Coquand <marc@coquand.email>
Date:   Thu, 10 Jul 2025 00:04:36 +0200

README

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

1 file changed, 20 insertions(+), 41 deletions(-)
diff --git a/README.md b/README.md
@@ -1,58 +1,37 @@
 # agendafs
 
-Status: Works but unstable, probably leaks memory. Still missing features. I
-dogfood it and it works decently for me.
+`agendafs` is a FUSE-based filesystem for writing notes that syncs to
+ical-backends using [vdirsyncer](https://vdirsyncer.pimutils.org/) or
+similar tools.
 
-`agendafs` is a FUSE-based filesystem written in C that works with
-[vdirsyncer](https://vdirsyncer.pimutils.org/) to allow you to sync your
-notes to caldav.
+## Installation
 
-Once you have a directory with ics entries, you can mount them with agendafs
-like so:
+Prerequisites: C compiler, libfuse, libuuid, libical and pkg-config
 
-```
-$ mount_agendafs -o icsdir=/home/me/.calendars/my-calendar /mnt/local-journal
-```
-
-Now your `.ics` files are available as readable plain-text files in
-`/mnt/local-journal`.
-
-## Dependencies
-
-Some C compiler along with libfuse, libuuid, libical and pkg-config.
-
-Right now you also need a tool that syncs .ics files with a caldav server,
-like [vdirsyncer](https://vdirsyncer.pimutils.org/en/stable/when.html#).
+You also need a tool that syncs .ics files with a caldav server, like
+[vdirsyncer](https://vdirsyncer.pimutils.org/en/stable/when.html#).
 
-## Building
+To build:
 
 ```
-$ make
+git clone https://sr.ht/~marcc/agendafs/
+make
 ```
 
-## Using
+## Basic principles
 
-1. Set up a new calendar with VJOURNAL support. See below for how its done in Nextcloud.
+Agendafs uses [vdirsyncer](https://vdirsyncer.pimutils.org/) as a backend to sync iCalenar files to a remote caldav server.
 
-2. Set up [vdirsyncer](https://vdirsyncer.pimutils.org/en/stable/installation.html).
+Each iCalendar entry (currently VJOURNAL only) is represented as a file or directory in Agendafs. Edit these files like you would on a regular filesystem. iCalendar entries that have a parent relationship are represented as directories. iCalendar attributes can also be accessed via xattr(7). Currently the only exposed xattribute is `user.categories`.
 
-3. You will now have a directory with your VJOURNAL entries mounted. Locate the one that you are going to use for journals.
+## Usage
+
+To mount an iCalendar directory with Agendafs:
 
 ```
-$ mkdir /tmp/journal
-$ mount_agendafs -o icsdir=/home/me/.calendars/my-journal /tmp/journal
-$ $EDITOR "/tmp/journal/My first note"
+mount_agendafs -o icsdir=<vdirsyncer_directory> <mountpoint>
 ```
 
-You can interact with it mostly like any other filesystem, and so agendafs
-pairs very well with [nnn](https://github.com/jarun/nnn), [lf](https://github.com/gokcehan/lf) and more.
-
-`agendafs` also levarages `xattr(7)`. It exposes the following properties:
-
-- `user.categories`
-
-See [TODO](https://todo.sr.ht/~marcc/agendafs) for current status.
-
 ### Limitations
 
 Right now attachments are not supported, I don't quite know what happens if you store a file but the behavior is undefined.
@@ -85,10 +64,10 @@ apps. However, the format is not particularly human-friendly. For example, VJOUR
 
 These are not really intended to be edited by users.
 
-## Planned features
-
-See also [todo tracker](https://todo.sr.ht/~marcc/agendafs)
+## Contributions
 
+See [tickets](https://todo.sr.ht/~marcc/agendafs) and [mailing
+list](https://lists.sr.ht/~marcc/agendafs)
 
 ## Appendix