Emacs Docs

Appearance

Rename a single file ​

The denote-rename-file command renames a file and updates existing front matter if appropriate. It is possible to do the same with multiple files (Rename multiple files interactively).

It always renames the file where it is located in the file system: it never moves it to another directory.

If in Dired, it considers ‘FILE’ to be the one at point, else it prompts with minibuffer completion for one. When called from Lisp, ‘FILE’ is a file system path represented as a string.

If ‘FILE’ has a Denote-compliant identifier, it retains it while updating components of the file name referenced by the user option denote-prompts (The denote-prompts option). By default, these are the ‘TITLE’ and ‘KEYWORDS’. The ‘SIGNATURE’ is another one. When called from Lisp, ‘TITLE’ and ‘SIGNATURE’ are strings, while ‘KEYWORDS’ is a list of strings.

If there is no identifier, denote-rename-file creates an identifier based on the following conditions:

  1. If the denote-prompts includes an entry for date prompts, then it prompts for ‘DATE’ and takes its input to produce a new identifier. For use in Lisp, ‘DATE’ must conform with denote-valid-date-p.
  2. If ‘DATE’ is nil (e.g. when denote-prompts does not include a date entry), it uses the file attributes to determine the last modified date of ‘FILE’ and formats it as an identifier.
  3. As a fallback, it derives an identifier from the current date and time.
  4. At any rate, if the resulting identifier is not unique among the files in the variable denote-directory, it increments it such that it becomes unique.

In interactive use, and assuming denote-prompts includes a title entry, the denote-rename-file makes the ‘TITLE’ prompt have prefilled text in the minibuffer that consists of the current title of ‘FILE’. The current title is either retrieved from the front matter (such as the ‘#+title’ in Org) or from the file name.

The command does the same for the ‘SIGNATURE’ prompt, subject to denote-prompts, by prefilling the minibuffer with the current signature of ‘FILE’, if any.

Same principle for the ‘KEYWORDS’ prompt: it converts the keywords in the file name into a comma-separated string and prefills the minibuffer with it (the ‘KEYWORDS’ prompt accepts more than one keywords, each separated by a comma, else the crm-separator).

For all prompts, the denote-rename-file interprets an empty input as an instruction to remove that file name component. For example, if a ‘TITLE’ prompt is available and ‘FILE’ is ‘20240211T093531--some-title__keyword1.org’ then it renames ‘FILE’ to ‘20240211T093531__keyword1.org’.

In interactive use, if there is no entry for a file name component in denote-prompts, keep it as-is (The denote-prompts option).

When called from Lisp, the special symbol ‘keep-current’ can be used for the TITLE, KEYWORDS, SIGNATURE and DATE parameters to keep them as-is.

[ NOTE: Please check with your minibuffer user interface how to provide an empty input. The Emacs default setup accepts the empty minibuffer contents as they are, though popular packages like vertico use the first available completion candidate instead. For vertico, the user must either move one up to select the prompt and then type ‘RET’ there with empty contents, or use the command vertico-exit-input with empty contents. That Vertico command is bound to ‘M-RET’ as of this writing on 2024-02-13 08:08 +0200. ]

When renaming ‘FILE’, the command reads its file type extension (like ‘.org’) and preserves it through the renaming process. Files that have no extension are left without one.

As a final step, ask for confirmation, showing the difference between old and new file names. Do not ask for confirmation if the user option denote-rename-confirmations does not contain the symbol modify-file-name (The denote-rename-confirmations option).

If ‘FILE’ has front matter for ‘TITLE’ and ‘KEYWORDS’, ask to rewrite their values in order to reflect the new input, unless denote-rename-confirmations lacks rewrite-front-matter. When the denote-save-buffers is nil (the default), do not save the underlying buffer, thus giving the user the option to double-check the result, such as by invoking the command diff-buffer-with-file. The rewrite of the ‘TITLE’ and ‘KEYWORDS’ in the front matter should not affect the rest of the front matter.

If the file does not have front matter but is among the supported file types (per denote-file-type), add front matter to the top of it and leave the buffer unsaved for further inspection (Front matter). Save the buffer if denote-save-buffers is non-nil (The denote-save-buffers option).

Construct the file name in accordance with the user option denote-file-name-components-order (Change the order of file name components).

Run the denote-after-rename-file-hook after renaming ‘FILE’ (Access the data of the latest note).

This command is intended to (i) rename Denote files, (ii) convert existing supported file types to Denote notes, and (ii) rename non-note files (e.g. ‘PDF’) that can benefit from Denote’s file-naming scheme.

For a version of this command that works with multiple files one-by-one, use denote-dired-rename-files (Rename multiple files interactively).