Vim Kōans

These koans have been independently translated into Chinese (archived), thanks to Wanzhang Sheng, and into Spanish (archived), thanks to Daniel Campoverde Carrión.

See also: The Dharma of Vi (archived), Emperor Sh and the Traveller

Master Wq and the Windows developer

Master Wq was addressing some Vim novices. After his lecture on the many virtues of Vim, he asked if there were any questions. A young man raised his hand.

“Master, by what means might one filter for the second column of a plaintext table for all rows that contain the string ‘tcp’?”

Master Wq said nothing, turned to the whiteboard behind him, and wrote:

:%!awk '/tcp/{print $2}'

There was a murmur of approval from the other students.

“But I develop on Windows … ” the student stammered.

Master Wq turned again, erased the command, and wrote:

:v/tcp/d
:v/^\s*\S\+\s\+\(\S\+\).*/d
:%s//\1/

“What! That is far too complex for such a simple task!” cried the student.

Master Wq turned again, erased the command, and wrote:

Microsoft Excel

At once, the student was enlightened.


No ultimate difference

One day a monk visited Master Wq, and inquired, “Master, how will my code be different when I have mastered Vim?”

Master Wq answered, “Before Vim: declare, define, process, print. After Vim: declare, define, process, print.”


Master Wq and the Markdown acolyte

A Markdown acolyte came to Master Wq to demonstrate his Vim plugin.

“See, master,” he said, “I have nearly finished the Vim macros that translate Markdown into HTML. My functions interweave, my parser is a paragon of efficiency, and the results nearly flawless. I daresay I have mastered Vimscript, and my work will validate Vim as a modern editor for the enlightened developer! Have I done rightly?”

Master Wq read the acolyte’s code for several minutes without saying anything. Then he opened a Markdown document, and typed:

:%!markdown

HTML filled the buffer instantly. The acolyte began to cry.


Master Wq and the Unix master

An old Unix master came to Master Wq. “I am troubled, Wq. You teach the way of Vim. vi is holy but Vim is not; its code sprawls, its features crowd memory; its binaries are vast, its behavior inconsistent. This is not the way of Unix. I fear you mislead your students. What can be done?”

Master Wq nodded. “You are right,” he said. “Vim is broken. Let us fix it. Shall we begin?”

The old Unix master agreed, and opened a shell. He typed:

$ vi vim.c

He began to code. Master Wq watched for a while and then asked him, “Which implementation of vi are you using? Nvi? Vim? Elvis?”

“I don’t know,” said the Unix master. “It doesn’t matter.”

Master Wq nodded. The Unix master sat stunned for a moment and closed his document unsaved.


No greatest tool

One night there was a storm, and Master Wq’s house collapsed. The next morning he began to build it again using his old tools. His novice came to help him, and they built for a while and were making good progress. As they worked, the novice began to tell Master Wq of his latest accomplishments.

“Master, I have developed a wonderful Vim script to give all sorts of useful information about a document. It counts the words, the sentences, the paragraphs, and even tells you what kind of document it is using the syntax highlighting rules. I use it in my pipelines all the time. It is a thing of beauty, and I am very proud. Truly, Vim is the greatest tool!”

Master Wq did not reply. Thinking he had unwittingly angered his master, the novice fell silent and continued his work.

The novice finished aligning two beams and had positioned a nail ready for beating into the wood, but found the hammer was out of reach.

“Would you pass me the hammer, master?”

Master Wq handed the novice a saw.

At once, the novice was enlightened.


Master Pope’s dream

Master Pope once dreamt he was an Emacs user. When he awoke, he exclaimed:

“I do not know if I am Tim Pope dreaming I am an Emacs user, or an Emacs user dreaming I am Tim Pope!”


The superior editor

Master Neil and Master Wyatt were famous for their instruction in the ways of Vim, and travelled around the country teaching.

One day a student asked them, “Master Neil speaks calmly and evenly, his accent carefully lilting over his words, as though planned down to the syllable. But Master Wyatt is full of enthusiasm, he starts and stops, his speech is rapid and energetic, and his soul flows into his lectures. Which is the superior way of teaching Vim?”

Masters Neil and Wyatt answered in unison, “Which is the superior editor: vi or ex?”

At once, several students were enlightened.


The slow student’s despair

Master Wq was eating his luncheon when a student burst into his room and knelt at his feet. Tears were in his eyes and he seemed profoundly frustrated. Master Wq put down his bowl and asked, “What upsets you so, young man?”

“Master,” he said. “I give up. I will never attain mastery of Vim! I will never learn the ways of the great patriarchs! I will never attain the brutal simplicity, the divine emptiness of perfectly efficient Vim usage!”

“Why do you say this?”

“I am your worst student, by far. When I am struggling with writing a simple macro, my fellow students are writing recursive macros with ease. When I am trying to remember the regular expression for white space characters, my fellow students are writing cyclomatic complexity tests in Vimscript. I am too slow, and I am ashamed, and I am afraid I have failed.”

Master Wq stood up. “Come with me to the window,” he said.

The student got up and followed Master Wq to the window, and looked across the street to Master Wq’s neighbour’s house. Through the window, the two could see a young man in suit and tie, working on a document.

“What do you see?” asked Master Wq. The student watched for a while.

“That young man is using Microsoft Excel to generate a spreadsheet. He is updating every single cell by hand. He doesn’t even know how to use formulas. He makes capital letters by pressing Caps Lock, and then pressing it again when he is done. He is so slow! I do not understand. How can he be so content?”

“Seeing this young man, how can you not be?” returned Master Wq.

The student was immediately enlightened. His name was Qa, and he later became one of the great masters.


Mastery of Vimscript

A student enquired of Master Wq, “When will I know I have mastered Vimscript?”

Master Wq answered, “When you never use it.”


The Vim poet

A young man begged an audience with Master Wq to read him his latest work, an ode to the glories of Vim. With tearful eyes he read out his heartfelt words, pouring his soul into his veneration for his text editor.

The master sat and listened to the poet for a while. After the tenth verse, he held up his hand. “Please, no more. Your poem is awful.”

The young man was very angry.

“Master Wq, surely you of all people can best appreciate the poem, you who know the great beauty of the editor. How can you be so terse, so dismissive? I even wrote this poem in Vim!”

“You wrote it in Vim,” said the Master. “But your meter is uneven, your rhyming pattern inconsistent, your metaphors mixed. You have written a very bad poem using a very good tool. You are not a poet, and Vim will not make you one; many of my students are not programmers, and Vim will not help them either.”

“Vim is eternally beautiful,” protested the poet. “It is a worthy subject for an ode.”

“Vim is not permanent. nvi is not permanent. vi itself is not permanent, only vi-nature. Emacs has vi-nature, nano has vi-nature, even Notepad has vi-nature. You narrow your sights, you grow attached, and hence you do not grasp the true value of your poem’s subject. You must leave. Come back when you have mastered Emacs.”

The poet left, deeply ashamed. He never returned.


Master Wq’s missing name

Contributed by Rafael Beraldo.

One afternoon, Master Wq was meditating under a pine tree. He contemplated how easily the wind moves through leaves and trunks, both moving them and having its course altered by their presence. A student approached and nervously stood by. Having finally mustered all the courage she could, the student said:

“Master Wq, I am troubled by what I have seen.”

The Master looked at her face, and she continued:

“I have mastered movement, I have understood macros, I am familiar with the source and have not touched vimscript. I have followed your every advice, ruminated on every teaching. Yet, there is something I cannot understand. Nowhere in Vim have I found your name. Never has anybody thanked you in the help pages. How can that be? The greatest of all Vim masters, unknown to all? In a desperate last try, I ran :Wq and the terminal screamed at me:

E492: Not an editor command: Wq.

My heart is drowned in doubt, and I am ashamed to admit that.”

Master Wq looked away. After a few moments, he said:

“You think you have committed a great sin. However, the breeze still follows its path, the leaves make their usual sound and the sky is no greyer.”

As the great master spoke this, with a sharp pebble he wrote in the dirt:

command! Wq wq