Good point, Gabriel.

I think you should still use %V for ISO-8601 week. Man page for strftime says %V is the ISO 8601 week number (even though %W stars on Monday, too).

You can test your calendar.txt implementation by generating a sample file. I have the correct output file from 1700s to 2400s in https://terokarvinen.com/2024/format-date-calendar-txt/

When testing any calendars - my own, companies', calendar.txt, other types - I often find mistaken edge cases.

— Tero Karvinen, 2026-02-28

Thanks for the answer, Tero.

I imagine that there is a little mistake here. In ANSI C, the strftime function approaches the time formatting differently of languages mentioned in your link. According to the second edition of K&R book, the %W already indicates week numbers starting from Monday. Furthermore, the formatting character sequence that aims the Sunday as first week day is the %U sequence, not %W.

Happy hacking for you too!

— Gabriel P. Alves, 2026-02-26

Hi Gabriel,

Happy to see you are working on Calendar.txt tooling!

I had a quick look at your code https://codeberg.org/agap/gencal/src/branch/main/main.c

ISO-8601 week numbers are %V - not %W that starts on Sunday. You can see some ready made format strings for different languages in my articles https://terokarvinen.com/2024/format-date-calendar-txt/

I did not check the loops in detail, but some indexes look like the edge cases should be tested.

Happy hacking!

— Tero Karvinen, 2026-02-23

Greetings again, Tero. I would like to contribute to your idea by sharing here for future readers the ".txt" calendar generator that I developed and currently use. So, below is the link to "gencal", my configurable calendar generator: https://codeberg.org/agap/gencal.

— Gabriel P. Alves, 2026-02-22

"The simplicity is the characteristic of all creative ideas" ~ Dimnet, Ernest

Thanks Tero, this convention is undoubtedly simple and useful. And, I think that it should be taught in schools...

— Gabriel P. Alves, 2026-02-12

Thanks for this wonderful tool! I read in the comments (@GESU) that there is a bash script to sync the file with khal. If someone could give the link or the code, that would make my day! I need to share my calendar with not so geeky people…

— Hyo, 2026-01-15

Happy to hear that, @neezer!

For multiday events, I mark start and end.

2025-08-01 w01 Fri 23:00 Takeoff

2025-08-02 w01 Sat 06:00 Landing

For multiday events, I sometimes make a plustag and mark it on each day. E.g. "Foobar days" +fd.

— Tero Karvinen, 2025-08-27

Awesome spec!

I'm having trouble figuring out how you'd log a single event with start and end times that span multiple days. For example, a red-eye flight that takes off at 2025-08-01 w01 Fri 23:00 and lands 2025-08-02 w01 Sat 06:00?

— neezer, 2025-08-26

Good examples, @GESU. Some thinking is indeed required for finding a good solution for those. A good solution would be obvious when read, based on an existing standard (ISO-8601), and would priorize common everyday case over a special edge case.

— Tero Karvinen, 2025-05-03

Hello again, my apologies for that deficient examples in my last comments.

1. First case, start time and end time (04:00 to 05:00)

2025-05-02 w18 Fri 04-05 Correct my comments.

2. Second case, start time without time zone (04:00)

2025-05-02 w18 Fri 04 Correct my comments.

3. Third case, start time(04:00) with timezone CDT on ISO_8601(-05:00)

2025-05-02 w18 Fri 04-05 Correct my comments.

4. Fourth case, start time(04:00) and end time(05:00) with time zone CDT on ISO_8601(-05:00)

2025-05-02 w18 Fri 04-05-05-05 Correct my comments.

The first case and the third case maybe can be confusing, so similar, maybe an alternative start and end time separator?

PD=This is amazing, I known of your proposal for a while, but now I will be using it, and there are a simple mode to sync with regular calendars formats with Khal, just a simple script.

Calendar.txt -> Bash -> Khal -> "Any Sync method" -> Other Calendars Apps

I'm using this structure on other types of data too, just testing for now.

— GESU, 2025-05-02

@GESU, good catch. Timezone is secondary to more common meanings. So 2025-05 is May 2025. Calendar.txt is human first, so I wish to make it practical. Maybe even challenge a paper calendar.

At least that's how I've used calendar.txt. Should I add it to this page describing calendar.txt?

A plan for a whole month could be quite common: "2025-05 Prepare for marathon". Timezone probably would not matter for monthly plans.

Calendar.txt always starts dates with year, so "05-04" is not a possible date format. Calendar.txt date would be "2025-05-04 w18 Sun".

End time without start time would be quite rare, for example "-16:20". I have never had a case of "end date without startdate, with non-default timezone on the end date, negative time zone". Maybe it could be "-16:20-05:00". I agree that the syntax would be unwieldy, but maybe it would be fine for a case as rare as this.

— Tero Karvinen, 2025-05-02

Problem in timezone ISO_8601, example: CDT (-05), in start time is timezone or end time??

without endtime (22:00 CDT)

2200-05 Write a comment.

with endtime but no time zone (04:00 - 05:00)

04-05 Check if I have response in the comments.

— GESU, 2025-05-02

@Rain - I highly recommend standard ISO 8601 dates, especially week numbers. But calendar.txt is your calendar, so of course you should set up the dates so that they match your requirements. For example, working in an environment that uses obsolete week number calculations can for you to use those, too.

Here are some scripts for generating calendar.txt dates in multiple languages:

https://terokarvinen.com/2024/format-date-calendar-txt/

— Tero Karvinen, 2025-04-18

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

I presume the program can be tweaked to suit your definition of week-of-year ;)

— Rain, 2025-04-13

I've used a similar format for many years, but with a twist.

I use a .CSV file with these cols:
YEAR,MONTH,DAY,EVENT

Repeating events are represented by Asteri - *
*,*,15,{$} Sewer
*,02,02,{h} Groundhog Day

I then wrote a program to convert one month of that data to .ICS so I could upload to Google Calendar.

I think I may incorporate some of your ideas.

— Ralph, 2025-03-07

Great tool/idea, but the definition for "week of year" differs by country, which makes the pre-defined calendar for some user hard to use. Any options to create a different file?

— Arne, 2025-03-07

In your "Tips and Tricks" examples, the string 'ke' appears where you said the "Aaa" day-of-week would appear. What day of the week is 'ke' ?

In "Rules" you said "Optional weekly goals / Syntax makes weekly goals sort alphabetically before days / date "·" weeknumber "··" goal string". But GNU coreutils sort will put "Vacation week" after "Mon" even if I use two spaces.

— Mozai, 2025-02-24

@kinghezy, that's indeed pretty smart. It's surprising that indeed, your recurring events are both using the most obvious words and sort to time order.

— Tero Karvinen, 2023-03-05

I've recently gotten into use todo.txt and markdown so the remaining thing that I hadn't figured out was calendars. Your idea seems like it will work. I see someone had asked about how to handle recurring events. I think the following below will work for me, in (a) allow recurring by week/year and (b) fitting with the sorting that is used for alphanumeric.

2033-06-09 w23 Thu
2033-06-10 w23 Fri
2033-06-11 w23 Sat
2033-06-12 w23 Sun
week Fri Kids Laundry
year 06-09 Someone's birthday
year 07-18 Another birthday

— kinghezy, 2023-03-04

That's an interesting script, Thomas. I'm happy to see something like this.

Did you just make the first event adding script to calendar.txt? Congratulations!

Myself, I write the events using a text editor, but read, summarize and collect events using scripts. However, I use apps and scripts with todo.txt daily.

Happy to see your script!

— Tero Karvinen, 2022-06-03

Hello,

I really enjoy the calendar.txt idea! For me, manual editing
was not that convenient though, so I came up with a little script. I hope it might be useful for others too.
https://gitlab.com/ThomasHastings/text-calendar

Best,
Thomas

— Thomas Hastings, 2022-06-03

Michael Phillips, thanks for the question. Calendar.txt can be sorted, because ISO-8601 dates are sortable. That is, each line starts with year-month-date, so a plain 'sort' will chronologically order the file.

For plans considering whole year, the whole-year plan is alphabetically sorted before the details (daily plans). Same for big plans for century, decade, month or a week.

You can grep by year and week if you want to, 'cat calendar.txt|grep 2022|grep w03'.

— Tero Karvinen, 2022-05-24

I would like to make a recommendation of putting the week of the year after the year so that the file can be sorted. This will also make grepping you file easier if your file is longer than a year.

— Michael Phillips, 2022-05-23

Thanks Ken and Danny! Having used this for a year, I have enjoyed it myself, too.

Taro, you asked about repeating tasks. I have a lot of repeating tasks, such as courses that run for 8 or 16 weeks. I just give them a shorthand (such as +pt for penetration testing), and then copy this to each week. Later, it's very easy for me to add details. For the last week, I might update it to "+tt evaluated lab 5 hours". For me, this is much faster than setting up recurring events in some other calendar systems.

For repeating tasks that go on indefinitely, such as brushing teeth, jogging and taking out the trash, I would use a separate week plan and not put it on my calendar.

— Tero Karvinen, 2022-01-17

Thank you for putting this up -it's really helpful!
I wanted to do daily notes as a record and with this I don't need to enter a new date each day.

— ken jacobsen, 2022-01-10

Extremely good way to keep on track of most things. I don't know if you should use it with todo.txt or alone but it's a good way to simplify your calendar AND todo.

I have one question, how would you handle repetitive task? For example, throwing the trash every 4 days?

— Taro, 2021-04-11