Skip to content

Grouping and filtering

Two lane settings change how a lane’s cards are shown: group sections them under headings, and filter hides the ones you do not want. Both are keys in a lane’s index.md (see Lane).

group:
by: modified
direction: descending
filter:
- by: modified
op: newer
value: 2d

Both change only what you see. Grouping never edits a card’s file, and a filtered-out card is hidden, never changed or deleted. The one exception is dragging a card from one section to another, which can give it that section’s value (see below). A filter and a search combine: a card shows only if it passes both.

How a lane’s cards are sectioned on screen. Write the mapping with by and direction together; with by: label, add kind as a third key.

KeyTypeDescription
by text What to section the lane on: modified, created, due, priority, component or label. A value the app does not know is read as no grouping and left as written.
kind text With by: label only: the type of the label kind to section on, matched case-insensitively. by: label with no kind means no grouping. Ignored under any other by.
direction text descending (the default) or ascending; desc and asc also work. It only reorders the sections against each other.

Values of by:

  • modified, created, due: day sections, newest first. Cards with no due date fall into a trailing “No due date” section.
  • priority: sections on the exact rank of the card’s labels entry of kind priority. If a card carries several, the lowest rank is used. Every rank 1 card is in the top section, rank 2 next, and each section is named after the text of its first card’s priority. A card with no priority, or a priority with no readable rank, goes in a trailing “No priority” section. This works on a board that defines no priority kind.
  • component: sections on the card’s labels entry of kind component. The sections are the distinct component values that occur, ordered alphabetically without regard to case, and named with the first spelling seen. A card with no component goes in a trailing “No component” section.
  • label: sections on any one label kind, which you name in kind.

kind. With by: label, kind is the type of a label kind, matched case-insensitively. A card’s value is its entry of that kind (the lowest rank if it has several, otherwise the first in the file), so each card sits in exactly one section. Ranked entries section on the exact rank, named after their first card. Unranked entries section alphabetically after the ranked ones. A card with no entry of the kind goes in a trailing “No” section named after the kind. by: label with no kind means no grouping. kind: priority and kind: component mean the same as those by values. A kind beside any other by is ignored.

group:
by: label
kind: status
direction: descending

direction. descending is the default; ascending reverses it, and desc and asc are accepted as synonyms. It reorders the sections against each other and nothing else: the order of cards within a section does not change, and the “No …” section stays last either way. descending always means the reading a person would call first:

  • for the date keys, newest section first (ascending is oldest first)
  • for priority, highest priority first, which is the lowest rank number (ascending reverses it)
  • for component, A to Z (ascending is Z to A)
  • for label, lowest rank first then A to Z (ascending flips both, and ranked sections still come before unranked ones)

Dragging between sections. Under modified and created, a drag only changes the card’s order, as in an ungrouped lane. Under priority, component, label and due, dropping a card into a section gives it that section’s value: the app writes the matching labels entry in place of any entry of that kind the card had, or the due day. Dropping a card into the trailing “No …” section removes its entries of that kind, or its due. While you drag, a lane grouped by a closed single kind also shows an empty drop section for each value of the kind that no card holds yet. They disappear when the drag ends.

An absent group, the value none, or a by this version does not know all read as no grouping. An unknown by or direction is left as written.

filter is a list of clauses narrowing which of the lane’s cards show. A card shows only if it matches every clause, so clauses combine with AND.

KeyTypeDescription
by text What the clause tests: modified, created, due, label, priority, component or waiting. A clause with an unknown by is skipped.
op text older or newer for the date fields; equal or not-equal for label, priority, component and waiting.
value text For a date field, a duration such as 30m, 12h, 1d or 2w. For the others, a name to match case-insensitively; for waiting, me or a handle.

Date clauses. by is modified, created or due; op is older or newer; value is a duration: a number followed by m (minutes), h (hours), d (days) or w (weeks), such as 30m, 12h, 1d or 2w.

Day and week durations count whole days from the start of today, in local time, the same day buckets that group draws. newer than 2d means the card’s day falls within the last two day buckets, with today counting as the first. older is the exact opposite, and 1w is seven day buckets. Minute and hour durations instead measure back from now. A card with no due matches neither older nor newer.

Label, priority, component. op is equal or not-equal and value is a name, matched case-insensitively against the stamped text. priority and component look only at the card’s entry of that kind (the lowest-ranked one, if there are several). label looks at the text of any label, whatever its kind: {by: label, op: equal, value: High} matches a card whose priority is High and also a card with a free label spelled High. Use by: priority to mean the priority alone. not-equal also matches a card that has no such value at all.

Waiting. by: waiting with equal or not-equal, and a value of me or a handle. me means the human on this machine; human, operator and an absent for on the card count as that same human. A handle also matches a card whose for lists it among several. not-equal matches a card with no waiting at all. See Waiting.

A clause the app cannot read (an unknown by or op, or a value it cannot interpret) is skipped, and the rest still apply. An empty or fully unreadable list filters nothing. Extra keys inside a clause are kept and ignored.

Examples.

A Done lane showing only cards modified in the last two days, newest section first:

group:
by: modified
direction: descending
filter:
- by: modified
op: newer
value: 2d

A lane of everything not touched for a week:

filter:
- by: modified
op: older
value: 1w

Urgent cards only, grouped by component:

group:
by: component
direction: descending
filter:
- by: priority
op: equal
value: Urgent

Cards waiting on kim, leaving out Low priority, split by status:

group:
by: label
kind: status
direction: descending
filter:
- by: waiting
op: equal
value: kim
- by: priority
op: not-equal
value: Low

See Labels in depth for the kinds that priority, component and label refer to.