A primer on using dates in TaskPaper

One of the most common queries and use of tag will probably related with dates. Although the documentation provided is excellent, some people will have a hard time understanding some of the concepts. I am going to try to add basic primer to get you started with dates and how to query them. I highly recommend you to read the documentation first or to have it available as you read this. Here are the links,

First - Modifier

Date based queries need to have the [d] modifier. Other modifiers available not related to dates are the following,

[i]  --- Case insensitive. This is the default of all the queries.
[s] --- Case sensitive. 
[n] -- Numeric compare

Now. you need to remember that the [d] query is numeric in nature. This means that it needs to be compared. This translation takes place within a library that translates dates to something the computer can understand. The dates should be in the ISO 8601 format. If you are wondering what is ISO 8601, that leads us to the next topic,

Date format (ISO 8601)

There are so many possible ways to write a date. I grew up writing dates like dd/mm/yyyy but then I had to relearn to write everything in the mm/dd/yyyy format that the US uses. The standard 8601 sets a specific way dates should be written. This is the ISO 8601


YYYY - Stands for year and it would be something like 2016
MM - Month
DD - Day
HH - Hour in the 24 hour format. So if you mean 7:00pm you will have to write it like 19:00
MM - Minutes
SS - Seconds
MMM - Millisecond.

Only the whole year is required to be translated into a date by TaskPaper. That means that this (2016) is considered a correct date in the ISO 8601 standard. Since you are not providing more information, the program will assume that you are talking about January 1st 2016 at 12:00am or

2016-01-01 00:00:00.000

If you want to add more information, you can also include that,


Again, since you are not including a time, the program will assume that you are talking about the beginning of the day which happens to be 12:00am or 00:00.

The tag you will be using for dates the most in TaskPaper is probably @due, but you can use any tags and include a date within. That means that if you are an event planner and happen to have hundreds of @meetings, or @weddings, or whatever comes to your mind, you can include a date, and TaskPaper’s engine can perform all kinds of queries on those tags too.


Because the computer is translating this date into a numeric value, you will need the ><= signs to compare that date to something. For example,

@date <= [d] 2016

The first thing to remember is that in order for Taskpaper to understand that you are talking about dates, the [d] operator needs to be there. Now, this search will give you all the date tag values within the @date that are equal or less than (2016-01-01 00:00:00.000). The means that unless you have the following values, you will not get anything above that.


But these dates are greater than 2016 not equal,

@date(2016-01-01 00:01)

That might be hard to grasp, because when we speak saying something like “I want all the dates where the year is equal to 2016” the computer has to translate that into something like,

@date >= [d] 2016 and @date < [d] 2017

But our natural instinct is to write

@date = [d] 2016

Which of course will not return anything since the computer again is assuming you mean…

2016-01-01 00:00:00.000

Or January 1, 2016 at exactly 00:00:00.000

So just remember that. The same applies to months. So if you want to look for dates before May, make sure that you start to look before the beginning of June like this,

@date < [d] 2016-06

Date Parsing

TaskPaper not only understands dates in the ISO 8601, but it has the ability to resolve other dates. The dates are included in the documentation, but here are the most useful,

January - December (and their common abbreviations, ie. Jan-Dec)

Date Queries

This parser of natural language into a date becomes very useful when searching dates. Let’s say that you want to look at all the tags that are due in the beginning of next week.

@date < [d] next week

Now, you do have to remember that weeks start on Sunday. So this means that you will get all dates that are due before the beginning of next week that starts on Sunday. If with next week you mean in seven days. You should write something like,

@date < [d] + 7 days

You could even use and combine natural language with the times that are included in the guides.

@date <[d] July 23 2pm

TaskPaper uses that to translate into the appropriate ISO 8601 format.

Advance tagging.

Maybe now is a good time to mention that the same parsing that takes place on the queries is available for the tags. This is extremely useful to do ticker files or recurring events. Let’s say that you are keeping track of your payments and need to be reminded when to pay what. You could use text like this in your tag.

- US Bank @due(this month +5 days)

That means that this happens every month on the fifth, and it will come up if your current date happens to be within seven days of the fifth of the month and you query something like,

@due < [d] + 7 days

If you prefer, you can even use a tag like @recurring to hint at the fact that this dates happens every month on the fifth day.

You can also say that something is to happen every 4th of July at 2:00pm with something like

- Office party @recurring(July 4 2pm)

I think this is pretty basic primer of how to use date. If you have any questions related to dates, ask. Remember that ye have not because ye ask not



I don’t know if you know this about dates, but I have been thinking on how to explain some of the queries in TaskPaper, and because of the nature of it, I decided to start creating a series of mini tutorials.

This is pretty brilliant. Now that i’ve started to understand @search, i am re-formatting my outline and using the searches to find subsets, not making subsets by hand.

@Victor Thanks for writing this up, I think it will help lots of people. With that said can you also provide links in your post to these sections of the user’s guide:

I think the way you’ve done it is more accessible, but I still want people to know there is some actual documentation too :slight_smile:

1 Like

Thanks, I added those. I honestly wanted to include them, but by the time I finished, I was ready to go to bed.

1 Like

This is awesome, but all of your " 12:00:00.000" need to be changed to " 00:00:00.000". A date without a time defaults to midnight, and in 24-hour mode, midnight is 0, not 12.

Great job on the primer!

1 Like

Thank you. I really missed that one. Fixing it now. Any other ideas or comments?

1 Like

Awesome work! Thanks for that!

But here is a tricky one: I need a recurring task to remind me when I have to update my statistics. Currently I use:

- Update stats @due(2016-05-02)

After it’s done, I simply change the due date. But is there a smarter way? Like:

- Update stats @due(next month +2 days)

But then it never appears (because it’s always next month). The same vise versa is with @due(this month) but then it always nags me :wink:

Any ideas?

Hi - thanks a lot for the primer, super useful.

I - as a newbie - have two issues with dates and I’m not quite sure where and how to address them:

Natural language dates

I really like to tag my tasks with natural language dates, eg. tomorrow, today, next week etc.
Do I understand correctly, that the queries can interpret those inputs, right?

I’m struggling with whether I have to translate those natural inputs into something more machine-readable - there seem to be scripts somewhere that do this, but I hoped I don’t have to use them.
As @fblome puts it @due(next week) is always only next week, unless you also have a date of creation etc.

Input of dates etc

What is common practice regarding the input of dates?
I somehow can not believe that any of you every time types @due(2016-4-7) or something similar …
I would love to see some advice on how others use dates in tagging practices … - same applies to the @priority(1-5) tag …

Thanks all

Natural Language

Yes, you can input things like that. You just need to have a clear idea of how those dates will affect your query. Because @tomorrow will always be tomorrow :slight_smile: I also mentioned that you can input things in a more natural way if you rather do that. For example,

- Pay the piper @due(2016-05-02 14:00)


- Pay the piper @due(May 2 2pm)

The same can be said for your queries

@due < [d] May 22

Input of dates

I really have no clue what is the common practice. It might sounds silly, but I wrote my own set of standards and documented them. I categorize all my tags into the five questions (or six :slight_smile: ) used for problem solving. Every category has a unique color.

The important thing is to be consistent. Personally, I find @priority(1) to be more important than @priority(5) just because that is how my brain works.

I also write all my dates using 2016-04-13. Since I am always dealing with due dates, projects, and other dates at work, I tend to usually know what is the date; and writing and reading dates in this format is faster for me than writing things out. My wife in the other hand, usually never knows what is the date, and finds it curious that I do. To each his own :slight_smile:

In this case, the important thing is to know how did you query things. When you were using the @due(2016-05-02) format, how did you look for that date? Let me know more about your old system of doing things, and I or other might help.

I am going to be out this morning, but if you describe your problem, I might be able to help you later today.

Oh that is easy. I have defined a number of searches to use for my work:

! Today @search(@due =[d] today or @today except @done) ! Soon @search(@due =[d] tomorrow union @due =[d] tomorrow +2 days) ! Overdue @search(@due <[d] today except @done)

These three I use on a daily base.

I think I understand your problem. In this case, you have to decide which one is more of a hassle for you. Changing the date every month as you used to do it, or see the task there once a month and not be able to mark done. I personally use a different tag for recurring tags (@recurring). That way I can choose to have them in my search or not by including or excluding that particular tag. Of course, that can be counter-productive and leads to having bigger queries, but it is your choice.

I don’t know if this is already explained somewhere, but I can’t find it or solve this issue.

I’m on TP 3.3.2. My macOS is the Italian version of Yosemite. I’m trying to create a search parsing natural language dates.

My search string is “@search(@due <= [d] 30 days except @done)”, with “30” replaced by any other number of days if I don’t want to search for the next 30 days.

This is perfectly fine to find dates formatted as ISO standard, that is, something like “@due(2017-01-07, 15h)”.

It doesn’t work, however, for natural language entries, either in English – like “@due(January 07)” – or in Italian – like “@due(07 gennaio)”.

By reading the manual and this thread, I would have assumed that at least the English version should have worked. At the same time, right-clicking on the natural language dates let me Quick Look at the Apple Calendar, and create items in it. So, it seems TP can recognize them.


You had everything right, the problem is that taskpaper needs to know the limits of your due search. In this case, just enclose that in parenthesis and you will be good to go, something like this,

(@due <= [d] 30 days)

Your query then would look like this,

@search((@due <= [d] 30 days) except @done)

Thank you very much for you answer, Victor. Unfortunately, this does not seem to work; TP simply can no longer recognize my search formula as valid when I add the nested parentheses. I suspect this has to do with the outdated version of TP I’m using (3.3.2).


If I remember correctly, it is the nested parenthesis. Just escape them and it will work. Try it,

@search(\(@due <= [d] 30 days\) except @done)

Victor, the syntax change you suggest works fine; escaping the internal parentheses makes them be recognized.

Unfortunately, this has no apparent effect on the search. Nautural language dates (either in English or Italian) are not recognized by the search engine.

For some odd reasons, I can figure better the order behind natural language dates, than ISO dates. I seem to see them immediately in the calendar. More logical does not seem to work better for me!



I suggest you start a new post asking about that particular problem. You will probably not get to hear back from people until after Monday, but I am confident someone will be able to help.

Happy New Year!!!

@doug can you say more about how you do this?