doomemacs/modules/emacs/undo/README.org

#+title:    :emacs undo
#+subtitle: Persistent, smarter undo for your inevitable mistakes
#+created:  April 14, 2020
#+since:    21.12.0

* Description :unfold:
This module augments Emacs' built-in undo system to be more intuitive and to
persist across Emacs sessions.

** Maintainers
- [[doom-user:][@hlissner]]

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +tree ::
  Uses [[doom-package:undo-tree]] instead of [[doom-package:undo-fu]], which is a little less stable, but offers
  branching undo history and a visualizer for navigating it.

** Packages
- [[doom-package:undo-fu]]
- [[doom-package:undo-fu-session]]
- [[doom-package:undo-tree]] if [[doom-module:+tree]]
- [[doom-package:vundo]]

** Hacks
- Both undo-fu and undo-tree have been modified to use =zstd= to compress undo
  history if it is available.
- undo-tree only
  - Text properties are stripped from undo history to shrink it.
  - Undo-tree is too chatty about saving its history files. This has be
    "silenced". i.e. It's visible in \*Messages\*, but won't appear in your
    minibuffer.
- unfo-fu only
  - Doom defines ~undo-fu-mode~ to make it easier to add hooks/mode-local
    keybinds.

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

/This module has no external requirements./

* TODO Usage
#+begin_quote
 🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote

* TODO Configuration
#+begin_quote
 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Disabling persistent undo history
- If you are using [[doom-module:+tree]]:
  #+begin_src emacs-lisp
  (after! undo-tree
    (setq undo-tree-auto-save-history nil))
  #+end_src

- If you aren't:
  #+begin_src emacs-lisp
  (remove-hook 'undo-fu-mode-hook #'global-undo-fu-session-mode)
  #+end_src

* Troubleshooting
[[doom-report:][Report an issue?]]

** undo-tree
- Has been known to truncate undo history unpredictably, due to Emacs' undo
  cleanup imposing linear undo limits on non-linear undo tree data. Doom already
  sets ~undo-limit~, ~undo-strong-limit~, and ~undo-outer-limit~ absurdly high
  to mitigate this somewhat.

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote