Checklists in org-mode

I am continuing on with another article org-mode, this time, checklist items. I am enjoying org-mode more as I read about its features, and found checklist items to be sweet.

I will introduce org-mode’s checklist feature by showing how to make a checklist, how to mark items as complete (or incomplete), auto-complete functions org-mode does for progress updates such as progress counts and percentages.

My hope is that you gain an appreciation of org-mode’s checklist function and start using org-mode as well. This should take you less than five minutes.

source and more information

Introduction

A checklist:

checklist | ˈCHekˌlist | noun

a list of items required, things to be done, or points to be considered, used as a reminder.

I love checklists, especially to break a big problem or project into smaller tasks.

Here’s a list of a possible projects, great list with children. The project has two subtrees: ‘main project’ and ‘celebrate main project completion’.

- project
  - main project
    - get permits
    - execute
  - celebrate main project completion
    - get meeting time for stakeholders
    - order appetizers for meeting

To make any item a checklist item, just add: [ ] to the beginning of the item after the list indicator: - [ ] get permits

Here’s the list again formatted with checklists:

- project
  - big project
    - [ ] get permits
    - [ ] execute
  - celebrate big project
    - [ ] get meeting time for stakeholders
    - [ ] order appetizers for meeting

To mark a checklist item as done, there are two ways, the manual way or using a keyboard shortcut.

Marking Manually

Marking the checklist item as done requires changing the [ ] to: [X].

To mark: “get permits” as done, change it from:

- project
  - big project
    - [ ] get permits

to this:

- project
  - big project
    - [X] get permits

Simple, right?

org-mode shortcut

Another way of marking a checklist item as done, is on the line with the checklist item, hit the org-mode shortcut key: control-c control-c.

Using the shortcut key has advantages as this updates other checklist items, such as progress meters and parent checklist items, presented in the following sections.

Here’s how to marking items in an org-mode checklist looks like:

Parent Checklist Items

One level of checklist items is nice, for bigger projects, having multiple levels of checklist items would help.

Taking the previous checklist further:

- [ ] project
  - [ ] big project
    - [ ] get permits
    - [ ] execute
  - [ ] celebrate big project
    - [ ] get meeting time for stakeholders
    - [ ] order appetizers for meeting

Keeping track of two items and each item has tasks of their own.

When using org-mode’s checklist item to update a subtask, org-mode will automatically update the parent task’s status.

When marking “get permits” as done, the following would be how org-mode will update:

- [-] project
  - [-] big project
    - [X] get permits
    - [ ] execute
  - [ ] celebrate big project
    - [ ] get meeting time for stakeholders
    - [ ] order appetizers for meeting

See how “big project” and “project” checklist box changed from [ ] to [-]? [-] shows there is partial progress! (I love this indicator!)

When marking the “execute” part of the project as done, the “big project” becomes done! This would be the state of the list in Emacs:

- [-] project
  - [X] big project
    - [X] get permits
    - [X] execute
  - [ ] celebrate big project
    - [ ] get meeting time for stakeholders
    - [ ] order appetizers for meeting

The “big project” is complete, indicated by: [X], “project” is still in progress as its checkbox is [-], because “celebrate big project” is not complete and “big project” is complete.

Here’s what it looks like in action:

Progress Detail

Having [-] show up helps indicate there’s progress on a group of tasks. To get additional detail on the progress, org-mode provides an auto-updating count and a percentage indicator for any checklist item.

Progress Count

On any checklist item or parent of checklist items, adding [/] to the end of the item will indicate to org-mode to automatically fill in the appopriate values for done items and the total number of items.

Taking the state of our last list, appending [/] to the “project”, “big project”, and “celebrate big project” lines, it becomes:

- [-] project [/]
  - [X] big project [/]
    - [X] get permits
    - [X] execute
  - [ ] celebrate big project [/]
    - [ ] get meeting time for stakeholders
    - [ ] order appetizers for meeting

After toggling any item from done to incomplete, org-mode updates the [/] items with the appropriate value:

- [-] project [1/2]
  - [X] big project [2/2]
    - [X] get permits
    - [X] execute
  - [ ] celebrate big project [0/2]
    - [ ] get meeting time for stakeholders
    - [ ] order appetizers for meeting

Isn’t that magical?!

Here’s a demonstration of org-mode updating progress counts when making changes to the checklist.

Progress Percentage

If you prefer to have progress percentages instead, append [%] to the line. org-mode allows both to co-exist on the same line and will udpate both.

- [-] project [1/2] [%]
  - [X] big project [2/2] [%]
    - [X] get permits
    - [X] execute
  - [ ] celebrate big project [0/2] [%]
    - [ ] get meeting time for stakeholders
    - [ ] order appetizers for meeting

Just like before, toggling any item forces org-mode to update values within [%] and [/].

- [-] project [1/2] [50%]
  - [X] big project [2/2] [100%]
    - [X] get permits
    - [X] execute
  - [ ] celebrate big project [0/2] [0%]
    - [ ] get meeting time for stakeholders
    - [ ] order appetizers for meeting

Caveats

org-mode only calculates the values for the direct descendants of the list, not all the items of a list. :-/

This is still magical for me.

This is what having progress counts and percentages on checklist items looks like in org-mode, how it updates when making changes to the checklist.

Conclusion

Emacs’ org-mode is simple yet provides nice helpers when working with checklists, such as:

• having simple boxes as visual indicators when marking an item done or not by prepending [ ]
• presenting done items as [X]
• presenting items in progress or subitems are partially done by [-]
• automatically calculating how remaining items to do and in total by appending [/]
• automatically calculating the percent complete a subitem is by appending [%]

As I discover more about org-mode, it impresses me more and more. I want to integrate org-mode more into my workflow every day.

If you like to keep lists and have it automatically update as you mark items done, check out org-mode. It can improve your workflow too!