Show HN: A plain-text file format for todos and check lists

[jotaen]

After having cycled through various CLI-based todo apps, I started to realise that I actually don’t need a tool at all for managing my todos. Most of the time, my use cases are quite simple, like viewing my todo items, checking them off, or adding a new one.

Rather than having to memorise CLI commands for these interactions (which I’m not super good at), I figured that it’s easier for me to use my text editor directly, and have an editor plugin help me with the visual structure and some convenience functionality. So, kind-of similar to Emacs Org Mode, but without having to use Emacs. I personally use Sublime Text, and even though I enjoy it a lot, I don’t like being bound to specific tools.

I think the best basis for staying independent is to have a data format that’s properly specified and meaningful on its own. This puts the data first, and it allows the tools to be built on top and shared (or interchanged) more easily.

This is what [x]it! is about, which is a plain-text file format for todos and check lists. I’m curious for thoughts and feedback. There is obviously not much tooling support (yet), but feel free to create something if the idea resonates with you.

Website with demo: https://xit.jotaen.net

File specification: https://github.com/jotaen/xit/blob/main/Specification.md

[tconfrey]

+1 for plain-text for all the points you mention, particularly "data-first with tools on top". But why reinvent the wheel when the org-mode format is well established and does everything you want, and more?

There are an increasing number of tools using org-mode as a plain-text data store, so you are more likely to be able to participate in a tool ecosystem. In addition to my own https://braintool.org see the list below. BrainTool (mainly a bookmark manager) has an elemental to-do system, I'd love to have my users be able to use your tool for todos.

NB see also Karl Voit's push for org markup awareness outside of Emacs via Orgdown: https://gitlab.com/publicvoit/orgdown.

------ ORG-MODE TOOLS OUTSIDE EMACS

https://plainorg.com

https://flathabits.com

https://beorg.app

https://braintool.org

https://easyorgmode.com

https://logseq.com

https://organice.200ok.ch

https://orgro.org

http://orgzly.com

[barankilic]

Isn't org-mode tied to emacs? Also, does it have a specification? I searched for a specification and found this (https://orgmode.org/worg/dev/org-syntax.html) and couldn't understand whether it is a proper spec. Without a well-defined spec, it becomes very hard to create tooling around it. For example, Markdown was using Perl scripts initially and didn't have a spec for some time.

[kesslern]

> org-mode format is well established

Is there a formal specification or documentation on the format? When I've previously read about integrating org-mode support in other threads, the lack of specification outside of "whatever org-mode does" was the biggest blocker.

[kaladin-jasnah]

Is there anything that isn't Orgzly for Android? I found the app very finicky from my basic usage and very difficult to use.

[greggman3]

Funny that all the phone versions have a hard coded UI. Isn't the point that org mode is just plain text so it's more free from? I currently use google keep. I'm not recommending it but to some extent I can use at as just a collection of synced text files.

[D13Fd]

I am conflicted on this.

The spec is nice. I love the recognition that dates may be imprecise (e.g., 2022-05 -- although I would count that as the last day of the period, 23:59:59 on 2022-05-31, rather than the first day of the next period, 2022-06-01). I like the thought that went into it and the nice presentation.

On the other hand, I do not think this is necessary or even all that helpful in the real world. You don't need a standardized format if you are writing to do items manually in a text editor. You just write them. In the vast majority of cases no one is going to see them but you. Time spent conforming to a spec is time wasted.

A formal spec also doesn't help much for apps to use this format. There is not a huge need for portability between to do apps, and for most users to do items are ephemeral and not something that needs to be archived and revisited. Even if an app adopted this, being tied to a plain text format would likely hinder feature development, including the ability to sync across multiple devices. Beyond that, different to do apps use different systems of categorization and tagging, so really in practice I doubt this will become any kind of standardized format.

So, all told, it is a beautiful effort, nicely presented, but I think it is unnecessary.

[vhanda]

> A formal spec also doesn't help much for apps to use this format. There is not a huge need for portability between to do apps, and for most users to do items are ephemeral and not something that needs to be archived and revisited. Even if an app adopted this, being tied to a plain text format would likely hinder feature development, including the ability to sync across multiple devices. Beyond that, different to do apps use different systems of categorization and tagging, so really in practice I doubt this will become any kind of standardized format.

I disagree. I maintain a rather popular plain-text-based app [1] and the formal spec makes this something very very easy to add support for. Infact the only thing that could make this even easier is if there was a way to verify my own implementation.

[1] https://gitjournal.io

[haswell]

> A formal spec also doesn't help much for apps to use this format. There is not a huge need for portability between to do apps...

To add some counterpoint to this, I try a lot of apps. Partially because I'm always looking for the one that's better than what I use now - looking for the thing that fits me the best - but also because I just like trying things.

Portability means a greater chance that I'll fully dive in and use an app to its potential vs. some light use.

There have been a few times that I've found a new app/solution that was clearly better than what I was currently using, and this was both exciting and frustrating. Frustrating because it meant I'd either have to leave my history behind, or spend a ton of time trying to port it over somehow.

I realize I'm part of a niche group of people, but I feel like a spec like this was meant for a pretty niche group of people.

I for one do not agree that this is unnecessary, but I do acknowledge that it's probably not necessary for a lot of people.

[jotaen]

I appreciate the criticism, thanks! I disagree, though, that adhering to standardised formats is not worth it. Currently, there are countless todo apps and editor plugins out there, which all do very similar things. However, each needs their own dedicated editor plugin for syntax highlighting, and you can’t easily switch the client apps without having to also switch the underlying data format.

What I agree with is that standards limit the creative freedom of tool creators. But that’s the same balancing act all over again, no matter where you look at.

[mufufu]

I disagree, having the spec is the first step to building tooling around it. People can port plugins that support this format to vim, eMacs, VSC, etc.. and create functionality around it. For example: reorder into a date view

[posharma]

Agree. Todo lists are ephemeral. They're not meant to be stored and archived. Just write the list already, execute the items in the list and move on. Focus on getting things done rather than creating new formats for these ephemeral lists.

[zamubafoo]

I think that having a formal spec would help since a lot of the minutiae that is done to format and the like can be in the form of snippets in (nearly all) text editors used today.

So just having the autocompletion for people editing in text does wonders.

As for standardization, applications don't have to target it as their on-disk format for it to be useful. Instead of bespoke JSON/XML schemas or proprietary formats, having a plain text export format is a big win. Specially if it's human readable and human writeable.

[oezi]

I think it is nice when there is a well thought out spec for something. But in this particular case, I think it is not compatible enough with other tools.

In particular, Markdown has a todos (using the same `[ ]`) and just uses indentation for grouping. I find this more intuitive and it renders in markdown renderers.

For priorities, I have adopted the notation of OneNote which puts exclamation and Unicode star symbol next to the todo brackets.

I also use some other conventions:

[-] for obsolete rather than [~].

[>] for postponed until later

Implemented in my Todo manager TUI: https://github.com/coezbek/rodo

[eigenvalue]

Where I think something like this is most useful is as a common interchange format. For example, if you are using TickTick as a todo app and decide you want to switch to using Notion or something. If there were an ecosystem of converters to this common format, that would make this trivial to do.

[smoe]

A spec makes it more easy to build tooling around it. I reckon the people that love emacs org-mode, do so not mainly because of its specification, but the power to manipulate those plain text files in the editor.

[RankingMember]

Agree, not everything needs a special format or spec. To me, it just obfuscates the core purpose of a to-do list for me, which is to record the bare essentials to remind me of things I need to do, then do them and forget about them. Anything else is just more overhead I don't need.

[divbzero]

As an alternative, the todo.txt format [1][2] first defined in 2006 [3] is supported by a CLI client (desktop) and several GUI clients (desktop, mobile, web).

[1]: https://github.com/todotxt/todo.txt

[2]: http://todotxt.org/

[3]: https://web.archive.org/web/20060701121920/https://lifehacke...

[neilv]

I've been using todo.txt too, for personal tasks and appointments.

I have a few tweaks: https://www.neilvandyke.org/todotxt/

[WesternWind]

This is what I use. It's a little hobbled in terms of add-ons to the standard because the orginal standard isn't centralized or versioned, but it works really well for a lot of things.

[jotaen]

Clickable links:

Website with demo: https://xit.jotaen.net

File specification: https://github.com/jotaen/xit/blob/main/Specification.md

[MattyRad]

Any todo list that doesn't account for dependency tasks is exclusively limited to short term planning (i.e. days not weeks). After skimming the spec, I don't think dependency tasks are accounted for?

For example, say this is my (out of order) to-do list:

- [ ] Mix ingredients

- [ ] Eat cake

- [ ] Bake a cake

- [ ] Find cake pan

These tasks need to be done in a specific order, but reading the list top to bottom doesn't make sense.

So let's denote dependencies with indentation:

- [ ] Eat cake

  - [ ] Bake a cake

    - [ ] Find cake pan

    - [ ] Mix ingredients

By specifying order through indentation, we've now created a DAG that orders and contextualizes tasks; with the most actionable tasks having the largest indentation. This is how I organize my plaintext to-do files, but afaict no todo list software is able to handle large task trees gracefully- with the exception of grit, which is more of an experiment (but the readme is incredibly well written and describes the DAG problem to a tee).

https://github.com/climech/grit

Does anyone know if org-mode handles complex task trees gracefully? All the examples I've found online were trivial (i.e. one task deep)

[drran]

IMHO, you are mixing TODO lists and task management/planning software. No, I don't know a good task manager or business process manager for command line. Instead, I created a simpler TODO list manager, called `td`[0], which supports flat TODO lists only, and use directories and command-line generators to manage todo's. `td` prints top item only, by default, leaving little room for procrastination. I'm keeping one `TODO.md` file per project instead of one large TODO file for all todo's.

[0]: https://github.com/vlisivka/bash-modules/blob/master/bash-mo...

[halostatue]

Looks interesting. It doesn’t have a formal specification, but there may be things from TaskPaper https://www.taskpaper.com/guide/getting-started/ that you may find interesting.

There are lots of things that support the basic TaskPaper format: https://support.hogbaysoftware.com/t/taskpaper-extensions-wi...

[kitplummer]

This is awesome! Super appreciate the effort on this.

One challenge I've had is the file-based concept. And it losing "shape" quickly. I taken a few whacks at something different and have settled on a CLI-based kanban-y thing: https://github.com/kitplummer/clikan

But this lacks things like tags - which I appreciate as long as they are searchable in some form.

[pixxel]

nb might be worth a look (has tags) https://xwmx.github.io/nb/

[oezi]

Nice! I also have this pain of the file losing shape quickly. My take is to have a a CLI tool to "carry over" all todos which aren't solved into a new heading. This way the old/resolved items are moved to the back/lower in the file.

I call it Rodo (Todos in Ruby): https://github.com/coezbek/rodo

It uses Markdown for syntax.

[jotaen]

Cool, that looks quite neat! I agree with you, at some point you have to structure things in one way or the other, in order to keep an overview. For me it works somewhat well to organise my data across different files and folders, which are setup in a certain structure. That either requires some manual labour and discipline, or you automate these workflows. That requires “standardised” data formats, however.

[jrib]

I like it.

I do something similar for my todo file but organize by date. Most recent date first. Every day I review unchecked items from the previous day and move them to today or mark them obsolete.

It has the added functionality of serving as a nice log of my work.

So it looks something like this:

    2022-04-01
    ==========
    
    [ ] do a thing
    
    2022-03-31
    ==========
    
    [x] foo the baz

[gcarvalho]

Me too, although I use markdown todo lists, starting with a minus.

I also record the creation date and timestamped notes on the progression of the task. And I use @ to keep tabs on tasks that I've delegated.

    2022-04-02
    - [x] [2022-03-30] do a thing #tag1 #tag2
        - 2022-03-31 10:30 notes about work being done thing
        - 2022-03-02 14:00 completed thing by using X
    - [ ] [2022-03-28] @delegated_person: do another thing
        - 2022-03-29 09:00 delegated_person reported that Y

[Giho]

There is a todo format that I use daily called todotxt. It has even application support on most platforms or you just write manually in a txt file. Easy to overview by yourself. In combination with Syncthing I have a very seamless experience where ever I go.

http://todotxt.org/ https://syncthing.net/

[_h9mb]

I had a similar insight some years ago. I write my TODOs mixed with text in markdown notes and use a CLI to do nice things like exploration and journaling. It purposefully doesn't have any state besides the notes in itself.

https://github.com/danisztls/journal

Lately I'm rarely using it because most of the things that I really have to do (work) are on my email inbox or containerized in project dirs. And for the later I just run 'rg "TODO:"' in the project dir.

[ma2rten]

I didn't know about rg, how does it compare to ag?

[dugmartin]

I have my own informal format that doesn't use the [], just single characters

    - this is an unstarted todo
    / this is a started todo
    x this is a finished todo
    ~ this is a todo I'm not going to do

It works well for me.

[kseistrup]

That resembles what I use in my daily paper agenda:

    / Unfinished task
    X Finished task
    % Canceled task
    ↗ Task moved to a later date
    ↙ Task moved to an earlier date

In effect, I can convert the ‘/’ sigil to any of the last four sigils and I can see at a glance what still needs to be done.

[yardshop]

This is similar to my own format too, but opposite meanings for some of them, and a few have somewhat mnemonic character names:

    ~ todo (tilde)
    * started (star)
    - done (dash)

    x didn't or won't do
    # comment
    > design item

I use this mostly to write out and track steps in scripts and programs I'm writing. I will use one or two levels of indentation and blank lines within entries.

    example feature steps

        > the example feature will demonstrate such and such
          and make use of this and that

        - write stub version
        * fill in actual code

            - part A
            ~ part B

        x call xyz function
        # didn't do this because of ...

        ~ add extra features

I do this mostly in the header comment of a script (Python doc string), but sometimes pull it out into its own text file if it gets too big.

I wrote a script at one point to convert these kinds of notes into a web page with various background colors per status. It helps to visualize it sometimes but I don't actually use it that often.

[tyingq]

Looks interesting. Might be worth looking at the Emacs Org Mode support for TODO lists[1]. Just as a reference for how someone else dealt with TODOs in a text format, but with a pretty complete feature set.

[1] https://orgmode.org/org.html#TODO-Extensions

[neurocat123]

Just my 2¢: I'm also using plain text files as a 'mind-dump'/exocortex/organsation system. After a while, the file tends to get rather big, and so I need some coarse hierarchical levels, like 'random cool stuff to look at when idle', 'high priority stuff/this week', 'medium priority stuff/this month', etc. A copious amount of unicode and especially ASCII art helps me a lot to find sections quickly. Behold my elite retro headers like

  ╗
  ║  TODAY
  ╚═════════════════════════════════════════════╗

and grab-box of symbols:

  ↗↙⋇⟡*═╔╗╚╝║∙◽◼▪→▶▷▸▹⇒⇨◉๏⦿⊙○●⭗⭘⭘
  ────── ∗ ⋅◈⋅ ∗ ────── 

Markdown-style headers (with - or = underlines) also help a lot to organise within the top-level sections. In general I find it very helpful to re-use Markdown (or reStructuredText) syntax, even if it's not rendered.

[ryanolsonx]

This is really cool. I dig it.

I like that there's a Sublime Text package for it. Seeing my plain text todos with nice syntax highlighting is a perk.

I maintain a Zenburn color scheme[0] for Sublime Text. After playing with this, I added specialized support for [x]it! and I think it looks pretty good[1].

[0]: https://packagecontrol.io/packages/Zenburn%20Color%20Scheme

[1]: https://github.com/ryanolsonx/sublimetext-zenburn-theme/issu...

[_andrei_]

Looks like quite similar to my own document / task management grammar [1].

I wrote a small library to parse mine, and built many tools on top of it, including editor support, various CLIs for task management, calendar, activity tracking, content consumption, etc.

I invested a lot of time into learning Emacs, got into using Org, but Emacs is just too slow, and I got to a point where customizing the tool for what I want was harder than building a custom tool.

[1] https://i.imgur.com/Nm6e31W.png * sorry for ma english

[wim]

This is very cool!

We're actually building an editor/IDE of sorts from scratch, but specifically for "todo.txt" (https://thymer.com if you're interested). I think a lot of parts of your spec would fit really well with the concepts we were thinking of (like the status in between [ ], due dates, #tags..). Maybe we should add compatibility for this spec as well (for things like autocomplete, and export/import).

Thanks for posting, really helpful for portability to have more standards like these!

[mpalczewski]

I switched away from Workflowy to a plain text file format. Load times are quicker, navigation is quicker, can use keyboard only without a mouse, the UX can keep up with the pace of my thinking.

I prefer vimwiki for this purpose https://github.com/vimwiki/vimwiki

You can get plugins that sync it to a git repository. I love this.

There's also task warrior plugins, though I haven't figured out how that would for me, seems to get away from simple text files at that point.

[sloankev]

Very cool! I made something very similar to this as a VS Code extension[1]. Inspired by the bullet journal method.

[1] https://marketplace.visualstudio.com/items?itemName=blt.blt

[geoelectric]

This is really neat. It's similar to the BuJo rapid-logging-inspired system I handspun for myself around Markdown a few years ago that I outlined here:

https://news.ycombinator.com/item?id=21580133

I'd quit using that one since because too many Markdown editors have forgotten tabs are legal whitespace after a UL bullet, and that there are three different UL bullet characters (and it really doesn't help that the CommonMark examples page only docs `-` and `*`, even though `+` is part of the CommonMark spec too). In particular, without the tab support being implemented, there's no fixed gutter for the BuJo-style sigil and queries get much harder.

But I do miss the idea of those simple bullets. I may have to check out your extension.

[prideout]

When I saw the OP's format, I immediately wanted a VS Code extension for it. This looks great, installing it as we speak.

In fact, I like your format slightly more, because when I complete tasks I usually just delete them -- no need for a checkbox.

[softwarebeware]

This is really cool. I am endlessly fascinated by the proliferation of "productivity apps" when I find the same thing as you: that they are quite unnecessary.

My approach is similar. I already take notes via a Bash script. I configure a particular "label" for any todos and (essentially) just grep for them, excluding those that are crossed out (with Markdown tildes). This approach works great for me as a Staff Engineer in a large tech company. Reference: https://github.com/scottashipp/noted/blob/main/subcommands.m...

I also wanted to mention there are several related ideas / movements around the web. One of the biggest is todotxt. In case you hadn't heard of it: https://github.com/todotxt/todo.txt

[jotaen]

I used todo.txt for a while, but in the end I stopped using the CLI tool and just worked with the files directly. For my use cases, the todo.txt file format has a few shortcomings and inconveniences, and there also is no dedicated specification.

That being said, I drew a great deal of inspiration from todo.txt, and I think it’s a well-made and powerful tool.

[zamubafoo]

Only thing I would think of changing would be allowing for the use of colons in tags to provide tag namespaces. Then it's fairly trivial to implement things like created on date, completion date, and the like since it's just "#created-on:yyyy-mm-dd" or "#completed-on:yyyy-mm-dd".

It also allows users more generic organization options, with filtering based on the namespaced tags being something trivial, but ultimately up to the user or the app that is interfacing with the xit file.