A plain-text file format for todos and check lists

With [x]it!, lexicographic sorting of lines works as well, as long as you stick to the following rules:

- Write due dates first (if you use due dates)

- Pad your priority with dots (if you use priorities)

- Don’t use line breaks within descriptions, so only single-line items

- Don’t use titles

That way, the lines will sort by checkbox status (open first), then by priority (highest first), and finally by due date (soonest first). For example:

    [ ] !!! -> 2022-05-01 Something
    [ ] ..! -> 2022-06-15 Something else
    [x] .!! -> 2022-01-04 More text

> grep and sort tasks to make sense of things

This.

grep + sort + awk = unbelievable single person task management effectiveness. And it was right under my nose all the while.

I've dumbed my version even further, I just use numbers. every line starting with 1 is highest Priority and so on.

another important piece i needed was a pointer to where i last left off. I just use double underscores "__". next time just open and search for 2 underscores and start right off.

Works everywhere.

> - doesn't support UTF-8 checkbox emoji

That's a good thing. Its also unicode, not utf-8. Your plugin can display it with a unicode character. Having a simple ASCII char set helps portability _a lot_. No benefit in supporting unicode code points.

> - doesn't support nested lists

If you can tick all items within a nested list, why bother writing it with dedicated TODO items? Additionally, you can just create more files for elaboration. Your file system is at your dispense. Additionally, that can be implemented in your plugin of choice. Goes with your first point in hand.

> - specifies a specific space character when a character class would be better

ASCII has no official character class. If your are refering to tabs; I don't think this is bad or good. Maybe you can follow uo on the use case..

> - not clear what "item must not contain blank lines" means

Probably that a blank line is used as a separator

> - description indentation limit of four space characters is a problem for nested items

I don't see why. The fixed amout of four characters obviously lines up to the start of the text from an item. This helps readability a lot. And is a simple standard for identation rules.

> - description supporting blank lines (properly indented) would be useful for longer descriptions

I disagree. A TODO list should be simple to grasp. Details and elaborations can be put in a dedicated directoy and refered to. Also, it is a _very bad_ idea to work with invisible lines. Users are dump and quick to judge.

> - date should support an ISO or other standard date format

This is the most portable standard, but extended for human editing..

> - timezone is necessary for events happening in specific timezones or across timezones

I tend to agree. But the person hosting the list should probably be the one defining the time zone. But I haven't read anythinf about time zones in the primer. Nothing stops one to simply append it to a time. No need for the standard to define such.

I think it is well put and the first one which checks all the boxes for me. Congratz to the author.

I don't see why such a comment is #1.

Thanks for sharing your notes. Nesting of items is not supported, although the idea has come up. It’s on hold right now – that’s mostly due to practical reasons, because it’s relatively hard to implement in tooling.

Allow me to clarify a few details regarding the spec:

- There can’t be any character before the checkbox. (An item “MUST start at the beginning of a line with a checkbox.”)

- A blank line is defined as “a line that is either empty, or that exclusively consists of blank characters”, and a blank character is defined as “a character from the Unicode Space Separator category (Zs)”. So the description text of an item (that can span multiple lines) cannot contain a line that’s all blank. Reason is that a blank or empty line separates item groups from each other, so allowing it to appear within descriptions could create visual ambiguity. (Even though it wouldn’t be ambiguous from a purely formal standpoint.)

- The format for dates is a subset of ISO-8601, except for the slashed variant (2020/12/31) that’s there for convenience, and the notation for quarters (2022-Q1).

Some of your comments are described in the extended syntax specifications[0].

[0]: https://xit.jotaen.net/syntax-guide

I do exactly the same, and also use a tilda for tasks in progress, and 2 periods for those that are blocked. Sometimes simpler is better.

rodo looks quite cool! It’s interesting to see how common the syntax is with these formats, so there seem to be “natural” patterns.

[x]it! doesn’t try to be opinionated about what you use it for. So you could use it for your daily todos, but you could also use it for writing a packing list, or maintaining a wish list with potential shopping items. It’s intended to be a generic file format, and more specific use-cases could be supported through (independent) tooling.

Have you found a good way to use org-mode on your phone? I remember trying to find a suitable app for weeks, but without any success.

Even simple things, like following links into other files, were not possible.

Edit: Ah, I missed you mentioning Orgzly. Last time I used it, I had a lot of trouble with syncing due to its way of storing files in a notebook. Everytime I deleted a file on any other device, Orgzly would just recreate the file and sync it back to all other devices. And when I tried it, it didn't support links to org-IDs.

Honestly people wanting to make a hobby project from scratch and then brag about it in a blog post to make themselves look like a more savy programmer/techie (hey, not blaming people, when it is done well it is way better than a resume with bullet points) is primarily the reason they dont use org mode. It is like wondering why people go through massive amounts of efforts to bake stuff from scratch when there is a super market and bakery down the street, except it is also like I said a resume.

If you want a plain text organizational, compositional and scheduling tool that you can use for the rest of your life and know that 30 years down the line it will be actively supported, developed and you will be able to tweak anything you want.... emacs/org mode is by far and away the best choice. It isn't even remotely close, we are talking about the difference between a planet and a tiny asteroid when you compare org mode to other plain textish organizational, compositional and scheduling tools.

For as long as humanity doesn't collapse and probably even after it does org mode and emacs will be used (there is going to be some nerd somewhere using org mode and ledger cli to meticulously track how many smoked rats and cockroach kebobs they have left to eat before they have to leave their bunker), there is just such an intense critical mass of utility under an open source license.

About the only bad thing with org mode at this point is it has such a vast nexus of interconnected capability it is difficult to even describe what exactly it is anymore lol. Like how would you even adequately describe org mode in a single sentence? It would have to be a Thomas Pynchon style sentence lol.

I’ve never used TaskPaper, but the capabilities of the data format look somewhat similar.

I think the difference is primarily a philosophical one: [x]it! is a file format with a formal specification that’s open source.[1] There is no “canonical” tool for it, the idea is rather that tools can be created separately. That should give users the freedom to work with their data independent of specific tools.

[1] https://github.com/jotaen/xit/blob/main/Specification.md

do you use orgmode outside of emacs? I tried a port to vscode once and it was not usable.

An online site that does task warrior sync - https://inthe.am

For reference, this is the discussion around subitems / nesting: https://github.com/jotaen/xit/discussions/2

As mentioned in that ticket, I’m still reluctant to add this to the [x]it! file specification. On the one hand it seems like an obvious and useful feature, but on the other hand it’s unfortunately pretty difficult to implement in tooling. For example, I tried to add experimental support for nested subitems in the Sublime Text plugin, but I eventually had to give up, just because the syntax highlighting engine is so limited in regards to recursion. It’s the same – or much worse – for other editors.

At the end of the day, I feel that it doesn’t help to add such a feature to the file format, if tools then cannot deal with it properly. Right now, the spec is so simple that it can be implemented in maybe a day or so. I see a great deal of value in keeping the hurdle for tool creators small. But it’s a pretty tricky balancing act in the end.

How's vim/neovim compatibilty these days? Org-mode is appealing, but vim/neovim support wasn't great last time I checked.

Thanks for your feedback. I think for the status characters there are a lot of imaginable variations and preferences. In the end, I thought that restricting the spec to a single character per status would help to confine the overall complexity of the file format, so it’s a bit of a tradeoff.

That character is not directly on keyboards, so it requires additional, OS-specific knowledge to type it.

Close, I think it has to be in a list , so requires `- [ ]`, which always trips me up because I forget.

There currently are a bunch of editor plugins and one CLI tool. You find a collection of tools (all third-party) linked from the project website: https://xit.jotaen.net

> So stuff that really needs to be done I will deal with without any todo list I will just remember it or deal with it right away.

Just remember. That's exactly the thing I (for example) am not capable of. I keep forgetting everything. Every time I have some spare time, I am checking my todo first if there's something I need/want/can do.

My experience is that physical to-do lists are great for sitting down, surveying what needs doing, and deciding what you’re going to do today. Including decisions like “I did not read any of Anna Karenina yesterday but I still want to do this so I am putting it on today’s list, and while I am thinking about this I took 5s to take it off the shelf and put it by the comfy reading chair”. And things like “laundry is gonna eat 2h of my day today but I need some clean clothes ffs”. And “I have six important work projects and only 3h of actual productive time between meetings, I am going to work on projects X and Z today unless someone comes and screams about the other projects”.

Digital to-do lists are where tasks go to die.

I just keep on coming back to a nice notebook, a nice pen, and my variant of the Pomodoro method.

> So stuff that really needs to be done I will deal with without any todo list I will just remember it

Well you're lucky then, because I frequently have to remind people of important things they (still) have to do and seem to have forgotten. Having such a list is a way to avoid the stressful situation of being late with things you can't postpone or which you benefit greatly from doing sooner rather than later.

For me it's useful to rid my mind from nagging thoughts. I might be working on something while suddenly thinking about something else to be done. If I'm not writing it, I'll lose focus. Writing it in a Todo list calms my mind and let me get back to whatever it is later, without worrying I'll forget about it. My mind wonders quite a bit, so this is very beneficial for me.

something to consider is that certain todo's require the right location or context, for example if I'm at the office and it occurs to me to pay the utility bill, that would go on a "home" todo list.

Additionally, some todo's have different timeframes than others. I try to think of things as short term/immediate, medium term/this week, and long term/nextweek-before I die.

I'll occasionally pick things of the long term list and cut them down into an action I could do immediate or this week, for example, get Anna karenina from the library.

> So stuff that really needs to be done I will deal with without any todo list I will just remember it or deal with it right away.

hopefully obvious note that that simply isn't an option for anyone with ADHD.

My problem is that I'll never remember to do those things on my own. I have repeating items for things that seem obvious but that life experience has demonstrated that I just can't track on my own. I wish I could remember to order flowers for my wife in time for them to be delivered before our anniversary, but I won't. A todo app for me is a lifesaver: instead of being all stressed out that I'm forgetting something important, I can get all that stuff out of my head and concentrate on other things.

I have a completely different approach. My personal TODOs are of different type: they are necessary, non-immediate, with varying emotional load (pleasant-unpleasant). I manage them using a combination of calendar and at-based reminders. These include things like teeth cleaning, cancelling a subscription, calling my parents for their anniversary and so on. I simply wouldn't be able to remember all these things without reminders, there are just too many of them.

Normal human brain can’t remember that much. It also helps to write down everything that needs to get done first, so that you can prioritize between them.

I shifted from text-files for todo lists to using an adapted Bullet Journal 3 or 4 years back. Some times I neglect it for a few weeks at a time, but I've found it really useful on the times when I have used it extensively. In many ways, the todo section has similarities to Kanban.

But anyway, one convention I picked up from there is:

      - for a comment - something to remind yourself of the context or information to remember
      . for a task you want to do
 date . for a task that needs to be done on/by a certain date
      / for a task that is started
      X for a completed task
      > for a task that moved to a later page

It's a great system especially as transition from one state to another is just the addition of a line so very easy to do with pen and paper. Also, the act of transferring uncompleted tasks to a new page every week/month depending on preference makes it a great time to assess if things on the todo list are still worth doing as well as giving you a gentle reminder to get on and do them if they are.

I see Kanban, I upvote ! Thanks for moving the challenge forward. May I share with you one of our articles that talks about it, hope it helps :) https://zenkit.com/en/blog/kanban-explained-what-youve-alway...

Creator here. [x]it! was deliberately designed as a strict data format that stands on its own, as I think this makes it easier to create tooling and work with the data programmatically. However, I think use-cases and preferences are as different as the people who use them, so [x]it! doesn’t aim to be the one-size-fits-all approach.

For reference, there was also some discussion about this topic going on here https://github.com/jotaen/xit/discussions/10.

> Why pad priority with dots? Why pad priority at all?

It's optional, so I'd assume it's for people who want to start the sentence from same aligned column.

> The date format will allow bad clients to do the American yyyy-dd-mm thing, using a standard would make it unambiguous.

Isn't 2022-08-23 the standard format; ISO 8601?

You’d be free to format your titles like that, if you prefer. The only restriction for titles is that the line cannot start with whitespace or `[`.

Not sure what you mean by the text wrapping bit, but I think that appropriate/pleasant text wrapping would be a concern of an editor.

[x]it! files are UTF-8 encoded by default. The predefined syntactical elements (such as checkboxes, priorities, or due dates) are composed from ASCII characters, but outside of that (e.g. in item descriptions) you can use all available Unicode characters without restriction.

Thanks for your detailed notes, I’ll look through your links.

Just to clarify for context, the “letter” definition is only relevant for tags, so outside of #tags (in item descriptions, or group titles) you can use any Unicode character you want.