Emacs undo-tree package

27 January 2021

Note: The undo-tree git repository has moved to Gitlab!
https://gitlab.com/tsc25/undo-tree

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.

Comments

Billy

16 June 2016 Cool, this package is the most excited package i ever used in emacs for servel years.

Billy

16 June 2016 Thanks a lot if author could move this package to github.

there will exist more collaborator and contributer to enhance this package a lot.

Martin

17 April 2017 Hi Toby,

I like what I have seen from you and on this page. I'll try out undo-tree now.

One remark, the latest version in Git is already 0.6.6. It would be great if you kept this web page and the download URL updated, because this page is the main information source for this package.

Cheers, Martin

Boruch

30 January 2019 Two questions:

  1. Are you in the loop as to why is the debian package seemingly so out of date? apt policy reports their version as 6.4.
  2. Now in 2019, is the git HEAD a stable improvement over the 6.6?

Toby Cubitt

12 February 2019 @Boruch #4:

  1. No clue why the Debian package is so old. But undo-tree has been available through GNU Elpa for ages now. I'd recommend installing it from there, rather than the distro package.
  2. The two changes sitting in git after the 6.6 release are so trivial, it hasn't seemed worth rolling a new release.

Alessandro

13 March 2019 Hi, I'm having quite some undo related issues which seem related to undo-tree. I'm using Spacemacs with vim keybindings. In a random fashion, the buffers lose undo information, so when I press "u" I get the dreaded "No further undo information." message.

Do you have any clue on what can cause this malfunctioning? Some hints on how to debug this issue would also be appreciated.

Aaron

18 April 2019 Hi Dr. Cubitt,

I believe undo-tree is no longer on MELPA. It is on ELPA, but the most recent release is 0.6.5. Some have upgraded via git/QUELPA to 0.6.6 in hopes that it would fix the "No further undo information" bug, but it doesn't appear to.

[https://github.com/syl20bnr/spacemacs/issues/12110] [https://github.com/syl20bnr/spacemacs/issues/9903#issuecomment-480567185]

If there is anything of note in 0.6.6 and you have the time and ability to publish those changes to ELPA, that'd be great. Thank you!

Abdo

14 June 2019 I frequently get corrupted nodes in the tree. Sometimes, I even get garbled text when undoing. I cannot quite pin down the reason, but is there a way to troubleshoot these problems when they happen?

Toby Cubitt

17 June 2019 @Alessandro #6, @Aaron #7, @Abdo #8:

I've been hearing about this issue for a long time now. Unfortunately, so far I've never encountered this issue myself, despite using global-undo-tree-mode. And no one has yet sent me a recipe that allows me to successfully reproduce it. Most (all?) of the reports seem to be from people using Spacemacs, so I wonder if the issue is to do with how undo-tree is integrated into Spacemacs, rather than the undo-tree package per se?

Until someone sends me steps to reliably reproduce this in vanilla Emacs + undo-tree, or I encounter this issue myself, it's extremely hard for me to investigate it.

There are only trivial changes in version 0.6.6, nothing that would fix this issue.

Timothy

7 January 2020 I'm not sure why but for (every?) file I open I tend to see:

Error reading undo-tree history from "home/tec.emacs.d/.local/cache/undo-tree-hist/.!home!tec….~undo-tree~.zst"

This is quite a pity to me, as other than that this package is fantastic, but losing all my history is definitely a killjoy.

Toby Cubitt

8 January 2020 @Timothy #10:

I'm not sure why you're seeing this specific error. It implies the Emacs read function cannot read a lisp object from the file at all. Have you checked the file it's trying to read from exists? If so, does Emacs decompress it automatically when you open it? (Note history file compression isn't configured out-of-the-box, so you must have set this up yourself.)

There are some subtle issues with history saving/loading in version 0.7, caused by compiling undo-tree under newer Emacsen. This is due to some changes in Emacs core since the last undo-tree release way back when. I've pushed an experimental bug-fix to git, and I'll roll out a version 0.7.1 release as soon as it's seen a bit more testing. If you're using the undo-tree-auto-save-history feature, probably best to hold off upgrading for now until version 0.7.1 is out, or (better still) help test the latest git. However, this fixes a different bug which affects saving undo history, not loading it. So I somewhat doubt this has anything to do with your issue.

As a general comment, I strongly advise against relying on persistent undo history for anything important, other than picking up editing where you left off last time. This applies whether you're using undo-tree, or one of the other Emacs packages that implement perstent undo history. Emacs undo history is not designed to be robust or reliable across Emacs sessions. Any file modification whatsoever outside of Emacs (or even within Emacs, but with undo-tree disabled) necessarily invalidates the entire undo history. If you want a reliable, robust, persistent history of prevous file versions, use a version control system. They're designed for that use-case. If you really want to store every change, you could try one of the Emacs packages that automatically commits to version control every time you save the buffer.

Toby Cubitt

9 January 2020 Version 0.7.1 is now available, above and on GNU Elpa.

Vincent Zhang

11 January 2020 I got this error with 0.7.1.

Error: (error (wrong-type-argument number-or-marker-p nil))
  (undo-tree-mode 1)
  (turn-on-undo-tree-mode)
  (global-undo-tree-mode)

Toby Cubitt

11 January 2020 @Vincent #13: I suspect this is already fixed in git, so have a try of that version. I'll roll out a new bug-fix release by the end of the weekend, once it's had a bit of testing by people.

Max

19 February 2020 Really awesome! Our programmers used IntelliJ IDEA, which includes a lot of proprietary extensions, however we decided to go with open source to reduce costs, so we are searching for EMACS plugins. Your package is very useful, and we just want to thank you for this great solution!

Han

27 January 2021 It seems the git repository is not available anymore?

> git clone [01]http://www.dr-qubit.org/git/undo-tree.git

Cloning into 'undo-tree'… fatal: repository 'http://www.dr-qubit.org/git/undo-tree.git/' not found

Toby Cubitt

28 January 2021 @Han #16: The repo died because my hosting provider is shutting down. I'm in the process of moving https://www.dr-qubit.org over to Gitlab Pages, but hadn't ported the repo yet.

I've now spun up a new undo-tree repo on gitlab: https://gitlab.com/tsc25/undo-tree and updated this page accordingly.

Leave a comment

All comments are moderated. Clicking submit will open your email client and let you send your comment by email. By submitting your comment you agree to license the content under a Creative Commons Attribution-ShareAlike 4.0 International License.




Creative Commons License