Function: denote-rename-file

denote-rename-file is an autoloaded, interactive and byte-compiled function defined in denote.el.

Signature

(denote-rename-file FILE TITLE KEYWORDS SIGNATURE DATE IDENTIFIER)

Documentation

Rename file and update existing front matter if appropriate.

Always rename the file where it is located in the file system: never move it to another directory.

If in Dired, consider FILE to be the one at point, else the current file, else prompt 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, retain it while updating components of the file name referenced by the user option denote-prompts. 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.

The IDENTIFIER is a string that has the format of variable denote-date-identifier-format.

If there is no identifier, create a new identifier using denote-get-identifier-function. By default, it creates a new identifier using the date parameter, the date of last modification or the current-time.

In interactive use, and assuming denote-prompts includes a title entry, make 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.

Do 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: convert the keywords in the file name into a comma-separated string and prefill the minibuffer with it (the KEYWORDS prompt accepts more than one keywords, each separated by a comma, else the crm-separator).

For all prompts, interpret 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 rename 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.

When called from Lisp, the special symbol keep-current can be used for the TITLE, KEYWORDS, SIGNATURE, DATE, and IDENTIFIER 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. ]

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.

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 the user option denote-file-type(var)/denote-file-type(fun)), add front matter to the top of it and leave the buffer unsaved for further inspection. Save the buffer if denote-save-buffers is non-nil.

When denote-kill-buffers is t or on-rename, kill the buffer if it was not already being visited before the rename operation.

For the front matter of each file type, refer to the variables:

- denote-org-front-matter
- denote-text-front-matter
- denote-toml-front-matter
- denote-yaml-front-matter

Construct the file name in accordance with the user option denote-file-name-components-order.

Run the denote-after-rename-file-hook after renaming FILE.

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.

Key Bindings

Source Code

;; Defined in ~/.emacs.d/elpa/denote-4.2.3/denote.el
;;;###autoload
(defun denote-rename-file (file title keywords signature date identifier)
  "Rename file and update existing front matter if appropriate.

Always rename the file where it is located in the file system:
never move it to another directory.

If in Dired, consider FILE to be the one at point, else the
current file, else prompt 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, retain it while
updating components of the file name referenced by the user
option `denote-prompts'.  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.

The IDENTIFIER is a string that has the format of variable
`denote-date-identifier-format'.

If there is no identifier, create a new identifier using
`denote-get-identifier-function'.  By default, it creates a new
identifier using the date parameter, the date of last modification or
the `current-time'.

In interactive use, and assuming `denote-prompts' includes a
title entry, make 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.

Do 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: convert the keywords in
the file name into a comma-separated string and prefill the
minibuffer with it (the KEYWORDS prompt accepts more than one
keywords, each separated by a comma, else the `crm-separator').

For all prompts, interpret 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 rename 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.

When called from Lisp, the special symbol `keep-current' can be
used for the TITLE, KEYWORDS, SIGNATURE, DATE, and IDENTIFIER
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. ]

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'.

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 the user option `denote-file-type'), add front matter to the
top of it and leave the buffer unsaved for further inspection.  Save the
buffer if `denote-save-buffers' is non-nil.

When `denote-kill-buffers' is t or `on-rename', kill the buffer
if it was not already being visited before the rename operation.

For the front matter of each file type, refer to the variables:

- `denote-org-front-matter'
- `denote-text-front-matter'
- `denote-toml-front-matter'
- `denote-yaml-front-matter'

Construct the file name in accordance with the user option
`denote-file-name-components-order'.

Run the `denote-after-rename-file-hook' after renaming FILE.

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'."
  (interactive
   (pcase-let* ((file (denote--rename-dired-file-or-current-file-or-prompt))
                (`(,title ,keywords ,signature ,date ,identifier)
                 (denote--rename-get-file-info-from-prompts-or-existing file)))
     (list file title keywords signature date identifier)))
  (let* ((file-type (denote-filetype-heuristics file))
         (title (if (eq title 'keep-current)
                    (or (denote-retrieve-title-or-filename file file-type) "")
                  title))
         (keywords (if (eq keywords 'keep-current)
                       (denote-extract-keywords-from-path file)
                     keywords))
         (signature (if (eq signature 'keep-current)
                        (or (denote-retrieve-filename-signature file) "")
                      signature))
         (date (if (eq date 'keep-current)
                   (denote-retrieve-filename-identifier file)
                 date))
         (identifier (if (eq identifier 'keep-current)
                         (or (denote-retrieve-filename-identifier file) "")
                       identifier))
         ;; Make the data valid
         (date (denote-valid-date-p date))
         (new-name (denote--rename-file file title keywords signature date identifier)))
    (denote-update-dired-buffers)
    new-name))