sponsor Vim development Vim logo Vim Book Ad

YankRing.vim : Maintains a history of previous yanks, changes and deletes

 script karma  Rating 905/612, Downloaded by 17819    Comments, bugs, improvements  Vim wiki

created by
David Fishburn
 
script type
utility
 
description
Vim already maintains a list of numbered registers containing the last 9 deletes.  These previous deletes can be referenced using [register]p, so "1p will paste the last delete, "2p the 2nd last delete.  For more information see |quote_number|.

Vim does not provide any mechanism to reference previous yanked, deleted or changed text.  In Emacs this feature is called the "kill ring".

The YankRing plugin allows the user to configure the number of yanked, deleted and changed text.  A split window can be used to choose which element(s) from the yankring you wish to paste.  Alternately after text has been pasted (using p), it can be replaced with a previous value from the yankring with a single key stroke.

The captured text is stored in a file (location configurable) and is instantly available (also configurable) to any other instance of Vim also running on the same machine.  This can especially be useful on *nix machines when you are sshed in running Vim in multiple terminals.

Storing the capture text in a file allows the text to be shared easily between multiple instances of Vim running in X, Windows, SSH or Screen.

A tutorial is included to take you through the various features of the plugin.  After you have installed the plugin just run:
     :h yankring.txt
     :h yankring-tutorial

The yankring can be interacted with in two ways:  a GUI or via maps.

The yankring supports all of Vim motions and text-objects.  There are very few new keystrokes the user must learn.   One keystroke to open the yankring to choose which item to paste is all that is required.  It has been designed work seamlessly with Vim

All the mappings and behaviours are configurable via global variables you can optionally specify in your vimrc.

The plugin can be toggled on and off, and supports:
    Ranges
    Registers
    Counts
    All visual modes (characterwise, linewise and blockwise)
    All motions
    All text-objects

Examples:
    yy - Adds the current line to the yankring.
    dd - Adds the current line to the yankring and deletes it.
   5yw - Adds 5 words to the yankring.
  "ade - Deletes the word, and puts it into both the yankring and the "a register.
    cw - Changes the word and stores the previous value in the yankring.
10"zyy - Places 10 lines into both the yankring and the "z register.
:1,4YRYankRange   - Similar to 1,4y
:3,$YRDeleteRange  - Similar to 3,$d

If you wish to paste previous values from the yankring and do not want to use the GUI, there are only two additional maps you must learn (these are configurable via your vimrc if needed).  The purpose of the yankring is to gain access to previously yanked (or deleted) elements.  The YRReplace command will replace the previously pasted text with a different entry from the yankring.  By default, I choose <C-P> (P for previous) to replace the text last pasted while moving backwards through your previous text from the yankring and <C-N> (N for next) to replace the previous paste while moving forward through the yankring.

A separate buffer window to allow you to easily interact with the contents of the yankring.  The window is similar to many other plugins: TagList, SelectBuf and so on.  You can use the mouse or standard Vim keys (p, gp, P, ...).  Visual mode is used to support counts, pasting multiple times and reversing the order of pasted elements.

The GUI significantly simplifies your interaction with the yankring for basic functions.  But often it useful to take advantage of the more powerful features of the yankring.

Here is a small section from the tutorial (using maps) so you have some idea of how you interact with the plugin gaining access to previous yanks.  Using the GUI for basic operations is self explanatory.

:h yankring-tutorial

---- Partial Tutorial ----
To understand how to use the yankring, the following example should demonstrate the various features.

Assume we have this buffer:
        one
        two
        three
        four
        five

Now yank (yy) each line separately starting at line 1.  Display the
contents of the yankring.
        :YRShow  
            --- YankRing ---
            Elem  Content
            5     five^@
            4     four^@
            3     three^@
            2     two^@
            1     one^@
Since we yanked the text starting at line 1 and finishing at line 5, the most current yankring element is the last one, the contents of line 5.  
"five^@" is displayed, the "^@" is a newline character (since we issued a "yy").

Now, go to the end of the file and press p.  The resulting buffer appears as:
        one
        two
        three
        four
        five
        five
Now press <C-P> to move backwards through the yankring, this results in:
        one
        two
        three
        four
        five
        four
Now press 2<C-P>.  This would be the same as pressing <C-P> two times in a row.  This results in:
        one
        two
        three
        four
        five
        two
Now press <C-N> to move forwards through the yankring, this results in:
        one
        two
        three
        four
        five
        three

You can create a map to display a buffer displaying the yankring's contents:
    nnoremap <silent> <F11> :YRShow<CR>

YRShow creates a new split buffer (you can configure where it should be and it's size)
        :YRShow  
            AutoClose=1;Cmds:<enter>,[g]p,[p]P,d,r,a,u,q,<space>;Help=?
            --- YankRing ---
            Elem  Content
            3     three^@
            2     two^@
            1     one^@
            5     five^@
            4     four^@
You can simply hit "p", <enter>, double click on an item and it will be pasted into your document.  The window will automatically close (by default) after you have made a choice.  The element will be pasted into the correct buffer if you have multiple split windows.

You can paste multiple items using visual mode.
You can also remove items from the yankring.

---- Partial Tutorial ----

Concentrating on the last line of the buffer you could see how we were able to replace our pasted text with lines yanked previously.  This is a feature Vim only has for deletes, and is limited to 9.  This plugin enables the same features for both yanks, deletes and changes, the size of the history is configurable.



 
install details
YankRing 4.0 and above, uses new features of Vim 7.2 which allows it to support all motions and text-objects Vim provides.  
If you are using Vim 7.1 or below it will still work as it did in previous versions.
YankRing 3.0, Vim 7 is required.
YankRing 2.2 requires Vim 6.2 or higher.

Copy the yankring.vim script to your $HOME/.vim/plugin (or $VIM/vimfiles/plugin for windows) directory.  
Copy yankring.txt to your $HOME/.vim/doc (or $VIM/vimfiles/doc for windows) directory.

To update the Vim Help, run:
:helptags $HOME/.vim/doc  (Unix)
:helptags $VIM/vimfiles/doc  (Windows)
 

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
yankring_180.zip 18.0 2013-09-25 7.0 David Fishburn NF: Handle the @: command (Lingnan Dai).

NF: Added new global option to specify the YankRing buffer name, g:yankring_buffer_name (Štefan Sakalík).

BF: Did not properly highlight new commands in the YankRing window (Thilo Six).
yankring_170.zip 17.0 2013-04-28 7.0 David Fishburn NF: The yankring_history_dir option can now take a comma separated list.  First valid directory found will be used (Alex Bel).

NF: YankRing can now monitor inserted text and place it in the ring. This is disabled by default, but can be enabled either through the YankRing window or via your .vimrc using the new option:
    g:yankring_record_insert = 1 (Alexandre Viau).

BF: When g:yankring_persist = 0, the YankRing was still reading and writing to the yankring file (Vladimir Marek).

BF: The YankRing menu entry, "Replace with Next", was performing the "Replace with Previous" action (Thilo Six).
yankring_160.zip 16.0 2013-01-20 7.0 David Fishburn BF: YankRing could report "YR: A register cannot be specified in replace mode" when using clipboard = unnamed or unnamedplus.  This can often happen when fetching previous values from the YankRing (i.e. <C-N> or <C-P>).
yankring_150.zip 15.0 2013-01-02 7.0 David Fishburn NF: Automatically turn off relativenumber for the YankRing window (Emma Tramp).

NF: The YankRing window supports 1-9 to choose to paste those items for quicker access to the top 9 items.

BF: When re-executing a macro using @<letter> and the macro used f, F, t, T, a "Press ENTER to continue" prompt was displayed (Greg Sexton).

BF: Some documentation updates and script tweaks (Dominique Pellé).

BF: The 0 register was updated during delete operations (Christian Brabandt).

BF: When running a macro (@a), pressing @ displays a YankRing prompt (YR:Enter character:) to choose which macro name to run.  This prompt was displayed twice leading to a "Press ENTER or type command to continue" Vim message.  This change suppresses the "Press ENTER" message (Greg Sexton).

BF: The YankRing prevented you from re-running the last macro using @@.

BF: YRToggle (to disable / enable the YankRing) did not unmap @.

BF: When prompted for a macro to run, if an invalid value was provided, Vim could report "E354: Invalid register name".

BF: When using a Vim instance with < 80 columns and using a horizontal YankRing window after opening and closing the YankRing window the Vim window did not shrink back to its original size (Eric Weir).

BF: Updated documented values of yankring_window_height and yankring_window_width (Paul).

BF: It was not possible to paste from the * register if the clipboard option contains unnamedplus before unnamed (Marcin Szamotulski).
yankring_140.zip 14.0 2012-04-05 7.0 David Fishburn NF: The YankRing window supports 1-9 to choose to paste those items for quicker access to the top 9 items.
NF: The YankRing now maps the @ key to run macros.  Not all actions performed during the macro are recorded by the YankRing as a number of items had to be unmapped to support the replay of actions which can prompt the user for input (i.e. t and f) (Asis Hallab).
BF: When flipping between applications the system clipboard was not added to the YankRing in all cases.
BF: The YankRing could report E121: Undefined variable: g:yankring_manual_clipboard_check (Thilo Six).
BF: The YankRing could report: E132: Function call depth is higher than 'maxfuncdepth'.  When executing a YRClear or YRPop or when flipping between applications (Marcin Szamotulski).
BF: Strange behaviour when opening the YankRing with :e [YankRing] instead of :YRShow (Marcin Szamotulski).
yankring_130.zip 13.0 2012-02-28 7.0 David Fishburn NF: [p, ]p, [P, ]P are now supported within the YankRing window (Alexandre Provencio).

NF: When using the console version of Vim the yankring was not detecting the "+ register automatically as the FocusGained event does not fire in console mode.  When new elements are added or the YankRing is shown the clipboard will be checked for new values (Giuseppe Rota).

NF: Added a new option, g:yankring_manual_clipboard_check which when enabled will manually check for clipboard changes at certain times within the YankRing.  This option is not used if the GUI is running as the FocusGained will perform checks at appropriate times (Erik Westrup).

BF: With clipboard=unnamed replacing the previous paste with a different value from the YankRing did not work in all cases (Chris Lott).

BF: Under certain conditions the YankRing would still check the system clipboard even if g:yankring_clipboard_monitor == 0.  This can lead to delays when attempting to access the clipboard when running in console mode.  Starting Vim with the -X switch removes the delay (Erik Westrup).

BF: Incorrect syntax setting cpoptions (Thilo Six).
yankring_120.zip 12.0 2011-09-17 7.0 David Fishburn NF: Added support for the clipboard option "unnamedplus" which was added after 7.3 (Hong Xu).

NF: When displaying the YankRing using YRShow, a new command "R" has been added to display all of Vim's registers [0-9a-z].

BF: YRMapsDelete did not remove the normal mode @ map, which interfers with recorded macros (Philippe Vaucher ).
yankring_110.zip 11.0 2010-08-12 7.0 David Fishburn NF: Documented the global variables to customize the location of the YankRing menu.

NF: The YankRing menu now shows the maps used for the default actions to help learn them more easily.

NF: Added g:yankring_menu_root and g:yankring_menu_priority (David Barsam).

NF: Added a warning indicating a stored value has been truncated based on g:yankring_max_element_length and a new option to suppress this warning, g:yankring_warn_on_truncate (Hans-Günter).

BF: The YRAfterMaps() function (if it exists) was not re-run if YRToggle was used to disable and enable the YankRing.

BF: Multibyte strings may not have been pasted correctly (Dr. Chip).

BF: When pasting a string of 1111's, and additional -1 could also be included in the output.
yankring_100.zip 10.0 2010-02-01 7.0 David Fishburn NF: Change the buffer name to [YankRing] to resemble other non-user buffers.

NF: Added g:yankring_min_element_length which can prevent items from being added to the YankRing if they are too small.  For example, single character deletes (Vedran M).

BF: When shifting focus back to Vim, the YankRing may incorrectly report: "YR:Failed to change to the yankring buffer, please contact author".

BF: When entering Vim for the first time and hitting "p" nothing was pasted (Mark Huiskes).

BF: When entering Vim for the first time and the yankring_clipboard_monitor = 1, the clipboard entry was not automatically added to the yankring.

BF: When overriding the default and setting g:yankring_window_use_bottom = 0, the YankRing would report the error (Sergey Khorev):  E21: Cannot make changes, 'modifiable' is off
yankring_90.zip 9.0 2009-08-30 7.0 David Fishburn BF: You cannot execute a macro with ":normal @a".  It is still not possible, but you can execute it with ":normal! @a" (A S Budden).  
BF: When g:yankring_persist = 0 the YankRing could go into an infinite loop (A S Budden).  
BF: When replaying a macro which used any of the zap keys (f,F,t,T,/,?) you were prompted again for the string to match on (Ovidiu C).
BF: When checking the clipboard for changes (g:yankring_clipboard_monitor == 1) only add the item if it is not already in the ring.  Previously, the item was moved to the top of the YankRing each time you flipped focus.
yankring_80.zip 8.0 2008-12-30 7.0 David Fishburn NF: Changed the implementation of YRGetSearch() (David Liang).
BF: Under some unknown circumstances, the yankring can fail to change to the correct buffer.  Put in code to double check and abort.
BF: Yanking and pasting a line which ends in a backslash resulted in the backslash being replaced by "@@@".
BF: When repeating a command (".") which used any of the zap keys (f,F,t,T,/,?) you were prompted again for the string to match on (Vasilii Pascal).
yankring_70.zip 7.0 2008-11-15 7.0 David Fishburn NF: Added support for the / and ? motions so that y/search is supported (Vasilii Pascal).
NF: When the YankRing window is displayed (or updated) an additional check is made against the default register.  If it has changed since the YankRing recorded it, the value will be added to the history.
NF: Added support for more motions h, j, k, l, H, M, L, ^, 0, -, +, _.  And a pile of g motions g_, g^, gm, g$, gk, gj, gg, ge, gE.
NF: The YankRing window will display a message it is operating in a limited mode if not using Vim 7.2 or the correct patch level.
BF: Correction to some internal code which could lead to an endless loop (John Beckett).
BF: Opening and closing the YankRing window with "set report=0" reported "1 line less" messages (Bill McCarthy).
BF: Changed the default value of g:yankring_paste_check_default_buffer to check if the default paste buffer has changed when pressing 'p'.  For example, if a plugin has changed the default registers it will be pasted rather than the top item from the YankRing.
BF: YRMapsDelete did not remove all the maps created by the YankRing.
BF: Under particular circumstances, yanking text with embedded @ characters were not properly stored and retrieved from the YankRing (Andrew Long).
BF: Changed to use xmaps instead of vmaps so that the maps only work in visual mode and not select mode (David Liang).
yankring_61.zip 6.1 2008-10-31 7.0 David Fishburn BF: If the g:yankring_history_dir contains spaces (default on Windows) an error was reported.  A simple work around was to let g:yankring_history_dir = 'c:\Vim' or no spaces (Matt).  
All Windows users should download this version.
yankring_60.zip 6.0 2008-10-30 7.0 David Fishburn NF: The YankRing now maintains the history in a file.  This means if you are running multiple instances of Vim, they all see the same yankring whether you are using X, Windows, SSH or Screen.
NF: The location and name of the file is configurable by the user.
NF: The g:yankring_separator is no longer used and has been removed.
NF: The g:yankring_max_element_length can be used to limit the size of an element in the yankring.
NF: The g:yankring_share_between_instances can be used to indicate whether each instance of Vim running on a machine should share the history file or whether each should have their own individual history file.
NF: The g:yankring_clipboard_monitor can be used to indicate whether changes to the system clipboard should be added to the YankRing (default is on).
NF: The YankRing window can toggle the clipboard monitor by pressing 'c'.  See the help in the window by pressing ?.
NF: Added some highlighting to the YankRing window (Marty Grenfell).
yankring_50.zip 5.0 2008-09-22 7.0 David Fishburn NF: The yankring can recognize certain Vim commands which do not change the contents of a buffer and not attempt to capture it.
NF: The global variables which allow you to customize the behaviour are now space separated instead of comma separated.  This provides greater flexibility but will require you to modify your vimrc (if you have customized it). (Andy Wokula)
BF: If using <C-O> from within insert mode, the yankring inserted characters into the buffer instead of capturing the changes, this was fixed by Andy Wokula (Agathoklis Hatzimanikas).
BF: The yankring did not properly account for all the different forms of counts "5yy" worked but "y5y" did not (Edwin Shao).
yankring_41.zip 4.1 2008-08-09 7.0 David Fishburn NF: The yankring now allows you to override which operators should be ignored (yankring_ignore_operator).  By default this is set for the standard Vim operators which do not modify any registers (Examples: = and gu) (Andy Wokula).
NF: The yankring did not map v_x (Matt Tolton).
BF: The expression register (quote=) was not accounted for correctly (Agathoklis Hatzimanikas).
BF: Using the v:operator variable must be escaped when used in a regular expression.
yankring_40.zip 4.0 2008-06-24 7.0 David Fishburn NF: The yankring by default now captures all |text-objects| and all motions (|motion.txt|) which Vim supports.  Version 3.0 only supported a subset of the basic motion commands.
NF: Prior to this version only predefined maps triggered the capture of data into the yankring.  These maps only supported yanks and deletes.  The yankring now also supports operator-pending mode, which allows a greater range of operations to be automatically captured and added to the yankring.  
Operating pending mode functionality requires Vim 7.2 or Vim 7.1 with patch #205.  If using Vim 7.1 you can determine this with:
       echo has("patch205")
NF: Prior to this version only yanks and deletes were registered in the yankring.  Changes are now also captured into the yankring.
NF: The yankring will also capture the system cliboard when focus is returned to the vim window.  This is useful if you copy text between applications.
NF: The yankring window always opened bottom horizontal.  Now it can be opened top or bottom and horizontal or vertically.  This can be controlled via variables in your .vimrc.
BF: The yankring has an option to persist between instances of Vim by storing the values in global variables within the viminfo.  This has led to some unusual ordering of items in the ring from conflicts between instances.  This option has been turn off by default.
BF: Their was an issue with yanking using y$.
yankring_30.zip 3.0 2007-09-07 7.0 David Fishburn NF: Converted the yankring to use the new Vim7's List object which means it is no longer compatible with Vim6.
NF: By default the yankring will now maintain the yankring's items persistently by default.  It does this via the |viminfo| file. This means the contents of the yankring rely on the internal variables of only 1 Vim instance.
BF: YRToggle was not unmapping 'gp' and 'gP'.
BF: YRSearch prompted the user for a regex even if one was provided on the command line.
BF: If g:yankring_manage_numbered_reg is enabled, the "." operator did not correctly repeat the previous action (Pedro DeRose).
yankring_22.zip 2.2 2005-10-21 6.0 David Fishburn BF: If you pressed '?' to toggle the display of the help in the
yankring window, the yankring window would close.  This also applied to
'a', which allowed you to toggle the autoclose feature.
yankring_21.zip 2.1 2005-10-11 6.0 David Fishburn NF: Much improved usability, the yankring now has a "GUI" to service
    the yankring.  If YRShow or YRSearch is used, a split buffer is
    opened which displays all the elements in the yankring.  There
    are a number of maps that allow you to interact with the
    contents.  The window can be positioned vertically or
    horizontally as well as being sized all through options
    specified in your vimrc.
NF: Added the ability for the yankring to override Vim's numbered
    registers.  Instead of the numbered registers holding the last
    yanked value, and the 9 previous deletes, they will now reflect
    the top 10 items in the yankring.  This allows you to reference
    them directly with "5p.
NF: YRPop can now delete any items from the yankring, rather
    that just from the top.
NF: YRSetTop has been removed, it is no longer required as the
    internal representation of the yankring has changed.
BF: If g:yankring_ignore_duplicate is set (which is the default)
    you could get some unpredicable results when moving
    backwards and forwards (<C-P> and <C-N>) through the
    previous values.
yankring_20_beta1a.zip 2.0 Beta1a 2005-08-22 6.0 David Fishburn Some people reported an error when selecting the first item from the yankring.
yankring_20_beta1.zip 2.0 Beta1 2005-08-20 6.0 David Fishburn Added a new split buffer that allows you to visually interact with the yankring.  This makes using it much better, no more commands you need to remember.
Previous commands are still available.  The new buffer is configurable.  Please see the tutorial for further details.

Feedback is greatly appreciated.
yankring_16.zip 1.6 2005-05-07 6.0 David Fishburn NF: YRSearch is similar to YRGetElem.  Given a regular expression it will interactively display all the elements in the yankring that match the regular expression.  You can enter the number of the element to paste it.  If you have many elements within the yankring, this can help you identify them more easily.
NF: Updated the default history size from 30 to 100, which is partially the reason for the YRSearch command.
NF: By default it supports "gp" and "gP", in addition to "p" and "P".
NF: Added support for the expression register (:h quote=).  Here is an example of how it is used:
       "="X"<CR>P
yankring_15.zip 1.5 2005-04-01 6.0 David Fishburn NF: The yankring now respects the cpoptions setting, if 'y' is included and you press '.', the previous yank command is executed and added to the yankring.  You can also add this behaviour by setting this in your |vimrc|:
       let g:yankring_dot_repeat_yank = 1

NF: Duplicates will not be added to the yankring by default.  If a duplicate is found, the element will be moved to the top of the yankring.  This can be controlled by setting this in your |vimrc|:
       let g:yankring_ignore_duplicate = 0 (1 is default)

BF: Regression from version 1.4, the '.' operator may incorrectly insert garbage.
yankring_14.zip 1.4 2005-03-27 6.0 David Fishburn NF: YRToggle has been updated.  If you toggle the yankring off (disable) the maps it creates are removed.  Calling YRToggle again will recreate the maps.  This truly disables the yankring, where the previous version attempted to do this via code.
BF: Using the '.' operator was not corrected replaying operations that did not move text in some way (g~t_) changed the case of the text but a '.' did not replay it.
BF: When replacing previously pasted text the yankring did not respect what key was used to paste the text originally.  All replaced items were pasted using 'p', even if you had originally pasted the text with 'P'.
ip used for rating: 54.81.76.147

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
   
SourceForge.net Logo