Release notes | Org mode
You can keep up with upcoming changes, requests for help, bug reports and submitted patch by checking updates.orgmode.org and by subscribing to the RSS feeds there.
Version 9.4
Incompatible changes
Possibly broken internal file links: please check and fix
A bug has been affecting internal links to headlines, like
[[*Headline][A link to a headline]]
Storing a link to a headline may have been broken in your setup and those links may appear as
[[*TODO Headline][A link to a headline]]
Following the link above will result in an error: the TODO keyword should not be part of internal file links.
You can use the following command to fix links in an Org buffer:
(defun org-fix-links () "Fix ill-formatted internal links. E.g. replace [[*TODO Headline][headline]] by [[*Headline][headline]]. Go through the buffer and ask for the replacement." (interactive) (visible-mode 1) (save-excursion (goto-char (point-min)) (let ((regexp (format "\\[\\[\\*%s\\s-+" (regexp-opt org-todo-keywords-1 t)))) (while (re-search-forward regexp nil t) (when (and (save-excursion (goto-char (match-beginning 0)) (looking-at-p org-link-bracket-re)) (y-or-n-p "Fix link (remove TODO keyword)? ")) (replace-match "[[*"))))) (visible-mode -1))
Calling conventions changes when opening or exporting custom links
This changes affects export back-ends, and libraries providing new link types.
Function used in :follow link parameter is required to accept a
second argument. Likewise, function used in :export parameter needs
to accept a fourth argument. See org-link-set-parameters for
details.
Eventually, the function org-export-custom-protocol-maybe is now
called with a fourth argument. Even though the 3-arguments definition
is still supported, at least for now, we encourage back-end developers
to switch to the new signature.
Python session return values must be top-level expression statements
Python blocks with :session :results value header arguments now only
return a value if the last line is a top-level expression statement.
Also, when a None value is returned, "None" will be printed under
"#+RESULTS:", as it already did with :results value for non-session
blocks.
In HTML export, change on how outline-container-* is set
When the headline has a CUSTOM_ID, use this custom id to build the
div id. For example, if you have :CUSTOM_ID: my-headline then the
resulting <div> will be <div id="outline-container-my-headline">.
You may want to check whether your HTML files are rendered differently after this change.
New keybinding <C-c C-TAB> for org-force-cycle-archived
org-force-cycle-archived used to be associated with <C-TAB> but
this keybinding is used in Emacs for navigating tabs in Emacs. The
new keybinding is <C-c C-TAB>.
New default settings for some options
These options now default to t:
org-loop-over-headlines-in-active-regionorg-fontify-done-headlineorg-src-tab-acts-natively
You may want to read the docstrings of these options to understand the consequences of this change.
Also, org-startup-folded now defaults to showeverything.
New features
Looping agenda commands over headlines
org-agenda-loop-over-headlines-in-active-region allows you to loop
agenda commands over the active region.
When set to t (the default), loop over all headlines. When set to
'start-level, loop over headlines with the same level as the first
headline in the region. When set to a string, loop over lines
matching this regular expression.
New minor mode org-table-header-line-mode
Turn on the display of the first data row of the table at point in the window header line when this first row is not visible anymore in the buffer.
You can activate this minor mode by default by setting the option
org-table-header-line-p to t. You can also change the face for
the header line by customizing the org-table-header face.
New minor mode org-list-checkbox-radio-mode
When this minor mode is on, checkboxes behave as radio buttons: if a checkbox is turned on, other checkboxes at the same level are turned off.
If you want to occasionally toggle a checkbox as a radio button
without turning this minor mode on, you can use <C-c C-x C-r> to
call org-toggle-radio-button.
You can also add #+ATTR_ORG: :radio t right before the list to tell
Org to use radio buttons for this list only.
New allowed value for org-adapt-indentation
org-adapt-indentation now accepts a new value, 'headline-data.
When set to this value, Org will only adapt indentation of headline
data lines, such as planning/clock lines and property/logbook drawers.
Also, with this setting, org-indent-mode will keep these data lines
correctly aligned with the headline above.
Numeric priorities are now allowed (up to 65)
You can now set org-priority-highest/lowest/default to integers to
use numeric priorities globally or set, for example
to define a buffer-local range and default for priorities. Priority commands should work as usual. You cannot use numbers superior to 64 for numeric priorities, as it would clash with priorities like [#A] where the "A" is internally converted to its numeric value of 65.
Property drawers allowed before first headline
Property drawers are now allowed before the first headline.
Org mode is moving more towards making things before the first headline behave just as if it was at outline level 0. Inheritance for properties will work also for this level. In other words: defining things in a property drawer before the first headline will make them "inheritable" for all headlines.
Refinement in window behavior on exiting Org source buffer
After editing a source block, Org will restore the window layout when
org-src-window-setup is set to a value that modifies the layout.
Display remote inline images
Org now knows how to display remote images inline.
Whether the images are actually displayed is controlled by the new
option org-display-remote-inline-images.
New option to resolve open clock at a provided time
org-resolve-clocks now has a `t' option, which works just like the
`k' option, but the user specifies a time of day, not a number of
minutes.
New step value semimonth accepted for clock tables
Allow text rescaling in column view
You can now use C-x C-+ in column view: the columns face size will
increase or decrease, together with the column header size.
New startup option #+startup: num
When this startup option is set, display headings as numerated.
Use #+startup: nonum to turn this off.
New tool for custom links
Org provides a new tool org-link-open-as-file, useful when defining
new link types similar to "file"-type links. See docstring for
details.
New optional numeric argument for org-return
In situations where org-return calls newline, multiple newlines
can now be inserted with this prefix argument.
New source code block header argument :file-mode
Source code block header argument :file-mode can set file
permissions if :file argument is provided.
RET and C-j now obey electric-indent-mode
Since Emacs 24.4, electric-indent-mode is enabled by default. In
most major modes, this causes RET to reindent the current line and
indent the new line, and C-j to insert a newline without indenting.
Org mode now obeys this minor mode: when electric-indent-mode is
enabled, and point is neither in a table nor on a timestamp or a link:
RET(bound toorg-return) reindents the current line and indents the new line;C-j(bound to the new commandorg-return-and-maybe-indent) merely inserts a newline.
To get the previous behaviour back, disable electric-indent-mode
explicitly:
(add-hook 'org-mode-hook (lambda () (electric-indent-local-mode -1)))
ob-C.el allows the inclusion of non-system header files
In C and C++ blocks, :includes arguments that do not start with a
< character will now be formatted as double-quoted #include
statements.
ob-clojure.el supports inf-clojure.el and ClojureScript evaluation
You can now set (setq org-babel-clojure-backend 'inf-clojure) and
evaluate Clojure source blocks using inf-clojure. With a header
argument like :alias "alias" the Clojure REPL will boot with
clojure -Aalias. Otherwise Clojure will boot with lein, boot or
tools.deps, depending on whether the current directory contains a
project.clj, build.boot or deps.edn, falling back on
inf-clojure-generic-cmd in case no such file is present.
Also, when using cider, you can now use #+begin_src clojurescript to
execute ClojureScript code from Org files. Note that this works only
if your Org file is associated with a cider session that knows how to
run ClojureScript code. A bare lein repl session outside of a
directory configured for ClojureScript will not work.
ob-java.el supports Java command line arguments
Babel Java blocks recognize header argument :cmdargs and pass its
value in call to java.
ob-screen.el now accepts :screenrc header argument
Screen blocks now recognize the :screenrc header argument and pass
its value to the screen command via the "-c" option. The default
remains /dev/null (i.e. a clean screen session)
ob-plantuml: now supports using PlantUML executable to generate diagrams
Set org-plantuml-exec-mode to 'plantuml in order to use the
executable instead of JAR. When using an executable it is also
possible to configure executable location as well as arguments via:
org-plantuml-executable-path and org-plantuml-executable-args.
New commands
org-table-header-line-mode
Turn on a minor mode to display the first data row of the table at point in the header-line when the beginning of the table is invisible.
org-agenda-ctrl-c-ctrl-c
Hitting <C-c C-c> in an agenda view now calls org-agenda-set-tags.
org-hide-entry
This command is the counterpart of org-show-entry.
org-columns-toggle-or-columns-quit
<C-c C-c> bound to org-columns-toggle-or-columns-quit replaces the
recent org-columns-set-tags-or-toggle. Tag setting is still
possible via column view value edit or with <C-c C-q>.
org-datetree-find-month-create
Find or create a month entry for a date.
New options and settings
New option org-html-prefer-user-labels
When non-nil, use NAME affiliated keyword, or raw target values, to
generate anchor's ID. Otherwise, consistently use internal naming
scheme.
CUSTOM_ID values are still always used, when available.
New option for using tabs in org-agenda-window-setup
Choosing other-tab for org-agenda-window-setup will open the
agenda view in a new tab. This will work with versions of Emacs since
27.1 when tab-bar-mode was introduced.
New option org-table-header-line-p
Setting this option to t will activate org-table-header-line-mode
in org-mode buffers.
New option org-startup-numerated
When this option is t, Org files will start using (org-num-mode 1)
and headings will be visually numerated.
You can turn this on/off on a per-file basis with #+startup: num or
#+startup: nonum.
New option org-clock-auto-clockout-timer
When this option is set to a number and the user configuration
contains (org-clock-auto-clockout-insinuate), Org will clock out the
currently clocked in task after that number of seconds of idle time.
This is useful when you often forget to clock out before being idle and don't want to have to manually set the clocking time to take into account.
New option to group captured datetime entries by month
A new `:tree-type month' option was added to org-capture-templates to group new datetime entries by month.
New option to show source buffers using "plain" display-buffer
There is a new option plain to org-src-window-setup to show source
buffers using display-buffer. This allows users to control how
source buffers are displayed by modifying display-buffer-alist or
display-buffer-base-action.
New option org-archive-subtree-save-file-p
Archiving a subtree used to always save the target archive buffer. Commit b186d1d7 changed this behavior by always not saving the target buffer, because batch archiving from agenda could take too much time.
This new option org-archive-subtree-save-file-p defaults to the
value from-org so that archiving a subtree will save the target
buffer when done from an org-mode buffer, but not from the agenda.
You can also set this option to t or to from-agenda.
New option org-show-notification-timeout
This option will add a timeout to notifications.
New option org-latex-to-html-convert-command
This new option allows you to convert a LaTeX fragment directly into HTML.
New option org-babel-shell-results-defaults-to-output
By default, source code blocks are executed in "functional mode": it means that the results of executing them are the value of their last statement (see the documentation.)
The value of a shell script's execution is its exit code. But most users expect the results of executing a shell script to be its output, not its exit code.
So we introduced this option, that you can set to nil if you want
to stick using :results value as the implicit header.
In all Babel libraries, the absence of a :results header should
produce the same result than setting :results value, unless there is
an option to explicitly create an exception.
See this thread for more context.
New option in org-attach-store-link-p
org-attach-store-link-p has a new option to store a file link to the
attachment.
New option org-fontify-todo-headline
This feature is the same as org-fontify-done-headline, but for TODO
headlines instead. This allows you to distinguish TODO headlines from
normal headlines. The face can be customized via org-headline-todo.
New default value for org-file-apps
The new value uses Emacs as the application for opening directory.
New hook org-agenda-filter-hook
Functions in this hook are run after org-agenda-filter is called.
Removed or renamed functions and variables
Deprecated org-flag-drawer function
Use org-hide-drawer-toggle instead.
Deprecated org-hide-block-toggle-maybe function
Use org-hide-block-toggle instead.
Deprecated org-hide-block-toggle-all function
This function was not used in the code base, and has no clear use either. It has been marked for future removal. Please contact the mailing list if you use this function.
Deprecated org-return-indent function
In Elisp code, use (org-return t) instead. Interactively, C-j is
now bound to org-return-and-maybe-indent, which indents the new line
when electric-indent-mode is disabled.
Removed org-maybe-keyword-time-regexp
The variable was not used in the code base.
Removed org-export-special-keywords
The variable was not used in the code base.
Renamed org-at-property-block-p
The new name is org-at-property-drawer-p, which is less confusing.
Renamed org-columns-set-tags-or-toggle
Renamed priority options
From org-lowest-priority to org-priority-lowest.
From org-default-priority to org-priority-default.
From org-highest-priority to org-priority-highest.
From org-enable-priority-commands to org-priority-enable-commands.
From org-show-priority to org-priority-show.
Miscellaneous
ob-screen.el now respects screen :session name
Screen babel session are now named based on the :session header
argument (defaults to default).
Previously all session names had org-babel-session- prepended.
Forward/backward paragraph functions in line with the rest of Emacs
org-forward-paragraph and org-backward-paragraph, bound to
<C-UP> and <C-DOWN> functions mimic more closely behaviour of
forward-paragraph and backward-paragraph functions when
available.
They also accept an optional argument for multiple calls.
See their docstring for details.
org-table-to-lisp no longer checks if point is at a table
The caller is now responsible for the check. It can use, e.g.,
org-at-table-p.
The function is also much more efficient than it used to be, even on very large tables.
New function org-collect-keywords
Drawers' folding use an API similar to block's
Tooling for folding drawers interactively or programmatically is now
on par with block folding. In particular, org-hide-drawer-toggle,
a new function, is the central place for drawer folding.
Duration can be read and written in compact form
org-duration-to-minutes understands 1d3h5min as a duration,
whereas org-duration-from-minutes can output this compact form if
the duration format contains the symbol compact.
C-n, C-p, SPC and DEL in agenda commands dispatch window
You can now use <C-n>, <C-p>, <SPC> and <DEL> key to scroll up
and down the agenda and attach dispatch window.
<C-c C-c> in agenda calls org-agenda-set-tags
Both <C-c C-q> and <C-c C-c> set the tags of the headline in the
Org buffer. Both keybindings are now available from the agenda too.
Allow to use an empty HTML extension
Using (setq org-html-extension "") or setting the HTML extension in
any fashion will produce the expected output, with no trailing period
to the resulting HTML file.
Handle repeated tasks with .+ type and hours step
A task using a .+ repeater and hours step is repeated starting from
now. E.g.,
,** TODO Wash my hands DEADLINE: <2019-04-05 08:00 Sun .+1h> Marking this DONE shifts the date to exactly one hour from now.
The format of equation reference in HTML export can now be specified
By default, HTML (via MathJax) and LaTeX export equation references
using different commands. LaTeX must use \ref{%s} because it is used
for all labels; however, HTML (via MathJax) uses \eqref{%s} for
equations producing inconsistent output. New option
org-html-equation-reference-format sets the command used in HTML
export.
ob-haskell.el supports compilation with :compile header argument
By default, Haskell blocks are interpreted. By adding :compile yes
to a Haskell source block, it will be compiled, executed and the
results will be displayed.
Support for org-edit-special with LaTeX fragments
Calling org-edit-special on an inline LaTeX fragment calls a new
function, org-edit-latex-fragment. This functions in a comparable
manner to editing inline source blocks, bringing up a minibuffer set
to LaTeX mode. The math-mode deliminators are read only.
org-capture-current-plist is now accessible during org-capture-mode-hook
New org-refile.el file
Org refile variables and functions have been moved to a new file.
The end of a 7 years old bug
This bug originally reported by Matt Lundin and investigated by Andrew Hyatt has been fixed. Thanks to both of them.