Renaming and moving notes

[mickael-menu]

Discussed in #199

^{Originally posted by srid April 27, 2022}
Would this be in scope for zk? Basically:

zk rename Foo "Bar Qux"

will rename Foo.md to Bar Qux.md while taking care of references. By which I mean it will replace all occurrences of [[Foo]] with [[Bar Qux]] in the notebook. As well as [[Foo|...]] with [[Bar Qux|..]]. This is exactly what the vscode-memo extension does.

The replacement can be delegated to sd.

EDIT: It should probably take directory and relative wiki links too into consideration? eg: [[Parent/Foo]] -> [[Parent/Bar Qux]]. Might have to disambiguate multiple Foo.md as well (in different parents).

[mickael-menu]

Here's a spec, feel free to review and comment.

We're talking about two separate features using the same renaming process under the hood:

• Renaming a note title, which potentially updates its filename as well.
• Moving a note to a different FS path (different folder, or changing its filename manually).

In both cases, the path of the note, its title and all the inbound or outbound links might need to be updated in a single atomic operation.

The actual FS changes will be handled by POSIX diff and patch.

New commands

We'll need one new zk command per feature. Both commands will fail if the new generated filenames already exist.

zk rename

Usage: zk rename <path> <new-title>

Rename the title of a note, updating all the backlinks and the note filename, if needed.

Arguments:
  <path>         Path to the note to rename.
  <new-title>    New title of the note.

Flags:
  -i, --interactive            Edit the changes before they are applied.
  -n, --dry-run                Don't actually rename the note. Instead, prints the changes on stdout
                               and the updated note path on stderr.

zk move

Usage: zk move <source> ... <target>

Move a note (or several) to a different path, updating all the backlinks.

Arguments:
  <source>    Paths to the notes or directories to move.
  <target>    Target directory or path if a single source note is given.

Flags:
  -i, --interactive            Edit the changes before they are applied.
  -n, --dry-run                Don't actually move the notes. Instead, prints the changes on stdout
                               and the updated note paths on stderr.

Interactive flag (-i)

The interactive flag offers an opportunity to edit the changes before they are applied. The confirmation is done in two steps, by editing temporary files (similar to git commit).

Step 1: Validate new paths

This edits a file containing all the filename/paths changes, with the following format:

• one file change per line
• source > target
• whitespaces (except inside a filename) are ignored

source.md > target.md
Foo.md > Bar Qux.md

The user can edit the target paths, or remove a line to cancel a file move.
Emptying the file cancels the whole process.

Step2: Validate diff changes

After validating the new paths, zk will generate all the file changes required (renaming titles, updating links) and generate a POSIX diff.

The user can edit any part of the diff, as long as the output is still a valid POSIX diff file. It will be applied as-is.
Emptying the diff file cancels the whole process.

Dry run (-n)

The dry run flag prints the content of the changes (as edited in the interactive flag) without applying them.

LCP integration

If the client sends a workspace.didRenameFiles event, the server will trigger the renaming process to update the links.

The user can update the title of a note manually using a RenameRequest when the caret is over the note title. This will trigger the renaming process to update the links and note filepath.

The LCP integration is not compatible with the interactive mode. The user is expected to backup their notes before such operation.

New config options

The user can configure the diff and patch commands used by zk from the config file.

[tool]
# Diff command used to edit the changes applied when renaming notes.
diff = "colordiff -u"

# Editor used to modify a diff when using the interactive mode.
# When missing, falls back on tool.editor.
diff-editor = "nvim"

# Patch command applying the changes when renaming notes.
# Use `patch --backup` to make backup copies of the files before they are modified.
patch = "patch"

Processes

Rename process

Given the note N that we want to retitle "T".

1. If the note.filename option for the note group of N contains the keyword title:
   1. Regenerate a new filename for N using the provided title T.
      • If the note.filename template contains a generated id, it will be randomized again. This should be fine as the inbound links will be updated anyway, but the user can decide to revert the id in interactive (-i) mode.
   2. If the process is in interactive mode, confirm the new filename with the user using tool.diff-editor.
      • The whole process is interrupted if the user empties the changes file.
   3. Move the file N to its new location.
2. Create a new compound diff file under .zk/DIFF.
3. Append to DIFF the result of replacing in the note content:
   • the old title of N by the new one T
   • the old filename by the new generated one, if needed
4. Iterate over all the notes linking to N, then for each link:
   1. Generate a new link using format.link-format with the new title T and generated filepath.
   2. Append to DIFF the result of replacing the old link by the new generated one.
5. If the process is in interactive mode, allow the user to edit the DIFF file using tool.diff-editor.
   • The whole process is interrupted if the user empties the changes file.
6. Apply the diff patch using tool.patch.
7. Re-index the notebook.

It's not a priority, but the link replacement algorithm could be smarter to try to preserve case changes or custom titles in a link.

Move process (single note as source)

Given the note N that we want to move to the new path P.

1. If P is a directory, append the filename of N to P.
2. Move the file N to its new location P.
3. Create a new compound diff file under .zk/DIFF.
4. Append to DIFF the result of replacing in the content of N:
   • the old filename by the new one
5. Iterate over all the notes linking to N, then for each link:
   1. Generate a new link using format.link-format with the new path P.
   2. Append to DIFF the result of replacing the old link by the new generated one.
6. If the process is in interactive mode, allow the user to edit the DIFF file using tool.diff-editor.
7. Apply the diff patch using tool.patch.
8. Re-index the notebook.

Move process (several notes or a folder as source)

Given the sources Sn that we want to move to the new folder P.

1. We expand each notes under Sn and append the child path portions to P to resolve the rename pairs.
2. If the process is in interactive mode, confirm the renames with the user using tool.diff-editor.
   * The whole process is interrupted if the user empties the changes file.
   * If only some lines of the file are removed, these files are skipped.
3. To simplify, we apply the "single note move process" described above to each rename atomically.
4. If there are empty folders in Sn, they are deleted.

Improvements

It's not a priority, but the link replacement algorithm could be smarter to try to preserve case changes or custom titles in a link.

[franco-ruggeri]

Great spec. I think it covers all the necessary. The interactive mode has IMO the least priority.

Has there been further work on this?

[igxlin]

@mickael-menu Look like some logic missing in moving process logic. The links inside the moved file should be updated too. For example, file foo.md move to bar/. Then the link ./path/to/file.md inside foo.md may need to be updated as ../path/to/file.md.

[ffflick-gh]

I believe this should be in scope for zk, because the README highlights do mention notebook housekeeping (and renaming is definitely a big part of it, not to mention the "housekeeping" only consists of two features as of now).

The renaming features suggested by @mickael-menu are quite comprehensive; personally I would be very happy with a simple renaming command that lets me do batch renaming using templates, something like the following:

# Change name format from "{{timestamp}}-{{CamelCaseTitle}}" to "{{timestamp}}-{{slug title}}"
zk rename Wiki/ "{{metadata.ctimestamp}}-{{slug title}}"

Since the notes already exist, the rename command can allow metadata and all other relevant fields in the template. This could provide very powerful renaming capabilities.

I am not a heavy user of the linking capabilities so I'm not sure how those would be handled.

[jamesl33]

Thought I'd weigh in with my use-case, and support for a KISS solution (as much as possible/is applicable).

I've been using a PARA/Zettelkasten approach, with a directory structure such as the following.

.
├── .gitmodules
├── .zk
│   ├── .gitignore
│   ├── config.toml
│   ├── notebook.db
│   └── templates
│       ├── bibliographic.md
│       ├── fleeting.md
│       ├── index.md
│       ├── literature.md
│       └── permanent.md
├── 0 Inbox
│   └── .gitkeep
├── 1 Projects
│   ├── .gitkeep
│   ├── Project 1
│   │   ├── 202509151405.md
│   ├── Project 2
│   │   └── 202509031323.md
│   └── Project 3
│       └── 202509011347.md
├── 2 Areas
│   ├── .gitkeep
│   └── Area 1
│       └── 202509011009.md
├── 3 Resources
│   └── .gitkeep
├── 4 Archives
│   ├── .gitkeep
│   └── Project 0 # No longer an active project
│       └── 202509011009.md
└── 5 Bibliography
    └── .gitkeep

I'd generally work within a project directory in "1 Projects" - e.g. writing up a design - then I'd move that into "4 Archives", the links within would probably be relative - so should resolve fine - however, it'd be great to have the peace-of-mind that these links get fixed up (especially if they link into "2 Areas" for example).

I personally use unique file-names, so appreciate the problem space there's far easier and that's not the case for everyone. I'm also quite happy to get involved implementing a solution, when we land on one.

[jamesl33]

For the benefit of others, the workflow I've highlighted above appears to work well with Wiki style links.

diff --git a/config.toml b/config.toml
index ee299df..002eb4f 100644
--- a/config.toml
+++ b/config.toml
@@ -81,13 +81,13 @@ template = "fleeting.md"

 # Format used to generate links between notes.
 # Either "wiki", "markdown" or a custom template. Default is "markdown".
-#link-format = "wiki"
+link-format = "wiki"
 # Indicates whether a link's path will be percent-encoded.
 # Defaults to true for "markdown" format and false for "wiki" format.
-#link-encode-path = true
+link-encode-path = false
 # Indicates whether a link's path file extension will be removed.
 # Defaults to true.
-#link-drop-extension = true
+link-drop-extension = true

 # Enable support for #hashtags.
 hashtags = true
@@ -128,7 +128,7 @@ multiword-tags = false
 # Each diagnostic can have for value: none, hint, info, warning, error

 # Report titles of wiki-links as hints.
-#wiki-title = "hint"
+wiki-title = "hint"
 # Warn for dead links between notes.
 dead-link = "error"

With this setup, you can use links such as [[202509080920]] which correctly resolve within different sub-directories.

The wiki-title = "hint" change allows you to hover over the link, to see the title.

TIL: You don't really need re-naming for the workflow shared above, although appreciate that won't be the case for everyone.

[gozes]

I use zk almost exclusively from within neovim so if rename where to finally be implemented it would be quite helpful if it was expose to the LSP so that renaming can happened from within the editor

[gozes]

For the benefit of others, the workflow I've highlighted above appears to work well with Wiki style links.

diff --git a/config.toml b/config.toml
index ee299df..002eb4f 100644
--- a/config.toml
+++ b/config.toml
@@ -81,13 +81,13 @@ template = "fleeting.md"

Format used to generate links between notes.

Either "wiki", "markdown" or a custom template. Default is "markdown".

-#link-format = "wiki"
+link-format = "wiki"

Indicates whether a link's path will be percent-encoded.

Defaults to true for "markdown" format and false for "wiki" format.

-#link-encode-path = true
+link-encode-path = false

Indicates whether a link's path file extension will be removed.

Defaults to true.

-#link-drop-extension = true
+link-drop-extension = true

Enable support for #hashtags.

hashtags = true
@@ -128,7 +128,7 @@ multiword-tags = false

Each diagnostic can have for value: none, hint, info, warning, error

Report titles of wiki-links as hints.

-#wiki-title = "hint"
+wiki-title = "hint"

Warn for dead links between notes.

dead-link = "error"

With this setup, you can use links such as [[202509080920]] which correctly resolve within different sub-directories.

The wiki-title = "hint" change allows you to hover over the link, to see the title.

TIL: You don't really need re-naming for the workflow shared above, although appreciate that won't be the case for everyone.

@jamesl33 thats not a bad idea. maybe the rename command should be more of a migration command where it goes ahead and add the id to to the file name and rewrites links to be [[{{metadata.id}}|{{title}}]]