Saturday, August 8, 2015

The Magic of Travel

I travelled up north, inside china, last week… I went by D train which is their second-best in class (the G trains are best). I wished there was a G train available but sadly, D’s were all we could get.

It was a three hour journey, each way. On the way up, a cacophony of screaming infants accompanied a solid performance from the man seated beside me as he industriously fingered every last ball of snot from his nose and artistically flicked them asunder.

On the way back, I had a feverish woman beside me for most of the journey which was a blessing for the short game (the long game was a gamble of course, but you take any win you can get). When she got off a couple of men boldly stole the vacant seats until they were kicked out by the righteous ticket owners — two pregnant women each carrying infant boys, each seated atop their mothers' laps to avoid seat costs. Joy. The boy beside me decided that it was Boner Time and that he’d have a fiddle with it, which ultimately led him to the announcement, "Mummy, I’m gonna pee!". It took her considerable effort to convince him not to let loose where he sat. It took even more effort for me to fight the instinct of abandoning my seat for safer (and drier) grounds. To punish me for my obvious disgust, the kid later exploded with a sudden sneeze, streaming thick strands of white snot at me. As I had assumed a defensive posture early in the piece, he merely coated the back of one of my legs. The mother giggled and gallantly withheld the service of her pack of tissues. Class, all the way.

Of course, it’s miserable of me to be whining about my pathetic first world troubles, I know. There are farmers who’d give their left nut to have snot flicked at them as they lounged atop padded seats in air-conditioned comfort listening to the choir of Angels that screaming children are romantically equated to here, I know. I could have been seated beside something a lot more malicious than a mere feverish crone, I know. And the boy could well have let loose with a torrent of pee that would have had me stinking like an abandoned tom-cat throughout my remaining 2 hour subway ride across town after the train trip, I know. So, lord, or fate or the stars or the Spaghetti Monster… thanks for only letting it suck as much as it did. That was awesome. I almost want to do it again. After I forget some more.

Saturday, April 18, 2015

Oral English classes in Chinese Universities

This post is my response to a question from Linked-In:

Many of my colleagues entertain students by showing movies, telling jokes, having fun role-plays, playing games etc. In these activities, should we merely be encouraging students to speak more using a variety of prompts or should we also be teaching grammar?

Note I tried posting this as my response on Linked-In, but ever since a troglodyte group owner banned me from his kingdom several years ago, I seem to have lost all rights to respond to all groups in Linked-In. Meh.

I have taught in Chinese Universities for over five years; English as a Foreign Language (EFL) for more than ten.

I never teach grammar; their Chinese English teachers do that. I do occasionally show examples of broken grammar and ask the students:

  1. Is there a problem?
  2. What/where is it?
  3. Fix it.
I accept any reasonable, grammatically correct fix to the sentence and point out changes in meaning when necessary. I don’t spend long on these moments and I don’t turn them into grammar lectures.

I do teach pronunciation, like linking and elision. I show the rules and we practice with example sentences. I teach the necessary background for this as well (like the syllable rules because linking depends on an understanding of syllable patterns).

I never show movies (unless it’s something like a TED with a definite purpose for watching it). I almost never use role-plays. They can be entertaining, but I see a lot of wasted time and the productions are often superficial. I should probably re-visit this tool to see if I can improve my use of it.

Of course I aim to have fun in class — it relaxes students and lets learning happen. I sometimes (but rarely) play EFL based games. One of my favourites is called "Wow!" where a word is written on the board behind a student standing at the front of the class and the other class members have to describe the word without using it or cognates. They’re not allowed to speak Chinese or use body-language (face/hands) or make sounds (like barking) either. I started playing "Wow!" as described but quickly converted it into a computer based solution so that students could quickly work through as many words as possible within their short time in front of the board. I now call this Marathon Wow!


I had a very inventive group of junior high school students who created their own English-based code for cracking the "Wow!" rules.

This was a decade ago and it was the very first time I tried "Wow!". What an adventure! These cunning kids immediately found ways to shortcut and "win". It was a war of escalation: They used hand gestures, so I introduced the "no hands" rule. They spelt words; a new rule. They mouthed words/spellings; rule. In the end, with their help, I came up with 7 water-tight rules for a happy and harmonious game of "Wow!".

Water-tight, I thought, until I noticed one group was winning so many more points than all of the others. I watched for cheating, assuming they were using gestures or mouthing answers but I couldn’t catch them. Then I realised that the English prompts their team-mates were giving couldn’t possibly cause the student at the board to think of the answer he so deftly produced. The look on my face told them the game was up. They laughed and confessed that they had devised a code for spelling the word by using English words.


So far this semester, I have not shown any movies or played any games. I chose this semester to teach my students about Critical Thinking and Creative Thinking. I have given them a semester-long project called "Think Big!" in which their group (5-7 members) presents a problem that exists in their world and various possible solutions. I have taught techniques like Reverse Brainstorming, PMI, Decision Matrix, Mind Mapping, Presentation Design and the rules of effective dialogue. The groups present their problem & solution and then lead a class-wide discussion based around the topic. They prepare questions to prompt dialogue but are not required to use any/all of them if the topic generates sufficient interest for spontaneous and enthusiastic discussion. I have successfully used this model before (with a different topic) and the students love the format.

To prepare them for this task I slowly (over the course of the first 10 weeks of semester) show them the various thinking, planning and presentation tools they need to produce good work. I show them examples of good work so they know what to aim for. I show them examples of bad thinking/planning/work so they know what to avoid.

I present thinking challenges in every class. Often these come from the students themselves when they talk to me outside of class. Because of this, the problems are often very real for the students so they are more motivated (and able) to ponder them and offer suggestions/solutions.

Another project I run concurrently during the first ten weeks is an opportunity for each student to tell the class something about themselves (this semester the topic is called "Five Minutes of Fame" where the students tell us about a talent, skill or achievement) and then answer questions from classmates. I record each week who presents and who asks questions — that participation constitutes a very large portion of their overall grade (and they are told so at the outset of the semester and reminded regularly throughout). I show a rank-sorted leaderboard before each class as an extra bit of motivation.

As my third and final assessment piece this semester, I am trying something new: I have asked the students to keep a Surprise Journal. They are required to show me their final journal and present to the class one of their surprise moments.

Each journal entry has the format:
  1. What surprised me?
  2. Why was it surprising?
  3. How has this changed me?
I spent the first few weeks inviting students to present surprise entries they had collected so far as a way to model expected behaviour for this assessment piece.

My goal is to get the students to use their English, not bore them with meaningless, isolated, disconnected snippets and exercises. They’ve done that throughout high school. In general, I get good participation and feedback — the students enjoy being given the opportunity to think and contribute their ideas.

Monday, February 23, 2015

Effective Teaching

In The First Days of School — Implementation Guide, Dr Wong posits that three characteristics make for an effective teacher:

  • Positive Expectations

  • Classroom Management

  • Lesson Mastery

Ineffective Teachers

Discussion question #5, Chapter 2, page 8 asks:

Why are all three characteristics of an effective teacher necessary?
Could you imagine a successful teacher only displaying two of the three characteristics?
Why, or why not?

It is easy to imagine teachers that fulfil only two of these three characteristics; none of them effective:

The Substitute

Positive Expectations + Classroom Management

These teachers know how to manage a classroom effectively and use appropriate praise and encouragement to inspire and motivate their students. The problem is, they don’t know their subject matter, or they don’t know how to effectively teach it. It’s great to have such teachers substitute for you in an emergency, but you wouldn’t want them carrying your core.

The Friend

Positive Expectations + Lesson Mastery

With well behaved students, these teachers appear to be effective. They encourage and motivate students with the right amount and type of praise and they really know how to teach their subject so that students are genuinely learning in class. The problem is when they are faced with unruly students. They lack the Classroom Management skills necessary to maintain an orderly room and recover from a chaotic one quickly & effectively. The misconception that they should be their students' friends causes an incorrect power distribution in the student-teacher relationship, rendering it ineffective.

The Moper

Classroom Management + Lesson Mastery

These teachers are capable of running a classroom efficiently and fairly. They know their subject matter and they really know how to teach it. The problem is they have somehow become jaded and as a result they have completely dropped all expectations of their students. They secretly or openly believe that there is no point in trying harder or expecting the students to try harder. They’ve lost faith in the system, their students and themselves.

The Tyrant

Classroom Management + Lesson Mastery

Just like the Miserable Moper, these teachers lack Positive Expectations. But rather than dropping them altogether, they have instead impossibly High Standards. Nothing seems to please these teachers and students rapidly grow weary of reaching for unachievable heights under the demoralising barrage of criticism relentlessly dished out by this mean and unyielding teacher.

The Effective Teacher

Positive Expectations + Classroom Management + Lesson Mastery

Positive Expectations

  • Give the right amount of praise for the right thing at the right time.

    • Carol Dweck says: Don’t praise their intelligence and talent; praise their process: their effort, strategies, focus, perseverance and improvements.

  • Encourage students to reach and extend themselves in a realistic way with clear expectations and constructive feedback.

Classroom Management
When I think of teachers with good Classroom Management skills, I remember them as being fair but firm. They have reasonable rules and are consistent in their application. Dr Wong recommends the use of Procedures to establish and maintain this situation.

Lesson Mastery
Knowing your subject matter is necessary but not sufficient to be an effective teacher. You must also be able to impart your knowledge and skills to your students. There are a vast number of techniques that teachers learn in order to ensure their students learn from their lessons.

The Accelerated Learning Handbook suggests these four components to ensure that learning occurs:


Prepare your students' minds for what they are about to learn and spark within them the desire to learn it.


Present the material in an engaging manner that embraces the learner as an active creator rather than a passive consumer.


Practice the material across many sessions spread out over increasing time gaps. Knowledge and skills are not consumed, they are created through deliberate, conscious, appropriate practice.


One of the single most effective ways to ensure learning is through testing. The mere act of being tested on material causes a greater amount of retention. This applies equally well to summative, formative and informal testing (where the student tests themselves).

Personal Reflection

I have certainly played The Moper and The Friend at various times throughout my career. I have occasionally stumbled on as The Tyrant. There have been rare moments in which I have felt out of my depth on the subject matter — teaching High School maths in Thailand, for instance — where I begrudgingly donned the robes of The Substitute.

Looking back, I have sometimes accidentally pulled off The Effective Teacher. The goal, looking forward, will be to do that deliberately.

Wednesday, January 21, 2015

The Meaning of Life

How would you explain to a six-year old the Meaning of Life?

Holiday Plans

I currently teach freshmen oral English at a university in China. That’s what it says on my contract, but I aim a little higher in my actual classes. In the last week of classes this semester, I wrote on the board the following question:
What are your winter holiday plans?
I gave them a brief moment to read, internalise and start thinking about the answer and then said in alarm, "Oops! I forgot to write the question properly…" as I bounced over to the board and changed it to read:
What are your winter holiday study plans?
Which earned me a classroom-wide groan and screwed-up faces to which I gave my biggest, most oafish grin.

I let the laughter die down and then changed into Serious Mode and said: "I’m not joking."

You’ve Got To Be Joking

Chinese students are forced to study. A lot. In (and before) high school. All in preparation for the university entrance exams. Once you "make it" to university, though, everyone (the kids, the universities, the parents, society) all sit back and relax. Finishing university is a mere formality. All the kids have to do is coast and conform for another four years and they’ll get their little degrees and be out the door, on their way to the Promised Land.

The Promised Land

The Promised Land is the glorious, prosperous future that has been promised to them since early primary school; dangled as a carrot and wielded as a stick. It isn’t until the kids are months into the post graduation job hunt that they finally realise that the Promised Land was all a lie. There is no comfy, well paid job waiting for them. They are not the "talents" their little piece of paper asserts. They have simply moved from one institution to the next. And unlike their utopian entrance to university life where they had for the first time ever a taste of real freedoms, their transition into working life is far more miserable: mean bosses; competitive colleagues; hard work; long hours; little pay; familial pressure to marry and breed…


But as I said, I’m teaching freshmen at the moment so they don’t hear that message yet. I tell them. Some of the Chinese teachers tell them. But they can’t hear it yet. They’re still relaxing furiously; over-enjoying their free life. No surprises then that they should sneer at my question:
What are your winter holiday study plans?
So to break the ice, I calmly walked over to the board and wrote my own study plans for the winter holidays:
  • Continue with my Chinese studies
  • Start learning Japanese Hiragana
  • Learn to use Freeplane
  • Learn about and start playing n-back games
  • Keep working on LearnVim
  • Improve my existing Vim plugins and dev more
(okay, I didn’t really mention the Vim stuff)

In every class, this opened the door for the more lively students to offer some of their own study plans. And in every class, one or more boys brashly declared that Computer Games would be their sole focus all winter long, which would invariably receive knowing laughter from all in the room. These same boys and many beside them spent the whole semester doing exactly that — why should they aim to do anything else now that they have the permission to do so?

The Meaning of Life

Is this a meaningful life?

I opened this post with the question:
How would you explain to a six-year old the Meaning of Life?
I’m not sure how I would have answered until Neil deGrasse Tyson showed us all.

“I’ve been thinking about that!”

The magic word there is thinking. It’s sad not to see that spark of life in the blank eyes of my lost students. And I don’t know how to help them find it again. I hope they do though.

Friday, November 7, 2014

The Vincible Vimmer

I lately saw an abomination
Of hammered keys and fumbled mouse
And angrily I cried "Perdition!
Have you not an ounce of nous?!"

Precision is my vade mecum
And careless edits I abhor.
Expand upon your set of motions
And grope the rodent nevermore.

Inspiration from The Naughty Preposition.

Thursday, August 14, 2014

Learning the Tool of Vim

Barry Arthur, 2014-08-14

Learning to use a tool requires:
  Understanding — What is it? 
                  Why do I need it? 
                  How does it fit in with the rest of my world?;
  Cognition — discovering how it works and remembering so;
  Practice — honing the coordination, grace and speed of movements; and finally,
  Affection — the desire to use it, to use it properly, 
              and to identify with the community using it.


If you already understand Vim, you can skip this section.

Vim is a Text Editor

A text editor is a tool for creating and changing text documents.

Vim has a Rich Set of Text Objects

Think of a Text Object as a unit of text that can be manipulated (changed, deleted, cut, copied, pasted, selected, etc). Simple editors like Notepad and Nano offer at most two Text Objects — individual characters, and visually selected text. Vim introduces objects for words, sentences, paragraphs, quoted strings, parenthetical collections, entire blocks and functions in programming languages, and a lot more. Text Objects allow the user to manipulate logical portions of text at a higher level of abstraction than mere characters or clumsy explicit selections. This freedom lets the Vimmer think and act faster.

Vim is Configurable

Nearly every facet of operation is controlled by one or more configurable options. Two different Vimmers may have their Vims configured so differently as to appear as different editors to newcomers. Initially daunting, this flexibility and control is appreciated by seasoned Vimmers.

Vim is Extensible

Default functionality can be altered and new functionality added. One such extensible aspect of Vim is its set of Text Objects — existing definitions can be altered and new objects created. Another area of extensibility is through the modification or addition of keys and commands.

Vim is Scriptable

More complicated edits can be recorded and played back as needed. These are called macros. I link to three macro articles below.

For even more scripting power, there is Vimscript (aka VimL), Vim’s built-in scripting language which is used by plugin authors to create weird and wonderful addons, and ordinary Vimmers to automate and control facets of Vim.

I look forward to meeting you on the Path to VimL Mastery.

Vim is Modal

The control interface to Vim is, typically, a keyboard. Keyboards are necessarily limited in the number of keys they hold. This limits the number of unique interactions with Vim that can be made by a User.

One way to solve this problem is by "chording" keystrokes, that is by holding multiple keys down at the same time. While Vim uses a small amount of chording, the more dominant model it uses could instead be referred to as "plucking".


One definition of such a key-chord includes the common SHIFT, CTRL, and ALT (META/COMMAND) key combinations used in most Operating Systems / Window Managers, like CTRL-W to close a window, or ALT-F4 to close an application (in Windows). Other definitions exclude such simple instances and instead require multiple non-(SHIFT, CTRL, ALT) keys to form a chord.

Two things to know about chording:
  1. The number of extra interactions it provides is small.
    Chording doesn’t scale very well because the hands can only hold down so many characters at the same time, less even, when limited by reach. It also limits the amount of extra interactions that are possible — chording is unaffected by the order in which the keys are pressed — they all need to be pressed together for the chord to trigger. Chording is therefore the mathematically poorer Combination as compared to the richer Permutation that plucking yields.
  2. It hurts.
    Contorting the hand to simultaneously press multiple keys puts a lot of strain on tendons and ligaments, and I believe, significantly contributes to repetitive strain injury (RSI). Anecdotally, I have heard of far more Emacsians complaining of RSI than I have Vimmers. In fact, it is an often cited reason for an ex-Emacsian switching to Vim. For the Emacsian reading this that can’t bare to lose his beloved Emacs, the Evil mode provides a vimmish interface that might be kinder on your wrists.


Instead of holding down more than one key simultaneously, Vim prefers a model of striking multiple keys sequentially. This is called a key-sequence and resembles plucking strings on a guitar (as opposed to strumming a chord).

Plucking is better because:
  1. The number of extra interactions is vastly greater. (permutation vs combination)
  2. It doesn’t hurt. (as much)

And it’s actually better than that because the sequence of keys that Vim uses for its commands are not random — they are carefully considered so as to form an actual language designed specifically for the efficient editing of text.

The d key for example is a verb for performing a delete operation. But… deleting what? A character? A word? A line? In other editors, different chords are used to express these alternatives, like ctrl-d deletes a word, ctrl-shift-d deletes a line, ctrl-alt-shift-d breaks your wrist, etc.

The d verb is an unfinished command in Vim. It is an operator (verb) pending a motion (an object to operate on). Vim is waiting for me to tell it what to delete. If I type l now, it will delete a letter (a synonym for the x command); if I type w it will delete from the cursor to the end of the word; b will delete back from the cursor to the start of the word; and another d will delete the entire line. This is a common idiom in Vim — doubling the operator (here, dd) will operate on the whole line. So, y is the yank operator (and unsurprisingly, I hope, pressing it DOES NOTHING because Vim is now waiting for you to tell it what to yank), and yy yanks the whole line. “Yank” is Vim’s term for copy (for pasting later).

One particularly nice set of "motions" are the Text Objects. I will show one here just quickly, but you need to read :help text-objects (heck, just grab a cold beer and read all of :help motion.txt — thank me later)

The iw Text Object:

The command diw will delete an entire word, no matter where the cursor is inside the word. This is better than messing around with dw which only deletes from the cursor to the end of the word.

What Does This Have To Do With Vim Being Modal?

Whereas some editor might use ctrl-d to delete a word, Vim uses diw To those unfamiliar with Vim, that might seem like a typo: how can the d i and w keys be used to delete a word?! What if I want to type a "d" or "i" or "w"?! This is where modes come in. In Normal mode, Vim uses diw to delete the word at the cursor. In Insert mode, it inserts (types) these letters instead.

By separating semantically different concepts, Vim is able to re-use keys for different purposes. For example, in Normal and Visual modes, the "%" key jumps the cursor to the bracket matching the one under the cursor; in Command-line mode, it serves as an alias meaning "the whole buffer" when used as a range, or the name of the current buffer when used as an argument to an ex command; and, of course, in Insert mode it merely inserts a "%" character.

Pop Quiz: Been paying attention? Let’s see.

Given the following text, where the cursor is on the "(" :

echo getline(1, '$')

What do you expect the following Normal mode key sequence to do:


Check your answer at the end of the article.

Vim has 12 modes all up (6 basic modes — the other 6 are variations on the basic ones) but the beginner Vimmer only needs to know 4 of them:
  • Normal mode — The editor starts in this mode. Use <Escape> to return to Normal mode from any other mode. This mode is for movements and operations on Text Objects, like changing, deleting, cutting, yanking (copying), pasting, and entering one of the other modes.
  • Visual mode — Used to extend a highlight region over text. Non-movement commands in this mode execute the command on the selected text.
  • Insert mode — Anything typed in this mode is inserted into the buffer.
  • Command-line mode — For running one of three types of commands:
    • Ex commands — :
    • Searches — / and ?
    • Filters — ! (which you won’t need until you advance somewhat)


Learning Vim is learning a skill

Learning a skill is very different to learning knowledge. Skills require that, not just your mind, but also your muscles get involved. We can intellectually know what is required of a task and yet be completely incapable of performing it competently. The gap here is what separates a skill from knowledge: practice. Physical practice. And not just any old practice; it requires Perfect Practice. More on that later.

A good way to learn a new skill:
  1. Normal - Watch an expert do it at normal speed
  2. Slow - Watch an expert do it slowly
  3. With - Do it with an expert, several times, from slow to normal speed
  4. Practice - Practice the new skill several times per day until competent

Use videos if you don’t have access to an expert to watch live. Textual descriptions of steps in tutorials will suffice if no better source is available, but then you lose value by missing the Normal and Slow steps. The value here is in seeing what really is achievable in terms of speed and ease. Seeing a skill being performed properly lowers learning barriers for many who can’t picture themselves being able to do a set of steps explained orally or in written form. Harness the power of Monkey See, Monkey Do.

A digression:
Unfortunately, a lot of video resources for Vim lack in two important ways:
  1. They tend to show too much in one session, confounding higher level concepts with lower level edit sequences.
  2. Some lack OSD overlays showing keystrokes as they’re typed, resulting more in porn than instruction. Watching a Gary Bernhardt session late at night, after the children have gone to bed, is a perfectly acceptable way to unwind after a stressful day.

Racing up the Vim Ramp — topics begging for decent videos:
  • motion.txt — All the builtin motions and text objects (or at least the most useful ones). Seeing them grouped is useful; perhaps the video could similarly group its presentation of these powerful commands.
  • ranges — Something the Vim Ranger can help you with for now.
  • registers
  • Searching & Replacing (Regular Expressions, /, :s///, :g//, :v//) The Walter Alan Zintz (waz) tutorial is this in text form. Other useful tutorials exist.
  • Macros — when to use them, not silly examples where :[range]s/// is preferred. My macro articles are one place to start.
  • Tags — The 80/20 that makes it worth learning.
  • Quickfix — :make & :vimgrep
  • Buffers, Windows and Tabs — Examples of using them wisely. This buffers & args article is a place to begin.

In addition to all of the resources above, I recommend my LearnVim to rapidly acquaint yourself with and acquire the skills of Vim.


One of the pieces of advice given in LearnVim is the use of a Practice File — a place where you can collect newly learned editing motions and commands requiring frequent practice.

Since LearnVim was first written wherein the Practice File advice was espoused, I have since written a tool to replace the manual maintenance of such a Practice File: VimGym.

The purpose of VimGym is to be a place for you to practice the things you need to work on. As and when you discover new commands or motions or ways to do things, create a practice task in VimGym. Gradually, you will build up a set of exercises targeting your weaknesses, helping you where you need it.

But how do I know if I’m practising right?

Excellent question. This is one of the key requirements for Deliberate Practice — the supervision of a coach — the knowledge that you’re investing energy in the right place, working on the right things.

In Vim terms, this means practising motions and commands and ways that are suitable to the task at hand.

Where do I find a coach?
  • Read :help motion.txt
  • Read the set of learning resources I have linked to in this article
  • Look at sane solutions to vim-golf problems
    • A solution is not sane if you don’t understand it.
    • Ask on #vim for explanations if you think it could be sane given clarity.

Fast, Slow, Medium

Once you know what you should be practising, there is the question of how: “How do I get my fingers Bernhardt fast?!”

Steve Yegge proposes the Fast, Slow, Medium approach.

I wonder if Gary used this…?


Being a successful Vimmer requires living the Vim Way. Many initially come to Vim with notions carried over from their prior editor pasts and attempt to change Vim accordingly. Many struggle this way until they give up on Vim, decrying it as worthless or inflexible. Those that eventually give up their struggle against Vim discover the opposite; they discover the power and flexibility and extensibility of a tool that, when used right, has continued to be the best “editor of text” for decades and will probably continue to be so for decades more.

Advice: Stop fighting Vim and start using it the way(s) it was intended. When you’re told on #vim that your approach is anathema to the Vim Way: stop, listen and change your approach. Happiness this way lies.

Good luck, and welcome aboard.

Quiz Answer: The cursor is on the "(" character, and in Normal mode the % key jumps to the matching bracket. The d key is given % as its motion. The result is that the entire bracketed chunk of text [ (1, '$') ] is deleted.

Monday, June 9, 2014

Tag Like a Boss

tagging the way god intended

This short article aims to get you working with Vim tags quickly and effectively, using its built-in support. Your heavy plugins can wait outside.

Before we can jump in and learn the cool commands and power moves, we have to take charge of our environment.

Preparing for a Tagged Lifestyle

You will need:
  • A ctags generated tags file (Exuberant Ctags is the choice for most cases)

    Typically this is as easy as:

    ctags -R

    in the root of your project.
    But if you need anything fancier than that, consult  man ctags  for guidance.
  • A correctly set :help 'tags' option

    The Vim default of ./tags,tags is probably sufficient for most projects but you might want to include library tag files or a project-common tags file.

  • A correctly set :help 'path' option

    My preferred default is:

    set path=.,**

    Which searches the directory of the current file and all directories beneath the current directory. See :help file-searching for more details.

These options can be set in your $MYVIMRC or, better, within filetype specific plugins in ~/.vim/ftplugin/<the-filetype>.vim or ~/.vim/after/ftplugin/<the-filetype>.vim

With the right setup, we can now enjoy a happy tagging lifestyle.

Living with Tag Love

There are many tag commands available in Vim, but I’m going to share with you only a select few — a mere dozen or so. These are the ones I most frequently reach for. You can learn the other tag commands later.

Jump to the keyword under the cursor. Tag jumps are recorded on a :help tag stack.

Jump to older tag in the stack.

Jump to newer tag in the stack. :help :tag

:0ta or :0tn
Jump to previously jumped-to tag. I use this one often after wandering away from the place I tag-jumped into the current file.

:ts /something
Show a list of tags matching the pattern something.

TIP: Use <ctrl-d> to show a list of tag candidates. This works with partial matches too.
Read more with :help c_CTRL-D

Show a list of tags matching the keyword under the cursor.

:tj /something
Show a list of tags matching the pattern something. If there is only one tag in the list, don’t show the list but instead jump directly to it.

g ctrl-]
Show a list of tags matching the keyword under the cursor. If there is only one tag in the list, don’t show the list but instead jump directly to it.

Ordinarily, this just shows all lines in the file matching the keyword under the cursor — a shortcut to :g/<c-r><c-w>

This map (taken from the Vim help) lets you jump to one of the matches:

:map <F4> [I:let nr = input("Which one: ")<Bar>exe "normal " . nr ."[\t"<CR>

  • Use ctrl-c to cancel the choice if you don’t want to jump to any of them.
  • Use `` to jump back to where you were if you accidentally pressed <esc> or <enter> instead.

Courteous Cousins

While not strictly tagging commands, these little gems are semantically related:

gd and gD
Jump to the local or global declaration of the keyword under the cursor, respectively.

Jump to the file under the cursor.

Honourable Mentions

While these are not in my daily tag toolbox, I do call upon them occasionally:
To see my current tag stack.

:ptj /something
To show the tag match in the :help preview-window.

ctrl-w ctrl-i and ctrl-w ctrl-d
To split the window, showing the associated first line or definition, respectively.

Tag! You’re It!

Using tags within Vim will speed up your editing by making it easy for you to jump around your pile of files. While there are heavy plugins that aim to make this prettier, the seasoned vimmer knows that the extra bling doesn’t add any real value to their edits.

Vanilla, when done right, is a classy choice.

Get yourself setup to use tags correctly within your projects and get on living the tag lifestyle!