Calendar.txt

Keep your calendar in a plain text file.

Calendar.txt is versionable, supports all operating systems and easily syncs with Android mobile phone.

How do I use calendar.txt? Open calendar.txt in any text editor and start filling in your events.

Example Calendar.txt

I've used calendar.txt for a while, and now I want to share it. Your new calendar in plain text:

2021-02-15 w07  Architecture week
2021-02-15 w07 Mon  9-12 project groups. 17 jogging. 
2021-02-16 w07 Tue  9-11 John 12-16 architecture meeting
2021-02-17 w07 Wed  8-14 +lp. 14:15-16 +mp
2021-02-18 w07 Thu  write out architecture
2021-02-19 w07 Fri  12-13 board
2021-02-20 w07 Sat  
2021-02-21 w07 Sun  10 ski with N
2021-04  Grand rollout
2022  The year of foobar

So it's

YYYY-MM-DD wWW Aaa  HH event. HH-HH another event.

Benefits of plain text calendar

Simple. Your meetings and schedules are valuable. With calendar.txt, you know you what you wrote. You don't need to let "smart" calendar programs mangle your timezones.

Use your favourite editor. You can edit plain text with nano, vim, emacs, micro, gedit, mousepad, notepad, joe...

Future proof. You can open a text file in 2039.

Versionable. It's plain text, you can keep it in git. You can easily take diff, as it's one day one line.

Unix philosophy. It's one day, one line. You can grep (only show lines).

Sortable. When sorted in alphabethical order, the dates start from older and advance to future. Optional weekly goals are sorted at the start of each week.

Mobile friendly. For Android, you can synchronize your calendar.txt with Syncthing. For desktops and laptops, you can also use git.

What week is that? No more mixups between dates (2021-02-14) and week numbers (w06). In calendar.txt, week numbers are on the same line, ready for copying.

Future is yours. For tomorrow, you want to know the hours. For the next year, you can plan the months. For five years, you can plan the years.

Tips and Tricks

Calendar.txt supports Unix philosophy on any platform. One line, one thing (day or goals).

Show all instances of Linux Basics course. The course is called "Linux perusteet" and the tag is +lp

$ grep +lp calendar.txt
2021-01-27 w04 ke       8-1345 +lp cli-sudo-apt; 14:15-1545 +mp groups and themes
2021-02-03 w05 ke       8-1345 +lp apache; 1415-1545 +mp
2021-02-10 w06 ke       8-1345 +lp vps+dns; 14-1545 +mp my groups
2021-02-17 w07 ke       8-1345 +lp flask; 1415-1545 +mp my groups
2021-03-03 w09 ke       8-1345 +lp bash-db; (14-1545 +mp); 1530 FxBar
2021-03-10 w10 ke       8-1345 +lp recap; (14-1545 +mp)
2021-03-17 w11 ke       8-1345 +lp final lab; (14-1545 +mp)

Only show March 2021 events for the course

$ grep +lp calendar.txt|grep 2021-03
2021-03-03 w09 ke       8-1345 +lp bash-db; (14-1545 +mp); 1530 FxBar
2021-03-10 w10 ke       8-1345 +lp recap; (14-1545 +mp)
2021-03-17 w11 ke       8-1345 +lp final lab; (14-1545 +mp)

Show both todos and calendar events for this course

$ grep +lp calendar.txt todo.txt
2021-03-17 w11 ke       8-1345 +lp final lab; (14-1545 +mp)
...
@N add article on Flask to +lp reading list

I'm physically going to work tomorrow. Do I have any tasks or events? Let's search by @W (at work) context

$ grep @W calendar.txt todo.txt

Download ready made calendar

Download calendar.txt template. It has ready made calendar events until 2033. Feel free to copy just the part you need, such as half a year.

Rules

One thing per line
- One day per line
- Optional goals for week, month and year are single line
Line contains (2021-02-14 w06 Sun 8-12 some event. 13 other event)
- ISO-8601 date (2021-02-14)
- ISO-8601 week number (w06). Standard week starts on Monday.
- Weekday abbreviation (Sun)
- Date separator, two spaces (" ")
- Daily events in earliest first order
Daily event
- Start time in 24 hour clock, (08:15)
  - Optionally, can be abreviated to just hour (8)
  - Optionally, hour-minute separator colon ":" can be left out (0815)
- Optional dash and ending time (-12:00)
  - Optionally, cab be abreviated to just hour (12)
  - Optionally, hour-minute separator colon ":" can be left out (1200)
- Text of the event ("Mike")
  - Optionally, can use plus tags ("+pt" for penetration testing course)
- Daily event ends with full stop "."
  - Optionally, full stop after last event of the day can be left out.
Optional weekly goals
- Weekly goals appear before dates of that week
  - Syntax makes weekly goals sort alphabetically before days
- Just like day lines, except without weekday abbreviation ("2021-02-15 w07 Architecture week")
  - ISO-8601 date (2021-02-14)
  - ISO-8601 week number (w06)
  - Date separator, two spaces (" ")
  - Weekly goals
Airport time: all times are local to the place of the event, unless timezone is marked
- E.g. local time: "12:00 Tero, Helsinki Cafe" is Helsinki time, "10:00 Westminster U cafe" is London time.
- E.g. with timezone: 0600Z Call ABC123
File format
- Encoding should be UTF-8
- File name is "calendar.txt"
Optional monthly goals
- Line starts with year and month in ISO-8601 format YYYY-MM ("2021-04")
- Date separator, two spaces (" ")
- Goals as text
Optional yearly goals
- Line starts with year ("2022")
- Date separator, two spaces (" ")
- Goals as text
Optional plus tags (+tag)
- You can add tags to any free text portion: daily events; weekly, monthly and yearly goals
- Tags can be used for repeating events (+pt for pentest course), grand projects (+phd) or any other purpose you like
Optional contexts (@Work, @E, @N)
- Some tasks require you to be in a specific place, with specific tools: running errands, being at work, being on a computer with Internet...

Rationale for some rules

Two spaces " " as date separator: many Android keyboards and editors make it slow to type tabs, but fast to type spaces. To make this unique and different from single space, two spaces is the minimum number of keystrokes.

Dates applying ISO-8601 standard YYYY-MM-DD: It's unambiguous. ISO-8601 dates sort nicely. Making the date part shorter for weekly, monthly and yearly goals makes also those goals sort correctly. And if you're a poster child of planning your life, you can easily make goals for a decade "202 PhD" or a century "20 World domination".

Week numbers near date. I need both date 2021-02-14 and week number w07. If I have to click around calendar UI to get them, week numbers and dates get mixed up. In calendar.txt, I can copy paste the whole thing "2020-02-14 w06 Sun".

Plus tags. Tags make it very fast to pick events with grep. Plus tags are already used with todo.txt. The other obvious alternative would be #hashtags, but as hash "#" is the comment character in bash shell, it would make many commands slower by requiring quoting.

Contexts, @W, @Work. Many of us spend most of their lives in 2-3 places. Why not give these places shorthand? Contexts are also marked this way in todo.txt, so it's convenient to use compatible syntax. You can, for example, pick all @W (work) events in both your calendar.txt and todo.txt.

Airport time. Having a "smart" calendar synchronization fiddle with your dates can really ruin your day. Calendar.txt follows "you wrote what you wrote" philosophy. Also, it's often expected that if you meet at a cafe in Helsinki at ten, that's local time. In the rare event you wish to use other timezones, such as Z (UTC) time, it's possible to mark it.

Having Mondays date in weekly goals. Some people use week numbers, others don't. So a common question would be: "w07, when does it start?". You have your answer already at hand. Also, this results in weekly goals sorting correctly in alphabetical sorting.

Downloads

To use calendar.txt, you just need to know the idea.

For your convenience, you can download a ready-made calendar.txt template with days and week numbers.

Download calendar.txt template

You're not going to need it before 2033, but here is the short go program to generate calendar.txt templates.

Links

http://todotxt.org/ Keep your todo list in a plain text file. Compatible with Getting Things Done (GTD). I have used this for a long time, it was one of the inspirations behind calendar.txt.

https://syncthing.net/ Synchronize files to Android. No central servers required, end to end encryption. Works nicely with todo.txt and calendar.txt. Download Syncthing from F-Droid.

https://f-droid.org/en/packages/net.gsantner.markor/ Markor, a text editor for Android.

https://micro-editor.github.io/ Micro, a text editor for Linux, Windows and Mac.

Obviously, you can use calendar.txt on any operating system with any text editor.

Adminstrivia: This article has been updated. Fixed some more typos in 2023-05-21 w20 Sun.