-- mode: org; mode: org-make-toc --

• org-reverse-datetree [[https://melpa.org/#/org-reverse-datetree][https://melpa.org/packages/org-reverse-datetree-badge.svg]] [[https://github.com/akirak/org-reverse-datetree/workflows/CI/badge.svg][https://github.com/akirak/org-reverse-datetree/workflows/CI/badge.svg]]

This package provides functions for creating reverse date trees, which are similar to date trees as supported by built-in functions of Org mode (e.g. =org-capture=) but in a reversed order. Since newer contents come first in reverse date trees, they are more useful in situations where you want to find latest activities on a particular subject using a search tool like [[https://github.com/alphapapa/helm-org-rifle][helm-org-rifle]].

[[file:screenshots/org-reverse-datetree-1.png]] ** Table of contents :PROPERTIES: :TOC: siblings :END:

• [[#features][Features]]
• [[#prerequisites][Prerequisites]]
• [[#usage][Usage]]
• [[#configuring-date-formats][Configuring date formats]] - [[#non-reverse-date-tree][Non-reverse date tree]]
• [[#defining-a-capture-template][Defining a capture template]]
• [[#jumping-to-a-particular-date][Jumping to a particular date]]
• [[#defining-a-refile-function][Defining a refile function]]
• [[#archiving][Archiving]]
• [[#defining-an-agenda-command][Defining an agenda command]]
• [[#cleaning-up-empty-dates][Cleaning up empty dates]]
• [[#configuration-examples][Configuration examples]]
• [[#changelog][Changelog]]
• [[#035-2020-11-28][0.3.5 (2020-11-28)]]
• [[#034-2020-09-23][0.3.4 (2020-09-23)]]
• [[#033-2020-03-25][0.3.3 (2020-03-25)]]
• [[#032-2020-03-21][0.3.2 (2020-03-21)]]
• [[#031-2020-02-24][0.3.1 (2020-02-24)]]
• [[#license][License]]

** Features

• Reverse date trees, where latest contents are shown first.

• You can customize the format of the date tree.

• Week trees are also supported. You can even create date trees with four levels (year-month-week-date) or any number of levels.

• Configurations of date trees are stored in file headers, so each file is ensured to have a single date tree with a consistent structure.

• Configuration is done interactively on first creation. ** Prerequisites

• Emacs 26.1

• dash ** Usage The following functions retrieve a configuration from the file header:

• Use =org-reverse-datetree-goto-date-in-file= to jump to a date in the date tree. If this function is called non-interactively and the time argument is nil, it jumps to the current date. This can be used for =org-capture=.

• =org-reverse-datetree-goto-read-date-in-file= is similar as above, but it always prompts for a date even if the function is called non-interactively.

• =org-reverse-datetree-refile-to-file= is a function that refiles the current entry into a date tree. This can be used to build a custom command for refiling an entry to a particular file. *** Configuring date formats The format configuration is stored in the file header of each Org file, as shown in the following example:

#+begin_src org ,#+REVERSE_DATETREE_DATE_FORMAT: %Y-%m-%d %A ,#+REVERSE_DATETREE_WEEK_FORMAT: %Y W%W ,#+REVERSE_DATETREE_YEAR_FORMAT: %Y ,#+REVERSE_DATETREE_USE_WEEK_TREE: t #+end_src

These attributes are added by functions in this package on initial creation of the date tree, so you usually don't have to manually edit them.

You can customize the default format by setting =org-reverse-datetree-{year,month,week,date}-format=. Note that the formats should be basically numeric and zero-prefixed, since date-tree headings are ordered lexicographically by their texts. You should avoid a month format starting with a string like "Feb" or "February". If you want to contain one, you should append it to a zero-prefixed numeric month.

Another way to configure the structure is to set =org-reverse-datetree-level-formats= variable as a file-local variable. Through the variable, you can define a structure with any number of levels. For example, the following configuration enables date trees consisting of four levels (year-month-week-date) in all files (thanks [[https://github.com/samspo][@samspo]] for [[https://github.com/akirak/org-reverse-datetree/issues/4][reporting]]):

#+begin_src emacs-lisp (setq-default org-reverse-datetree-level-formats '("%Y" ; year (lambda (time) (format-time-string "%Y-%m %B" (org-reverse-datetree-monday time))) ; month "%Y W%W" ; week "%Y-%m-%d %A" ; date )) #+end_src **** Non-reverse date tree Even though this package is named =org-reverse-datetree=, it is now possible to create a non-reverse date tree, i.e. a normal ascending date tree.

To enable the feature, set =org-reverse-datetree-non-reverse= variable to non-nil. It is a file-local variable. The default continues to be a reverse date tree. *** Defining a capture template You can define an =org-capture= template which inserts an entry into a date tree with [[https://github.com/akirak/org-starter][org-starter]] package as follows:

#+begin_src emacs-lisp (org-starter-def-capture "p" "Commonplace book plain entry" entry (file+function "cpb.org" org-reverse-datetree-goto-date-in-file) "* %?" :clock-in t :clock-resume t :empty-lines 1) #+end_src

*** Jumping to a particular date Use =org-reverse-datetree-goto-date-in-file= command to jump to a particular date in the date tree of the current file.

*** Defining a refile function With =org-reverse-datetree-refile-to-file=, you can define a function which can be used to refile entries to the date tree in a particular file:

#+begin_src emacs-lisp (defun akirak/org-refile-to-cpb (arg) (interactive "P") (org-reverse-datetree-refile-to-file (org-starter-locate-file "cpb.org" nil t) nil :ask-always arg :prefer '("CREATED_TIME" "CREATED_AT" "CLOSED"))) #+end_src

The heading properties given as =:prefer= to the function are used to determine the date of an entry.

You can use this function both in =org-mode= (either on a single entry or on multiple entries under selection) and in =org-agenda-mode= (either on a single entry or on bulk entries). It retrieves a date for each entry if it operates on multiple entries.

=org-starter-locate-file= is a function from org-starter package, which locates the location of an Org file. If you don't use the package, you should give an absolute path:

#+begin_src emacs-lisp (defun akirak/org-refile-to-cpb (arg) (interactive "P") (org-reverse-datetree-refile-to-file "~/org/cpb.org" nil :ask-always arg :prefer '("CREATED_TIME" "CREATED_AT" "CLOSED"))) #+end_src

A recommended way to invoke this command is to add an entry to =org-starter-extra-refile-map= in org-starter package:

#+begin_src emacs-lisp (add-to-list 'org-starter-extra-refile-map '("p" akirak/org-refile-to-cpb "cpb")) #+end_src

Then you can run =org-starter-refile-by-key= and press p key to refile the selected entries to =cpb.org=. *** Archiving :PROPERTIES: :CREATED_TIME: [2020-03-25 Wed 19:04] :END: You can archive a tree to a reverse datetree using =org-reverse-datetree-archive-subtree= command. It also works on multiple trees in an active region.

The destination is specified in either =REVERSE_DATETREE_ARCHIVE_FILE= property (inherited) or =REVERSE_DATETREE_ARCHIVE_FILE= file header. It should be a file path. For now, the target file cannot contain multiple date trees.

From inside =org-agenda=, you can use =org-reverse-datetree-agenda-archive=. It doesn't work on bulk entries for now. *** Defining an agenda command With [[https://github.com/alphapapa/org-ql][org-ql]] package, you can define a function for browsing entries in a reverse date tree:

#+begin_src emacs-lisp (org-ql-search "~/org/cpb.org" (level 4) :sort priority) #+end_src

You can also define a custom org-agenda command:

#+begin_src emacs-lisp (setq org-agenda-custom-commands '(("c" "Browse entries in cpb.org" org-ql-block '(level 4) ((org-super-agenda-groups '((:todo "DONE") (:todo t))) (org-agenda-files '("~/org/cpb.org")))))) #+end_src

=org-super-agenda-groups= is an option for [[https://github.com/alphapapa/org-super-agenda][org-super-agenda]] for grouping the contents. If you don't activate =org-super-agenda-mode=, that option is simply ignoerd. *** Cleaning up empty dates You can use =org-reverse-datetree-cleanup-empty-dates= command to clean up date entries that contains no children. ** Configuration examples

• [[https://out-of-cheese-error.netlify.com/spacemacs-config#org7963676][An Annotated Spacemacs - For an org-mode workflow ·]]: Using the package in some of his =org-capture= templates for clippling URLs, notes, and tasks. ** Changelog *** 0.3.5 (2020-11-28)
• Fix bugs with =org-reverse-datetree-cleanup-empty-dates=.
• Switch to [[https://github.com/akirak/elinter/][elinter]] for CI. *** 0.3.4 (2020-09-23) Add a function for archiving from org-agenda, =org-reverse-datetree-agenda-archive=. *** 0.3.3 (2020-03-25) Add an initial support for archiving. *** 0.3.2 (2020-03-21) Add support for a non-reverse date tree. *** 0.3.1 (2020-02-24)
• Fix a bunch of issues with =org-reverse-datetree-cleanup-empty-dates=. Explicitly documented the function in README.
• Switch to GitHub Actions on running CI. ** License GPL v3