How do I prevent a count prefix or visual range from corrupting an Ex command in a Vim mapping?

Q: How do I prevent a count prefix or visual range from corrupting an Ex command in a Vim mapping?

`: MyCommand ` When writing `nnoremap` or `vnoremap` mappings that call Ex commands, Vim may silently prepend a count or a visual range (`' `) to your command before it runs. Inserting ` ` immediately after the `:` erases that automatic prefix, giving you a clean command line every time. This is one of the most important patterns for writing robust, predictable mappings. ## How it works - In a mapping, after `:`, Vim may automatically insert things like `5` (a count) or `' ` (a visual selection range) - ` ` in command-line mode deletes from the cursor back to the beginning of the line, clearing whatever was auto-inserted - The mapping then executes the intended command without side effects ## Example A naive mapping that breaks with a count prefix: ```vim nnoremap w :write ``` If the user types `3 w`, Vim sends `:3write`, which writes to file number 3 — not what you want. The robust version: ```vim nnoremap w : write ``` Now `3 w` safely runs `:write`, ignoring the count. For a visual mode mapping: ```vim xnoremap s : call MySort() ``` Without ` `, Vim would insert `' ` before `call`, calling `:' call MySort()` — likely an error. With ` `, the function receives a clean command line and can use `' ` explicitly inside the function if needed. ## Tips - Always use `: ` in `nnoremap`, `xnoremap`, and `vnoremap` mappings that call Ex commands or functions - If your command intentionally needs the visual range, pass it explicitly: `: call MyFunc(line("' ")) ` - ` ` in insert mode deletes from cursor to start of line; in command-line mode it clears the line — the behavior differs by mode

Question

Accepted Answer

`:MyCommand` When writing `nnoremap` or `vnoremap` mappings that call Ex commands, Vim may silently prepend a count or a visual range (`'<,'>`) to your command before it runs. Inserting `` immediately after the `:` erases that automatic prefix, giving you a clean command line every time. This is one of the most important patterns for writing robust, predictable mappings. ## How it works - In a mapping, after `:`, Vim may automatically insert things like `5` (a count) or `'<,'>` (a visual selection range) - `` in command-line mode deletes from the cursor back to the beginning of the line, clearing whatever was auto-inserted - The mapping then executes the intended command without side effects ## Example A naive mapping that breaks with a count prefix: ```vim nnoremap w :write ``` If the user types `3w`, Vim sends `:3write`, which writes to file number 3 — not what you want. The robust version: ```vim nnoremap w :write ``` Now `3w` safely runs `:write`, ignoring the count. For a visual mode mapping: ```vim xnoremap s :call MySort() ``` Without ``, Vim would insert `'<,'>` before `call`, calling `:'<,'>call MySort()` — likely an error. With ``, the function receives a clean command line and can use `'<,'>` explicitly inside the function if needed. ## Tips - Always use `:` in `nnoremap`, `xnoremap`, and `vnoremap` mappings that call Ex commands or functions - If your command intentionally needs the visual range, pass it explicitly: `:call MyFunc(line("'<"), line("'>"))` - `` in insert mode deletes from cursor to start of line; in command-line mode it clears the line — the behavior differs by mode

Answer

Explanation

How it works

Example

Tips

Related Tricks

How do I control how many lines Ctrl-U and Ctrl-D scroll?

How do I enable an alternative digraph entry mode where I type two characters then backspace?

How do I profile Vim startup time to find out which plugins are slowing it down?

How do I encode and decode JSON data in Vimscript for configuration and plugin development?

How do I use glob() in Vimscript to get a list of files matching a wildcard pattern?