From db0223fc6857c160b2394489094355feb20318f2 Mon Sep 17 00:00:00 2001 From: Bill Ming Date: Wed, 30 Jan 2019 12:02:22 -0800 Subject: [PATCH] Updated doc --- doc/undotree.txt | 92 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 69 insertions(+), 23 deletions(-) diff --git a/doc/undotree.txt b/doc/undotree.txt index 61ff305..d56c4da 100644 --- a/doc/undotree.txt +++ b/doc/undotree.txt @@ -1,9 +1,8 @@ -*undotree.txt* Display your undo history in a graph +*undotree.txt* The undo history visualizer for VIM Author: Ming Bai Licence: BSD Homepage: https://github.com/mbbill/undotree/ -Version: 4.3 ============================================================================== CONTENTS *undotree-contents* @@ -34,13 +33,53 @@ CONTENTS *undotree-contents* ============================================================================== 1. Intro *undotree-intro* -Vim 7.0 added a new feature named Undo branches. Basically it's a kind of -ability to go back to the text after any change, even if they were undone. Vim -stores undo history in a tree which you can browse and manipulate through a -bunch of commands. But that was not enough straightforward and a bit hard to -use. You may use :help |new-undo-branches| or :help |undo-tree| to get more -detailed help. Now this plug-in will free you from those commands and bring -back the power of undo tree. +The plug-in visualizes undo history and makes it easier to browse and switch +between different undo branches. You might wonder what is undo "branches"? +It's vim feature that allows you to go back to a state when it is overwritten +by a latest edit. For most editors, if you make a change A, then B, then go +back to A and make change C, normally you won't be able to go back to B +because undo history is linear. That's not the case for Vim because it +internally keeps all the edit history like a tree structure, and this plug-in +exposes the tree to you so that you not only can switch back and forth but +also can switch between branches. + +Some people have questions about file contents being changed when switching +between undo history states. Don't worry, undotree will NEVER save your data +or write to disk. All it does is to change the current buffer little bit, just +like those auto-completion plug-ins do. It just adds or removes something in +the buffer temporarily, and if you don't like you can always go back to the +last state easily. Let's say, you made some change but didn't save, then you +use undotree and go back to an arbitrary version, your unsaved change doesn't +get lost - it stores in the latest undo history node. Clicking that node on +undotree will bring you back instantly. Play with undo/redo on other editors +is always dangerous because when you step back and accidentally typed +something, boom! You lose your edits. But don't worry, that won't happen in +Vim. Then you might ask what if I make some changes without saving and switch +back to an old version and then exit? Well, imaging what would happen if you +don't have undotree? You lose your latest edits and the file on disk is your +last saved version. This behaviour remains the same with undotree. So, if you +saved, you won't lose anything. + +We all know that usually undo/redo is only for the current edit session. It's +stored in memory and once the process exits, the undo history is lost. +Although undotree makes switching between history states easier, it doesn't do +more than that. Sometimes it would be much safer or more convenient to keep +the undo history across edit sessions. In this case you might need to enable a +Vim feature called persistent undo. Let me explain how persistent undo works: +instead of keeping undo history in RAM, persistent undo keeps undo history in +file. Let's say you make a change A, then B, then go back to A and make change +C, then you save the file. Now Vim save the file with content state C, and in +the mean time it saves the entire undo history to a file including state A, B +and C. Next time when you open the file, Vim will also restore undo history. +So you can still go back to B. The history file is incremental, and every +change will be recorded permanently, kind of like Git. You might think that's +too much, well, undotree does provide a way to clean them up. If you need to +enable persistent undo, type :h persistent-undo or follow the instructions +below. + +Undotree is written in pure Vim script and doesn't rely on any third party +tools. It's lightweight, simple and fast. It only does what it supposed to do, +and it only runs when you need it. ============================================================================== 2. Usage *undotree-usage* @@ -51,26 +90,30 @@ for example. > nnoremap :UndotreeToggle < -Then you can try to do some modification, and the undo tree will automatically -updated afterwards. +Markers -There are some hotkeys provided by vim to switch between the changes in -history, like |u|, ||, |g+|, |g-| as well as the |:earlier| and |:later| -commands. + * Every change has a sequence number and it is displayed before timestamps. -You may also switch to undotree panel and use the hotkeys to switch between -history versions. Press ? in undotree window for quick help of hotkeys. + * The current state is marked as > number <. -You can monitor the changed text in diff panel which is automatically updated -when undo/redo happens. + * The next state which will be restored by :redo or is marked as + { number }. -Persistent undo. -It is highly recommend to enable the persistent undo. If you don't like your -working directory be messed up with the undo file everywhere, you may add the -following line to your vimrc in order to make them stored together. + * The [ number ] marks the most recent change. + + * The undo history is sorted by timestamps. + + * Saved changes are marked as s and the big S indicates the most recent + saved change. + + * Press ? in undotree window for quick help. + +Persistent undo + +Usually I would like to store the undo files in a seperate place like below. > if has("persistent_undo") - set undodir='~/.undodir/' + set undodir=$HOME."/.undodir" set undofile endif < @@ -362,6 +405,9 @@ https://github.com/mbbill/undotree/issues ============================================================================== 5. Changelog *undotree-changelog* +Further changes will not be recorded. Please go to github page for more +information. + 4.4 (2017-10-15) - Autoload plugin functions