Notes for working with Xcode VIM mode

xcode-vim.markdown

Xcode VIM

Learning VIM in Xcode comes with its own set of challenges and limitations, but there is enough there for you to give your mousing hand a break and master the keyboard.

A limited set of commands are available in Xcode, and this document attempts help ease the learning curve of using VIM in Xcode by providing a handy reference as well as what I find works for me in practice.

NOTE: Commands are case-sensitive. A command of N means pressing shift + n on the keyboard.

This document is a work in progress! Leave a comment if you would like to see a change.

---

Normal Mode Commands

Basic Navigation

Vim Input	Xcode Standard	Action
h	←	move left
l	→	move right
k	↑	move up
j	↓	move down
0	↖	move to first character in line. e.g. "move to column zero"
$	↘	move to last character in line
^	⌘←	move to first non-whitespace character in line
g0	⌘←←	goto before first non-whitespace character in line
g_	⌘→	goto to last printed character in line
gg	⌘↑	goto to first line in file
G	⌘↓	goto to last line in file
%	-	move to matching character in pair, e.g. {}, ()
{	-	jump to next paragraph above
}	-	jump to next paragraph below
]	-	jump ahead to input brace ({ or }). e.g. when in a function, type ]} to move forward to next closing brace for the current scope.
[	-	jump back to next input brace ({ or }).

Word Navigation

Vim Input	Xcode Standard	Action
w	⇧→	jump forward to start of word
W	⌃→	jump forward to start of Word, ignoring punctuation
e	-	jump forward to end of word
E	-	jump forward to End of word, ignoring punctuation
b	⇧←	jump backward to start of word
B	-	jump Backward to start of word, ignoring punctuation
gd	^⎇J	go to definition

Scrolling the Viewport

Actions that scroll the code viewport without moving the cursor.

Vim Input	Action
zz	scroll viewport to center on current line
zt	scroll line to top of viewport
zb	scroll line to bottom of viewport
z⏎	position viewport so the current line is at the top. e.g. Show me what is below this line.
z.	position viewport so the current line is in the middle. e.g. Center on this line.
z-	position viewport so the current line is at the bottom. e.g. Show me what is above this line
H	move cursor to top of viewport
M	move cursor to middle of viewport
L	move cursor to bottom of viewport

Jumping the Cursor

Actions that scroll the code viewport by moving the cursor.

Vim Input	Action
^e	scroll one line down
^y	scroll one line up
^d	scroll one half page down
^u	scroll one half page up
^f	scroll one page forward
^b	scroll one page back
^o	move cursor back to previous position.
^i	move cursor forward to the next position.

Cut, Copy, and Paste

Vim uses yank as a naming convention analgous to the copy clipboard command. The delete command is analogous to the cut command as it places the deleted content into a buffer that can be pasted.

Vim Input	Action
yy	Copies the current line and places it into a buffer that can be used with p to paste.
y	Copies characters from the current cursor position.
Y	Copies the entire line at the cursor position.
p	Pastes characters copied from y or d commands at the current cursor position.
P	Pastes characters copied from y or d commands before the current cursor position.
yiw	Copy a word at the cursor position.

Editing Text

Vim Input	Action
r	Replaces the character at the cursor position with the next input character.
S	Clears all text on the current line and enters insert mode.

Deleting Text

Vim Input	Xcode Standard	Action
dP	-	Pressing d begins a delete that matches a selection based on the next position command of P. For example, dw deletes all characters jumping forward to the start of the next word. Usable for most all cursor position commands such as w, e, b, B.
dd	⌘D	Deletes the current line.
dN	-	Deletes N number of lines where N from the cursor position. e.g.: d5 deletes the next 5 lines.
D	–	Deletes characters to the end of the line from the current cursor position.
x	–	Deletes the character at the current cursor position.
X	Backspace	Deletes the previous character from the character position.

Navigating Characters in Line

Vim Input	Action
f{char}	move to next character ahead of cursor in line
F{char}	move previous character behind cursor in line
t{char}	move behind next character ahead of cursor in line
T{char}	move ahead of next character behind cursor in line
;	repeat previous f, t, F or T movement
,	repeat previous f, t, F or T movement, backwards

Selecting Text

Vim Input	Action
vP	Selects text up to the next position, P. e.g. ve selects from the cursor to the end of the word.
V	Selects the current line. Subsequent position commands will extend the selection. Very handy for beginning multi-line selections and edits.

Indentation

NOTE: Xcode will drop the current selection after the action is performed, which makes these commands not as good as a standard Xcode indentation command with ⌘+([ or ]) which retains the selection. Its really only useful for making the indent once, unlike the built-in action which can indent multiple times.

Vim Input	Action
<<	Indent line(s) left
>>	Indent line(s) right

Misc. Handy Actions

Vim Input	Action
~	Changes the case of the character at the cursor position and moves the cursor to the next character.
.	Repeats the previously input VIM command. (Xcode 16+)

Undo and Redo

Vim Input	Xcode Standard	Action
u	⌘z	Undo last action.
Nu	–	Undo last N number of actions. e.g. 3u undo 3 times.
^r	⌘Z	Redo last action

Search

Vim Input	Xcode Standard	Action
/	⌘f	Begin a forward text search.
?	⌘G	Begin a backward text search.
*	-	Find next occurance of the word at the cursor position
n	⌘g	Move to next search result.
N	⌘G	Move to previous search result.

Changing Modes

Vim Input	Action
i	"Insert here". Enter visual mode at the start of the current cursor position.
a	"Append here". Enter visual mode at the end at the current cursor position.
I	"Insert at start". Enter visual mode at the beginning of the line.
A	"Append at end". Enter visual mode at the end of the line.

Registers

Registers act as a space to store text with an identifier that can be recalled later. Think of it as having multiple clipboards with identifiers that you can store and copy text from. You select the text you want, save it to a register, then recall it later to paste in that text. Registers can be named by using characters in the range of a-z, or numbers from 0-9.

For example, I could select a word using ve, copy that to register number 9 with "9y, navigate to a new line, then paste that word with "9p. Once you've used pasted a registers contents, you can keep pressing p repeatedly insert that register.

The power of registers is that these are not replaced by the last item you copied/yanked, like the clipboard would.

Vim Input	Action
"[a-z]y	Creates a named register with character in the range of a-z
"[a-z]p	Puts (pastes) a named register at the cursor position
"[0-9]y	Creates a numbered register in the range of 0-9
"[0-9]p	Puts (pastes) a numbered register at the cursor position

---

Visual Mode Commands

Section

Vim Mode	Action
esc	exit to normal mode
^[	exit to normal mode

VIM Usage in Practice

Below are tips for using and combining the commands in VIM to perform common actions.

Very Basic Usage

Move up and down holding down ^ Control and tapping u and d (Up and Down) to move the cursor in 1/2 viewport increments.

Vertically move to the line to edit using j/k.

Horizontally move to where you want to edit using e/E/w/b/B/h/l.

Start editing text with a/A/i/I.

Exit insert mode with esc and repeat.

Quick Word Navigation

Use ^i or ^o to quickly bounce the cursor to its next and previously recorded positions. Helpful when making an action such as gd to go to a definition, then use ^o to return to where you were before.

Use * to jump from the current cursor word to the next occurence in the file. You can repeat * to keep navigating that word, and after a word is selected with that command, you can then use n or N to find the next or previous occurence of that word.

New Lines

O - add a new line above the cursor and enter insert mode

o - add a new line below the cursor and enter insert mode

Selecting Text

ce - Edit from cursor to end of word and replace

v$ - Select from cursor to end of line

Find & Replace

Basic finding

1. / Start the find, enter the text to find and press Enter
2. n and N to move between the occurences found in the file

Replace

1. vey - Selects a word and yanks (copies) it
2. viwp - Selects a word and puts (pastes) the copied text

Copy/Paste Lines

To copy 2 lines… 2yy - Copies 2 lines

To cut 2 lines 2cc - Cuts two lines

Duplicate line Yp - Copies the current line and puts (pastes) it

From https://developer.apple.com/forums/thread/681968

Motion Commands:

(h, ←), (l, →), (⌫, ⌃h), , (0, ↖), ($, ↘), (g0, g↖), (g$, g↘), ^, g_, g^, F{character}, f{character}, T{character}, t{character}, ;, , (k, ⌃p, ↑), (j, ⌃j, ⌃n, ↓), (gk, g↑), (gj, g↓), _, -, (+, ↩, ⌃m), (gg, ⌃↖), G, ⌃↘, %, (b, ⇧←), (w, ⇧→), (B, ⌃←), (W, ⌃→), ge, e, gE, E, {, }, %, H, M, L, ⇥, ⇧⇤

Scrolling Commands:

^y, ^e, ^u, ^d, (⌃b, ⇧↑, ⇞), (⌃f, ⇧↓, ⇟), z↩, zt, zz, z., z-, zb

Insert and Replace Commands:

a, A, (i, ), I, o, O

Deleting Text Commands:

["x]X, (["x]x, ["x]⌦), ["x]dd, ["x]d{motion}, D, J, gJ, ["x]c{motion}, (["x]cc, ["x]S), ["x]C, ["x]s

Simple Changes Commands:

<<, >>, ~

Copying and Moving Text Commands:

["x]yy, ["x]y{motion}, ["x]Y, ["x]p , ["x]P

Undo and Redo Commands:

(u, ), ⌃r

Visual Commands:

v, V, ^v

Search Commands:

?, /, E, , gE, g, n, N

Visual Mode Commands

Motion Commands:

;, , ⇥, ⇧⇤, (h, ←), (l, →), (⌫, ⌃h), , (0, ↖), ($, ↘), (g0, g↖), (g$, g↘), ^, g_, g^, F{character}, f{character}, t{character}, T{character}, (k, ⌃p, ↑), (j, ⌃j, ⌃n, ↓), (gk, g↑), (gj, g↓), (b, ⇧←), (w, ⇧→), (B, ⌃←), (W, ⌃→), ge, e, gE, E, H, M, L

Text Object Selection Commands:

aw, iw, aW, iW, (a[, a]), (i[, i]), (a(, a), ab), (i(, i), ib), (a<, a>), (i<, i>), (a{, a}, a:) , (i{, i}, i:) , a", i", a', i', a, i

Deleting Text Commands:

(["x]x, ["x]d, ["x]⌦), (["x]c, ["x]s)

Copying and Moving Text Commands:

["x]y, ["x]Y

Visual Commands:

v, V, ^v, o

Search Commands:

n, N, #, , g#, g

Insert Mode Commands

Insert and Replace Commands:

^r{register}

Copy a word
yiw

Hi there,
I noticed a tiny typo in the Find & Replace Section and I'd suggest a fix.

Before:

1. / Start the find, enter the text to fnid and press Enter

After:

1. / Start the find, enter the text to find and press Enter

@nsswifter thanks, fixed!

Hello, is there any way to edit the keymap?

Hi, thanks! BTW...with Xcode 16 there is also the dot command (repeat) available.

Hi, thanks! BTW...with Xcode 16 there is also the dot command (repeat) available.

it sounds great, really help me.

one more...! 😄
registers are available: use "
works quite well with the option of numerical and named registers.

Hi, thanks! BTW...with Xcode 16 there is also the dot command (repeat) available.

Nice! I haven't played around with Xcode 16 yet and I'm glad to hear that the VIM tooling has been getting some improvements. Let me know if you find more!

Xcode 16/beta6+:
You have the opportunity via Help Menu to disable/enable the show of the VIM Editor hints. It's named in Menu: Hide/Show Keyboard Hints (Option+Command+?; might collide with your keybindings but usable via menu command)

Xcode 16.2 also supports gd (go to definition) and ^-o and ^-i to jump back and forth between where you were.
Also I use daw a lot (deletes a word) in combination with de and db

Hey hey guys…
I just saw that a very important command is still missing.

Find the current word:
The asterisk (*) can be used to search for the current word. n/shift-n finds the next/previous occurrence.

Thanks @bvoq and @Bravosierra0, I've updated the gist with those additions!

FYI, the dot operator (.) doesn't repeat the count that you apply for most delete operations. Example:

Code

let x = MyClass()
let y = MyClass()

Executing 2df on line 1 will result in = MyClass(). Executing . on line 2 will result in y = MyClass().

Seems like a bug with Xcode but it's worth noting.