sponsor Vim development Vim logo Vim Book Ad

ReplaceWithRegister : Replace text with the contents of a register.

 script karma  Rating 106/33, Downloaded by 4486  Comments, bugs, improvements  Vim wiki

created by
Ingo Karkat
script type
Replacing an existing text with the contents of a register is a very common
task during editing. One typically first deletes the existing text via the
d, D or dd commands, then pastes the register with p or P. Most of
the time, the unnamed register is involved, with the following pitfall: If you
forget to delete into the black-hole register ("_), the replacement text is

This plugin offers a two-in-one command that replaces text covered by a
{motion}, entire line(s) or the current selection with the contents of a
register; the old text is deleted into the black-hole register, i.e. it's
gone. (But of course, the command can be easily undone.)

The replacement mode (characters or entire lines) is determined by the
replacement command / selection, not by the register contents. This avoids
surprises like when the replacement text was a linewise yank, but the
replacement is characterwise: In this case, no additional newline is inserted.

- ReplaceWithSameIndentRegister.vim (vimscript #5046) is a companion plugin
  for the special (but frequent) case of replacing lines while keeping the
  original indent.
- LineJugglerCommands.vim (vimscript #4465) provides a similar :Replace [["]x]
  Ex command.

- regreplop.vim (vimscript #2702) provides an alternative implementation of
  the same idea.
- operator-replace (vimscript #2782) provides replacement of {motion} only,
  depends on another library of the author, and does not have a default
- Luc Hermitte has an elegant minimalistic visual-mode mapping in
- EasyClip (https://github.com/svermeulen/vim-easyclip) changes the delete
  commands to stop yanking, introduces a new "m" command for cutting, and also
  provides an "s" substitution operator that pastes register contents over the
  moved-over text.
- R (replace) operator (vimscript #5239) provides an alternative
  implementation that defaults to the clipboard register.
- replace_operator.vim (vimscript #5742) provides normal (only with motion,
  not by lines) and visual mode mappings.
- subversive.vim (vimscript #5763) provides another alternative
  implementation, has no default mappings, and as a unique feature provides a
  two-motion operator that changes all occurrences in the moved-over range
  with typed text; something similar to the functionality of my ChangeGlobally
  plugin (vimscript #4321).

[count]["x]gr{motion}   Replace {motion} text with the contents of register x.
                        Especially when using the unnamed register, this is
                        quicker than "_d{motion}P or "_c{motion}<C-R>"
[count]["x]grr          Replace [count] lines with the contents of register x.
                        To replace from the cursor position to the end of the
                        line use ["x]gr$
{Visual}["x]gr          Replace the selection with the contents of register x.
install details
The code is hosted in a Git repo at
You can use your favorite plugin manager, or "git clone" into a directory used
for Vim packages. Releases are on the "stable" branch, the latest unstable
development snapshot on "master".

This script is also packaged as a vimball. If you have the "gunzip"
decompressor in your PATH, simply edit the *.vmb.gz package in Vim; otherwise,
decompress the archive first, e.g. using WinZip. Inside Vim, install by
sourcing the vimball or via the :UseVimball command.
    vim ReplaceWithRegister*.vmb.gz
    :so %
To uninstall, use the :RmVimball command.

- Requires Vim 7.0 or higher.
- repeat.vim (vimscript #2136) plugin (optional)
  To support repetition with a register other than the default register, you
  need version 1.1 or later.
- visualrepeat.vim (vimscript #3848) plugin (version 2.00 or higher; optional)

The default mappings override the (rarely used, but somewhat related) gr
command (replace virtual characters under the cursor with {char}).
If you want to use different mappings, map your keys to the
<Plug>ReplaceWithRegister... mapping targets _before_ sourcing the script
(e.g. in your vimrc):
    nmap <Leader>r  <Plug>ReplaceWithRegisterOperator
    nmap <Leader>rr <Plug>ReplaceWithRegisterLine
    xmap <Leader>r  <Plug>ReplaceWithRegisterVisual

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
ReplaceWithRegister-1.43.vmb.gz 1.43 2019-11-19 7.0 Ingo Karkat - BUG: {count}grr does not repeat the count.
- Suppress "--No lines in buffer--" message when replacing the entire buffer, and combine "Deleted N lines" / "Added M lines" into a single message that is given when either previous or new amount of lines reaches 'report'.
ReplaceWithRegister-1.42.vmb.gz 1.42 2014-10-29 7.0 Ingo Karkat - BUG: Previous version 1.41 broke replacement of single character with gr{motion}.
ReplaceWithRegister-1.41.vmb.gz 1.41 2014-05-28 7.0 Ingo Karkat - Also handle empty exclusive selection and empty text object (e.g. gri" on "").
ReplaceWithRegister-1.40.vmb.gz 1.40 2013-11-21 7.0 Ingo Karkat - Avoid changing the jumplist.
- Use optional visualrepeat#reapply#VisualMode() for normal mode repeat of a visual mapping. When supplying a [count] on such repeat of a previous linewise selection, now [count] number of lines instead of [count] times the original selection is used.
ReplaceWithRegister-1.31.vmb.gz 1.31 2012-11-28 7.0 Ingo Karkat BUG: When repeat.vim is not installed, the grr and v_gr mappings do nothing.
Need to :execute the :silent! call of repeat.vim to avoid that the remainder of the command line is aborted together with the call. Thanks for David Kotchan for reporting this.
ReplaceWithRegister.vba.gz 1.30 2012-03-26 7.0 Ingo Karkat - Adaptations for blockwise replace:
  - If the register contains just a single line, temporarily duplicate the line to match the height of the blockwise selection.
  - If the register contains multiple lines, paste as blockwise.
- BUG: v:register is not replaced during command repetition, so repeat always used the unnamed register. Add register registration to enhanced repeat.vim plugin, which also handles repetition when used together with the expression register "=. Requires a so far inofficial update to repeat.vim version 1.0 (that hopefully makes it into upstream), which is available at https://github.com/inkarkat/vim-repeat/zipball/1.0ENH1
- Moved functions from plugin to separate autoload script.
ReplaceWithRegister.vba.gz 1.20 2011-04-28 7.0 Ingo Karkat - BUG: ReplaceWithRegisterOperator didn't work correctly with linewise motions (like "+"); need to use a linewise visual selection in this case.
- BUG: Text duplicated from yanked previous lines is inserted on a replacement of a visual blockwise selection. Switch replacement mechanism to a put in visual mode in combination with a save and restore of the unnamed register. This should handle all cases and doesn't require the autoindent workaround, neither.
ReplaceWithRegister.vba.gz 1.10 2011-04-21 7.0 Ingo Karkat - The operator-pending mapping now also handles 'nomodifiable' and 'readonly' buffers without function errors.
- Add experimental support for repeating the replacement also in visual mode through visualrepeat.vim. Renamed vmap <Plug>ReplaceWithRegisterOperator toPlug>ReplaceWithRegisterVisual for that. *** PLEASE UPDATE YOUR CUSTOM MAPPINGS ***
ReplaceWithRegister.vba.gz 1.03 2011-01-09 7.0 Ingo Karkat - ENH: Better handling when buffer is 'nomodifiable' or 'readonly'.
- Added separate help file and packaging the plugin as a vimball.
ReplaceWithRegister.vim 1.02 2009-12-11 7.0 Ingo Karkat Replaced the <SID>Count workaround with :map-expr and an intermediate expression.
ReplaceWithRegister.vim 1.01 2009-10-06 7.0 Ingo Karkat Do not define "gr" mapping for select mode; printable characters should start insert mode.
ReplaceWithRegister.vim 1.00 2009-07-05 7.0 Ingo Karkat Initial upload
ip used for rating:

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.
Vim at Github