Toby 'qubit' Cubitt - Emacs undo-tree package (original) (raw)

27 January 2021

Emacs has a powerful undo system. Unlike the standard undo/redo system in most software, it allows you to recover any past state of a buffer (whereas the standard undo/redo system can lose past states as soon as you redo). However, this power comes at a price: many people find Emacs' undo system confusing and difficult to use, spawning a number of packages that replace it with the less powerful but more intuitive undo/redo system. (See the Emacs Wiki.)

Both the loss of data with standard undo/redo, and the confusion of Emacs' undo, stem from trying to treat undo history as a linear sequence of changes. It's not. The undo-tree-mode provided by this package replaces Emacs' undo system with a system that treats undo history as what it is: a branching tree of changes. This simple idea allows the more intuitive behaviour of the standard undo/redo system to be combined with the power of never losing any history. An added side bonus is that undo history can in some cases be stored more efficiently, allowing more changes to accumulate before Emacs starts discarding history.

It gets better. You don't have to imagine the undo tree, because undo-tree-mode includes an undo-tree visualizer which draws it for you, and lets you browse around the undo history.

The only downside to this more advanced yet simpler undo system is that it was inspired by Vim. But, after all, most successful religions steal the best ideas from their competitors!

Documentation

Details of the undo-tree-mode commands and key bindings can be found in the Commentary section at the top of the undo-tree.el file itself, along with an extended explanation (with diagrams!) of the differences between the undo-tree-mode, standard Emacs' undo, and undo/redo systems.

The commands themselves are all documented using the standard, built-in Emacs documentation features. Customization options can be found under the undo-tree customization group.

Download and Installation

In recent versions of Emacs (>=24.1), you can install the undo-tree package from within Emacs itself, via GNU ELPA. Use M-x list-packages and take it from there. This is the preferred installation method. (Occasionally, the ELPA version might lag slightly behind the latest version available here.)

The current "stable" release of the undo-tree package is version 0.8.1 (released February 2021). It's relatively stable, though bug fixes and new features are added occasionally. (A few older versions are also available below, but are no longer supported.)

If you want to live on the bleeding edge, the latest "development" version of the undo-tree package is hosted in a gitlab repository.

Unless you obtained undo-tree from ELPA (which takes care of package installation for you), to install the undo-tree package, simply save the undo-tree.el file to a directory in your Emacs load-path, and add the line:

(require 'undo-tree)

to your .emacs file. M-x undo-tree-mode will then enable undo-tree-mode in the current buffer.

If you want to replace the standard Emacs' undo system with the undo-tree system in all normal buffers, you can enable undo-tree-mode globally by adding:

(global-undo-tree-mode)

to your .emacs file.

Bugs, Feature Requests, and Contributing

Bugs, feature requests, and any other feedback should be addressed to toby-undo-tree@dr-qubit.org. (Note that this address is protected by the TMDA spam-reduction system. The first time you send an email, you will have to verify your address by replying to a confirmation message.)

If you have code you would like to contribute to undo-tree, either send a patch against the latest development version to toby-undo-tree@dr-qubit.org. Or, better still, use git, rebase your work against the latest git master, and let me know where to find your clone of the undo-tree repository so that I can pull your changes.

I maintain undo-tree in my spare time, which is in very short supply these days! So I tend to batch-process bug reports, feature requests and patches at intervals of a year or more. If you contact me about undo-tree and don't receive a response, it's not because I'm ignoring you or didn't receive your email. You're just in a queue of indeterminate length until the next undo-tree batch job runs. It does run eventually, though.

There are numerous comments on the internet about seeing the message "No further undo information" and losing all undo history. If you encounter this, the answer is likely to be: increase the value of the undo-limit configuration variable. Recent releases of undo-tree do this for you, and other things to improve the user experience. I wrote a blog post discussing this and other undo-tree issues in detail.