# Organise Tasks

An Obsidian plugin with four commands: **Sort completed tasks to bottom**,
**Sort by due date**, **Clear completed tasks**, and
**Clear completed tasks in current document**. In the command palette they
appear as **Organise Tasks: Sort completed tasks to bottom** and so on.

It reorders the task list at the level your cursor is on, or at the shallowest
list level touched by your selection. Completed tasks sink to the bottom and
everything else keeps its order.

**Sort by due date** orders incomplete tasks soonest first using `📅`
due dates, falling back to `⏳` scheduled dates. Undated incomplete tasks follow
dated ones. Completed tasks move to the bottom using the completed-task sorting
rules described below. Overdue tasks are not specially grouped or highlighted.
You can optionally limit sorting to dates within a number of days from today.

**Clear completed tasks** removes `[x]` / `[X]` items at the same list
level and within the same cursor or selection scope as sorting. Children and
annotations are removed with their parent, including unfinished children.
Cancelled `[-]` items are kept by default. The edit can be undone in one step.

**Clear completed tasks in current document** applies the same clearing
rules to every list in the active document, including nested tasks. When a
completed parent is removed, its whole subtree is removed with it.

## Behaviour

- A completed task is `[x]` / `[X]` (done) or `[-]` (cancelled).
- Done tasks come first in the completed group, cancelled tasks after them.
- Within each completed group, tasks are ordered newest first by their done
  (`✅ YYYY-MM-DD`) or cancelled (`❌ YYYY-MM-DD`) date. Tasks without a date
  follow the dated ones, in their original order.
- Everything else at the sorted level counts as incomplete and stays on top.
  This includes `[ ]`, `[/]`, other status symbols, and plain bullets.
- Children and annotation lines move with their parent and keep their order.
- No selection: the cursor item's own level. With a selection: the shallowest
  list level present, and every affected parent's full child list is sorted.
- One blank line keeps a list together; two consecutive blank lines break it.
- Tasks inside blockquotes and callouts are supported. Quote-depth changes,
  quoted titles, paragraphs, and fenced code bound the list being sorted.
- The cursor follows its task after a sort. With a selection, it moves to the
  first selected task. A single undo reverses the sort.

These are the defaults. Settings → Organise Tasks can adjust the rules below without
changing any of the above until you touch a setting.

## Settings

- **Cancelled counts as completed** (on): `[-]` tasks are completed and sink
  below done tasks. Off: `[-]` counts as incomplete and stays on top.
- **Clear cancelled tasks** (off): also remove `[-]` items when clearing
  completed tasks. This is independent of **Cancelled counts as completed**.
- **Require complete trees before clearing** (off): keep a completed parent
  when any child list item cannot be cleared. The command reports blocked trees
  while continuing to clear other complete trees and individual tasks.
- **Clear complete siblings in blocked trees** (off): when the complete-tree
  requirement blocks a parent, still remove fully complete child task trees.
- **Tab width** (4): how many columns a tab character counts for when measuring
  list indentation. Matters when lists mix tabs and spaces.
- **Undated completed tasks** (bottom of the completed group): completed tasks
  without a date follow the dated ones. Top: they come first.
- **Sortable date range (days)** (blank): blank sorts all dates as before. Set a
  whole number of days (0-365000) to sort incomplete tasks dated on or before
  today plus that many calendar days, including overdue dates. For example,
  with 60 days set on January 1, January and February dates are sortable, but
  June dates are not. A due date beyond the range falls back to a scheduled
  date within the range. Tasks with neither date in range join undated tasks
  after dated tasks, preserving their relative order. This setting only affects
  **Sort by due date**, not **Sort completed tasks to bottom**. The command's
  notice counts tasks excluded from date sorting because every date they have
  is beyond the range, even when nothing changes in the note. Tasks
  using an in-range scheduled-date fallback are not counted.

## Installation

### Community plugins

1. Open Settings → Community plugins and select **Browse**.
2. Search for **Organise Tasks**, then select **Install** and **Enable**.

### BRAT

1. Install and enable the [BRAT](https://github.com/TfTHacker/obsidian42-brat) plugin.
2. Run **BRAT: Add a beta plugin for testing** and enter
   `ChrisDavison/organise-tasks`.
3. Enable **Organise Tasks** in Settings → Community plugins.

### Manual

1. Download `main.js` and `manifest.json` from the latest
   [GitHub release](https://github.com/ChrisDavison/organise-tasks/releases).
2. Put both files in `<vault>/.obsidian/plugins/organise-tasks/`. The folder
   name must match the plugin ID in `manifest.json`.
3. Enable **Organise Tasks** in Settings → Community plugins.

### Upgrading from Todo Sorting

Version 2.0.0 changed the plugin ID from `todo-sort-completed` to
`organise-tasks`. Install Organise Tasks, copy `data.json` from
`.obsidian/plugins/todo-sort-completed/` into `.obsidian/plugins/organise-tasks/`
to keep your settings, rebind any hotkeys, then remove the old plugin.

## Usage

Run **Sort completed tasks to bottom** from the command palette, or bind a
hotkey to it. Run **Sort by due date** to order incomplete tasks by their due
or scheduled date. The two clear commands remove completed tasks from the
current list scope or the whole active document.

## Development

There is no build step and no dependencies. `main.js` is the complete source.
Run the tests with `node --test`.

## Scope

Not handled: ordered lists and multiple cursors. Those are reported rather than
edited.

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for the
full license text.