Enable Persistent Undo in Vim: Configuration, Usage, Limits, and Common Pitfalls

Enable Persistent Undo in Vim: Configuration, Usage, Limits, and Common Pitfalls

The useful answer: add set undofile (and optionally set undodir=~/.vim/undodir) to your .vimrc. After that, every time you write a file, Vim creates an undo file that records the full change history, letting you undo actions from previous sessions with the normal u and Ctrl‑R commands.

Configuration

Open your .vimrc (usually in ~/.vimrc) and insert the following lines:

set undofile
' optional: set undodir=~/.vim/undodir

Explanation: set undofile tells Vim to keep an undo history even after the buffer is closed. The undodir option specifies the directory where undo files are stored. If you omit it, Vim uses the same directory as the edited file, naming the undo file with the file’s full path where slashes are replaced by %. Using an absolute path such as ~/.vim/undodir avoids confusion caused by changing the current working directory when Vim starts.

Required permissions: the directory must be writable by the user running Vim. On Unix‑like systems you can create it with mkdir -p ~/.vim/undodir and give it write permission with chmod 755 ~/.vim/undodir.

How it works

When you edit a buffer and then issue a write command (:w), Vim writes a hidden file named after the original file with a .undo suffix (e.g., example%2Etxt.undo if the file path contains a slash). This file contains a complete undo tree, not just a linear list of changes. The tree lets you step forward and backward through all modifications, even those made in earlier Vim sessions, as long as the undo file still exists.

To test the feature, perform the following steps:

1. Start Vim and open a new file, for example vim test.txt.
2. Enter insert mode, type a few lines, then press Esc to return to normal mode.
3. Make a change, save with :w, and quit with :q.
4. Close Vim completely.
5. Re‑open the same file with vim test.txt.
6. Press u to undo the most recent change; press Ctrl‑R to redo.

If the text returns to the state before the change you made in the previous session, persistent undo is active.

Verification

Check that an undo file appears in the chosen directory. Run the command :echo expand('undodir') inside Vim; it should show the path you set (or the file’s directory if undodir is empty). Then execute :ls $HOME/.vim/undodir from a shell; you should see a file whose name matches the edited file’s path with % replacing slashes. For the test file test.txt, the undo file might be named test%2Etxt.undo.

Undo the changes you made in the previous session, then press Ctrl‑R. The text should revert to the state after the edits, confirming that the undo tree is being read correctly.

Limits and Common Mistakes

• Directory not writable: If undodir points to a location you cannot write to, Vim silently disables persistent undo. Verify with :set undodir? after starting Vim; it will show an empty value or a path you cannot access.
• Relative paths: Using a relative undodir (e.g., ./undodir) can place the undo files in unexpected locations, because the current working directory is taken from the shell that launched Vim, not from the directory of the edited file. Prefer an absolute path or expand $HOME.
• Undo file growth: Each undo file stores every change, so a heavily edited file can generate a large file. Vim automatically truncates the undo history when the total size exceeds the value of undolevels (default 10000) or when the buffer’s ulimit is reached. If you notice disk usage climbing, consider lowering undolevels or periodically cleaning the undo directory.
• Too many files: Over time, many undo files accumulate, especially if you frequently open and close different files. Set undoreload=10000 to limit the number of changes read back into memory, or schedule a cron job that removes old undo files.

Summary

Persistent undo is a simple configuration change that greatly improves the reliability of undo operations across sessions. By adding set undofile and optionally set undodir=~/.vim/undodir to your .vimrc, ensuring the directory exists and is writable, and testing with a short edit‑save‑quit cycle, you can confirm that Vim is writing undo files correctly. Watch out for unwritable directories, relative paths, and excessive file growth, and you’ll have a robust undo history that survives restarts.