agendafs
A filesystem for your calendar.
git clone git://mccd.space/agendafs| Log | Files | Refs | README | LICENSE | Mail | Website |
README.md (5932B)
1 # agendafs
2
3 [Homepage](https://agendafs.website)
4 | [Todo](https://todo.sr.ht/~marcc/agendafs)
5 | [Mailing List + Patches](https://lists.sr.ht/~marcc/agendafs)
6
7 
8
9 Agendafs is a FUSE-based filesystem for writing notes. It creates a shim over [vdir storages](https://pimutils.org/specs/vdir/), allowing you to write notes as regular files and synchronize them back to a caldav server. It supports directories, categories, arbitrary metadata and access rights.
10
11 ## Status
12
13 Agendafs is still in early development and is alpha-level software. It
14 probably leaks memory, destroys files and might summon demons. However, I
15 use it daily for my note-taking mostly without issues. If you try it out,
16 I recommend creating a new calendar specifically for agendafs and also
17 regularly backing up your notes elsewhere.
18
19 ## Installation
20
21 Prerequisites: scdoc (man pages), C compiler (currently only tested with
22 gcc), libfuse, libuuid, libical and pkg-config. Optionally a `shell.nix`
23 exists which sets up all dependencies for you.
24
25 Some fields, such as categories, are accessed via xattributes (xattr(7)), for that you will need to have the xattribute utilities installed.
26
27 You also need to setup a tool that syncs vdir storages to a caldav server, like
28 [vdirsyncer](https://vdirsyncer.pimutils.org/en/stable/when.html#) or [pimsync](https://sr.ht/~whynothugo/pimsync/).
29
30 To build:
31
32 ```
33 git clone https://sr.ht/~marcc/agendafs/
34 cd agendafs
35 make
36 make install
37 ```
38
39 ## Basic Principles
40
41 Agendafs uses a [vdir storage](https://pimutils.org/specs/vdir/) as a backend
42 to allow users to sync VJOURNAL entries to a remote caldav server.
43
44 Agendafs scans the vdir directory for VJOURNAL entries to populate the
45 file tree. Each VJOURNAL entry is represented as a file or directory in
46 Agendafs. Edit these files like you would on a regular filesystem. Some
47 VJOURNAL attributes can also be accessed via xattr(7), for example categories
48 a.k.a. tags. The full list of supported user attributes can be found in the
49 manpage.
50
51 Agendafs pairs well with file explorers like `ranger`, `lf` or `nnn`.
52
53 ## Usage
54
55 To mount a vdir storage with Agendafs:
56
57 ```
58 mount.agendafs -o vdir=<vdir directory> <mountpoint>
59 ```
60
61 See [agendafs(8)](https://git.sr.ht/~marcc/agendafs/blob/main/agendafs.8.scd) and [agendafs-examples(7)](https://git.sr.ht/~marcc/agendafs/blob/main/agendafs-examples.7.scd) for a full list of options and examples.
62
63
64 ### Limitations
65
66 Some major features are missing before a beta release:
67
68 - [Attachment support is missing](https://todo.sr.ht/~marcc/agendafs/2)
69 - [Symlink support is missing](https://todo.sr.ht/~marcc/agendafs/11)
70
71 Depending on the caldav server, there might be limitations as to how big
72 a file can be. Usually the limit of one entry is ~5MB, but agendafs does
73 currently not enforce any file size limit.
74
75 ## Motivation
76
77 Note-taking tools like Obsidian and Logseq have great syncing capabilities,
78 but they restrict you to only those editors. I wanted a solution that is
79 more Unixy, and allow me to use my favorite CLI tools. Plain-text notes
80 seemed like the obvious solution, but I struggled to find a good solution
81 for syncing and editing notes on other devices. Caldav makes for a great
82 place to store notes, since many already have a provider. Storing notes in
83 ical-format means that I can also take advantage of mobile apps for editing
84 my notes, such as jtx Board on Android.
85
86 Agendafs also have some features that are too unergonomic on regular
87 filesystems. It makes full use of Xattributes to store categories,
88 classification (public vs private) and any other arbitrary metadata to the
89 file. This means that it frees you from just using one file-format while
90 still giving you capabilities to link notes, either via directories or
91 via categories (sibling linking exists in the ical spec, but this is not
92 supported yet). This also makes it easy to pair Agendafs with CLI tools,
93 file explorers like nnn, lf, ranger and also editors like Kakoune and Neovim. For example, you could easily extend `lf` to show if a file is draft or not.
94 I documented in [examples] what this might look like
95
96 Of course, you can also ignore those features and just use Agendafs
97 as a way to just backup your [todotxt](http://todotxt.org/) or
98 [jrnl](https://jrnl.sh/en/stable/).
99
100 ## Appendix
101
102 ### VJOURNAL support in Nextcloud calendars
103
104 To have vjournal support on Nextcloud, I needed to create the calendar manually. This is probably also required if you use Fastmail.
105
106 ```
107 curl -X MKCALENDAR \
108 -u me:me \
109 -H 'Content-Type: application/xml; charset=utf-8' \
110 -d "<?xml version='1.0' encoding='UTF-8'?>
111 <mkcalendar xmlns='urn:ietf:params:xml:ns:caldav'>
112 <set>
113 <prop>
114 <displayname xmlns='DAV:'>Journal</displayname>
115 <calendar-description xmlns='urn:ietf:params:xml:ns:caldav'>Calendar with VJOURNAL support</calendar-description>
116 <supported-calendar-component-set xmlns='urn:ietf:params:xml:ns:caldav'>
117 <comp name='VEVENT'/>
118 <comp name='VTODO'/>
119 <comp name='VJOURNAL'/>
120 </supported-calendar-component-set>
121 </prop>
122 </set>
123 </mkcalendar>" \
124 'https://my-nextcloud-server/remote.php/dav/calendars/me/journal'
125 ```
126
127 ### Find files by category with nnn
128
129 Add the following function to your profile to search your notes files with a matching category.
130
131 ```sh
132 find_by_category() {
133 category=$1
134 if [ -z "$category" ]; then
135 echo "Usage: find_by_category <category>" >&2
136 return 1
137 fi
138
139 find . -type f | while read -r file; do
140 fullpath=$(realpath "$file")
141 value=$(getfattr --only-values -n user.categories -- "$file" 2>/dev/null)
142 case $value in
143 *"$category"*)
144 printf '%s\0' "$fullpath"
145 ;;
146 esac
147 done
148 }
149 ```
150
151 Usage: `find_by_category MY_CATEGORY | nnn`
152
153 ### Why C?
154
155 I started this project to improve my C skills.
156
157 [examples]: https://git.sr.ht/~marcc/agendafs/blob/main/agendafs-examples.7.scd