DEV Community: Igor Irianto

Vim Global Command

Igor Irianto — Sat, 19 Nov 2022 17:44:29 +0000

The global command (:h :global) is used to run Ex-commands on multiple lines.

If you want to delete a line, Vim has the :d (:h :delete) command (or you can press dd).

Wait a second - if I want to run the delete command on multiple lines, can't I just run :%d to delete all the lines in my buffer? Yes, you definitely can.

Where the global command shines, is that it lets you to execute the delete command on all the lines matching the pattern. So if you want to delete all the lines containing "foo", without the global command, you may need to first find the lines with foo (/foo), then delete them (dd or :d). Repeat the process as many times as there are lines containing foo in your buffer. This can get tedious if there are tens, if not hundreds of lines. With the global command, you can run :g/foo/d once and - voila! All foo lines are deleted.

This is the power of the global command. It lets you to apply a command to multiple lines at once. In this post, I will show you how to unlock some of the global command's potentials.

What Commands Can I Run With the Global Command?

When you go to the help section for the global command, :h :global, it says something like:

Execute the Ex command cmd (default ":p") on the lines within [range] where {pattern} matches.

So what are the Ex commands that I can run with the global command?

You can find a list of Vim's ex commands with :h ex-cmd-index (warning: there are hundreds of them). I've been using Vim for years and frankly, I only use very, very few of them. I believe the trick here is to use the few tools that you have well.

For the sake of brevity, based on my personal experience, I found the following 8 commands useful to work with the global commands (if you have a command that you use often and it is not listed here, please let me know!)

Delete
Substitute
Normal
Print
Move
Put
Copy
Sort

CMD: Delete

The delete command deletes line(s). Type :d to delete the current line, :1,5d to delete lines 1-5, :%d to delete the whole buffer, and :+3d to delete the third line below your cursor.

With the global command, you can delete multiple lines.

To delete all lines containing console: :g/console/d.

To delete all lines that do not end with a number 0-9: :g/[^0-9]$/d.

When we run the delete command, Vim stores the deleted text in the numbered register. If you prefer not to modify your register, you can run the blackhole (_) delete command instead: :g/console/d_. It is a little more verbose but it preserves your registers! If you don't use the number register that often, you can just use the regular delete command.

CMD: Substitute

The substitute command (:h :substitute) substitutes a string with a new string. Type :s/foo/bar to sub foo with bar.

To substitute all to_s with to_f on all lines containing puts: :g/puts/s/to_s/to_f.

CMD: Normal

Vim has a :normal command to execute normal mode commands. If you type :normal Ahello, it's similar to pressing A (append text at the end of the line) then typing "hello". Think of it like running a brief normal-mode script.

If you want to insert "//" before all import texts, you can run: :g/import/normal I//. This will effectively comment out all the import commands (even better, if you have a comment plugin and gcc is set to toggle comment, you can also run :g/import/normal gcc).

You can also execute macro (:h macro) using the normal command. Assuming you've recorded a macro in the register a, to execute your macro on all lines containing console: :g/console/normal @a.

CMD: Put

The :put command (:h :put) lets you to put a text from the Vim register.

Recall that registers are what Vim uses to store yanked (copied) or deleted files. For more, check out :h registers.

To put (paste) a text from register a after the lines containing const, run :g/const/pu a.

You also don't have to always paste from the register. You can tell put to output your own text with :g/const/pu ='hello vim'.

CMD: Print

The :print command (:h :print) prints the current line. By itself it is not too useful, but with the global command, you can print all the lines containing the given pattern.

To look at all the Javascript functions in the current buffer, you can print them with: :g/() {/p (assuming you are using the myFunction() { ... } syntax and not the arrow function).

If you want to list all the import your file has, run :g/import/p.

By default, the global command runs the print command if you don't pass it any command after the pattern. So instead of running :g/foo/p, you can just run :g/foo.

One cool trivia, the default global command syntax, :g/re/p (re stands for Regex), spells "grep", the very same grep that lives in the command-line universe. This is not a coincidence, because the g/re/p command originally came from the ed editor (which is probably still in your terminal right now - try it! Just remember, if you need to quit it, type q).

CMD: Move

The :move command (:h :move) moves the current line to the line below the given address. Address is usually the line number. For example, to move the current line to below line 10, you can run :m 10.

With the global command, you can do neat trick like reversing the entire file with :g/^/m 0. Note that ^ is the pattern for the beginning of a line (use it to match all lines, including empty lines)

If you want to gather all your require lines to the top of the file, you can run :g/require/m 0 (keep in mind that their order will be reversed).

CMD: Copy

The copy command (:h :t - not sure why it's the letter t) can copy the current line into the line below the given address (similar to move, except it keeps the original line). To copy the current line to below line 10, run :t 10.

To copy const to the line below them, run :g/const/t . - note that . represents the current line. This effectively duplicates all lines containing const.

Range in The Global Command

There are two range types that you can pass to the global command: address range and the pattern range.

Address Range

The address range has a syntax of: :n,mg/pattern/cmd (n and m are the starting and ending addresses)

To delete the lines containing "puts" between lines 1 and 5, run :1,5g/puts/d (anything outside lines 1-5 aren't affected).

To delete the lines containing "import" between the current line to the end of the file, run :.,$g/import/d.

To delete all lines containing "require" between the 2 lines above and below the current line, run :-2,+2g/require/d.

Pattern Range

Up to now, we have been passing one pattern to the global command: :g/pattern/command.

To pass two patterns, pass it another one: :g/pattern1/,/pattern2/command. When given two patterns, the global command will take effect only between the two pattern matches.

To delete everything between the line containing foo and the line containing bar, including the lines containing foo and bar themselves, run: :g/foo/,/bar/d. Anything outside of the foo-bar sandwich will not be deleted (ie: any line before foo and any line after bar).

The command above deletes all lines sandwiched between foo and bar including the foo and bar lines; if you want to preserve the foo and bar lines, run :g/foo/+1,/bar/-1d. /foo/+1 tells the global command to run the command one line after foo; retrospectively, /bar/-1 executes the command one line before bar.

CMD: Sort

Vim has a :sort command (:h :sort) to sort lines. I find the sort command useful combined with the pattern range of the global command.

If you just run the :sort command, Vim sorts the entire file. Often this is not the effect you want. What usually happens is that there would be times when I need to sort the content inside an array or object/hash/dict (I'll refer this data structure {foo: bar} as object from now on in this article) that goes over a few lines and I'd like to sort them.

To sort only the elements inside each array that spans over several lines, run :g/\[/+1,/\]/-1sort.

arr1 = [
  "i",
  "g",
  "e",
  "c",
  "a",
  "h",
  "b",
  "f",
  "d"
]

arr2 = [
  "b",
  "d",
  "c",
  "a",
  "e"
]

The result:

arr1 = [
  "a",
  "b",
  "c",
  "d"
  "e",
  "f",
  "g",
  "h",
  "i",
]

arr2 = [
  "a",
  "b",
  "c",
  "d",
  "e"
]

The command :g/\[/+1,/\]/-1sort looks intimidating with all these symbols, let's break it down.

When you look at the command :g/\[/+1,/\]/-1sort, it follows the pattern :g/pattern1/,/pattern2/cmd. It starts with the first pattern, followed by the second pattern, followed by a command.

The first pattern is /\[/+1. The pattern is enclosed inside a pair of forward-slashes /. The pattern itself is \[, which is an opening square bracket [. Note that in regex, [ is a special character for character class, so we can't just do /[/. We have to escape it to match a literal [. That's why we have /\[/. +1 matches one line after the square bracket. We don't want to sort that line containing [ itself, but the line after that, that's why we add the +1 modifier.

The second pattern is /\]/-. It is similar to the first pattern. I won't break it down here, but basically it matches one line before the closing square bracket ].

The /\[/+1,/\]/-1 then captures anything one line after [ and one line before ].

Finally, the last part of our command :g/\[/+1,/\]/-1sort is the sort command itself. Any line one line after [ and one line before ] will be sorted. Hey, that was not too bad!

Let's try another one. Can you sort only the keys in the array of objects below? I'll give the solution down below, but spend a few minutes attempting it yourself before scrolling down!

[
  {
    one: 1,
    two: 2,
    three: 3,
    four: 4
  },
  {
    def: 2,
    abc: 1,
    jkl: 4,
    ghi: 3,
  }
]

My command is :g/{/+1,/}/-1 sort. Does yours work?

Result:

[
  {
    four: 4
    one: 1,
    three: 3,
    two: 2,
  },
  {
    abc: 1,
    def: 2,
    ghi: 3,
    jkl: 4,
  }
]

Conclusion

Vim's global command augments Vim's Ex commands so that you can apply them on multiple lines. With this, you only need to run a command once and Vim will do the rest for you. Why run a command multiple times if you can just do it once?

If you want to learn more Vim tips/tricks, follow my Twitter account learnvim!

Learning Vim Regex

Igor Irianto — Sat, 29 Jan 2022 15:47:56 +0000

Learning Vim Regex

Learning regular expressions is like learning latin. It is not pleasant but it is good for your soul. They are incredibly useful but also hard to read. People who master them are hailed as gods. Many desired to learn them but a few actually did.

To a programmer, regex (regular expression) is a tool. It can be learned (and mastered). Learning it is a lifetime investment. Here's why: First, regex is portable. Sure, there are different regex flavors, but the basic principle is the same across all flavors. Regex knowledge in one domain will transfer everywhere. Second, regex is powerful and knowing it can save you a lot of time. Programming is all about creating and updating text. Regex allows you to search and modify texts efficiently. Many powerful programs (like parsers) are built on top of regexes. Third, it is fun (once you get to a certain proficiency).

Regex knowledge boosts your Linux-fu. You'll unlock more powerful commands using programs like sed, awk, grep, find, vim, and more. In this article, we will focus on learning and understanding regexes in Vim.

This article is by no means a complete regex tutorial. In fact, I'll be honest right now, that this article probably contains less than a third of what Vim regex can do. But they are the ones that I find very useful. I call them the good parts.

Many of the regex information you will be learning here is also transferable. Although the syntax may vary slightly in different environments, the principle is the same. If you understand everything in this article, you should be well on your way to use regex in other environments.

Using Regex in Vim

Many of Vim's search features allow you to use regular expressions. Some of them are:

The search commands (/ and ?)
The global and substitute command-line (ex) commands (:g and :s)
The grep commands (:vimgrep and :grep)

There are other places where you can use regex, but based on my experience, these three are the main places I would use regex in.

Finally, this is not a guide about how to use the global command, or grep, or whatever. This is more of a regex guide than a Vim guide. Think of it as a regex guide that uses Vim. It will show you how to use regex in Vim.

I am going to limit the command to only the search command. Almost everything you see here is done using the search command / (I may release more guides in the future with different commands).

To Magic or Not

If you are acquainted with Vim regex, you might be aware of Vim's special "flavor" of Regex. You can read more in :h /magic.

Basically Vim allows you to pass an option where certain characters are treated as literal characters while others as special characters.

In this guide, I won't use any magic option - meaning no \v, \m, \V, or \M (you basically will see a lot of backslashes).

Enough with introductory stuff, let's start!

The Good Parts of Vim Regex

Basic Search `/`

The most basic search that you could do is to search for a literal word. If you want to search for the string donut, run /donut. Vim will look for a literal word donut. It won't match d0nut, Donut, or DONUT (unless you have 'smartsearch' option on, but that's another topic).

In real life, things are not that simple. Maybe you need to look for variations of foo string including food, fool, and foos. Maybe you need to match a phone-number-looking pattern like xxx-xxx-xxxx where x could be any integer. So you want this pattern to match 123-123-1234 and 333-444-5555, but not 1234-123-123.

Practically speaking, we often need to search for a pattern, not a literal word. This is where knowing a little bit of regex goes a long way. In fact, just by knowing a handful of regex concepts in this article, you should be able to handle 99% of your searching needs.

Any Character `.`

The most simple, versatile, and almost universal regex pattern is the dot symbol (.). It matches any single character.

For example, if you need to search for a 3-letter string that starts with an n and ends with a t, and you don't care what goes in the middle, you can use the pattern n.t.

/n.t will match the strings not, nut, net, n0t, and even n t (space between n and t).

You can also use it multiple times, so /n..b matches any 4 character string that starts with n, followed by any character, followed by any character, and ends with b. So it will match noob, n00b, n3wt. It will not match nob or nooob.

The Character Class

The dot syntax is useful, but sometimes you want to classify your search. Recall that /n.t matches any three-lettered word that starts with n, ends with t, and anything goes in the middle. What if we only want alphabetic characters, so it would match not, nut, and net but not n0t, n t, and n?t.

To match only between a set of characters, a character class can help you.

Character Class `[]`

A character class or a collection, is a sequence / set of characters that you can use to match any single character in the collection.

In this case, to match lowercase and uppercase alphabetic characters (a-z and A-Z), we can use /n[a-zA-Z]t. This will match net, nUt, and not.

If you need to match only lowercase alphabets, you can instead use /n[a-z]t. It will now match net, nut, and not, but it won't match nEt, nUt, and nOt.

To match only vowels, use /n[aeiou]t.

To match only numbers, use /n[0-9]t.

To match only numbers 0 to 5, use /n[0-5]t.

To match only uppercase A-F and numbers 0-9, use /n[A-F0-9]t.

You are not limited to alphabets and numbers, if you want it to match either a space, an exclamation mark, and a question mark, you can do something like /n[ !?]t.

Negated Char Class `[^]`

There is a special behavior that you need to know with the character class []. If you put a caret (^) as the first character in it, it will act as a negation character. [^a] means "not a". [^0-9] means any non-number character. [^aeiou] means any non-vowel character.

The command /n[^ue]t means any non-u or non-e character. It will not match nut and net, but it will match any not, nUt, and n0t.

Special Characters

Vim comes with a predefined special character set.

If you want to match a number, instead of using /[0-9], you can also do /\d (digit). If you want to match a non-number, instead of using /[^0-9], you can use /\D.

If you want to match a lowercase alphabet character, instead of using /[a-z], you can use /\l. If you want to match a non-lowercase, alphabet character, instead of /[^a-z], you can use /\L. To match an uppercase, use /\u. For the non-uppercase, use /\U.

If you want to match a hex digit, instead of /[0-9A-Fa-f], you can use /\x. To match a non-hex digit, use /\X. You should see a pattern of using the uppercase letter to indicate the negated version of that special character.

If you want to match a whitespace character (tab and space), use /\s. To match a non-whitespace character, use /\S.

To match a "word" character (lower and uppercase alphabets, numbers, and underscore), use /\w. To match a non-word character, use /\W.

If you know your predefined characters, you can save a few keystrokes (/\d is 3 strokes vs /[0-9] 6 strokes).

Quantifiers

Repeating patterns are common when searching. For example, maybe you need to look for repeating digits in a phone number pattern. Nobody wants to type [0-9][0-9][0-9]-[0-9][0-9][0-9]-[0-9][0-9][0-9][0-9] to match 123-123-1234 and 111-222-3333.Instead typing the characters many times, you can use quantifiers to simplify the search.

Min/Max

The pattern 123-123-1234 consists of a set of 3 consecutive numbers, followed by a dash, then another set of 3 consecutive numbers, followed by another dash, then another set of 4 consecutive numbers.

You can use the {n} (where n is an integer) quantifiers to do the job. The {n} quantifier expects the preceding character to repeat n times. The {} syntax is a special character and needs to be escaped (without the escape, Vim will treat {3} as a literal {3}. The search command /[0-9]\{3}-[0-9]\{3}-[0-9]\{4} will match the phone number pattern. In the case of /[0-9]\{3}, it expects the digit to be repeated 3 times. It will match 123 or 777, but not 12 or 7.

The search command to find the phone number 123-123-1234 looks like: /[0-9]\{3}-[0-9]\{3}-[0-9]\{4}. That's a lot simpler than typing /[0-9][0-9][0-9]-[0-9][0-9][0-9]-[0-9][0-9][0-9][0-9].

There are variations in the min/max quantifier:

{n}
{n,m}
{n,}
{,m}
{}

Exact Match `{n}`

You have already seen the first one, {n}. It means the preceding character is repeated exactly n times.

/a\{5} will match aaaaa. /[a-z]\{3} will match abc and zzz.

Min Max Match `{n,m}`

Let's explore the second one, {n,m}. It expects the preceding character to be repeated a minimum of n times and a max of m times (n and m are integers).

When we search using /[0-9]\{2,4}, it searches for any numbers 0-9 repeated between two and four times. It will match 99, 789, and 1234, but not 9, 78, and 12345 (although it will match the first 4 digits)

The command /fo\{2,5} searches for a string that starts with an f, followed by the letter o repeated 2 to 5 times. It matches foo, foooo, and fooooo, but not fo and foooooo (if will match up to fooooo).

The command /fo\{2,5}d will match food and foooood, but not fooooood. It expects no more than 5 o's between f and d, whereas it finds 6 o's.

Min Match `{n,}`

The next form, {n,}, expects a minimum of n, up to infinity.

The search /fo\{3,} looks for the letter f, followed by 3 or more o. It matches fooo, foooo, and foooooooooooooooooooo. It won't match fo or foo.

The search /[0-9]\{2,} looks for 2 or more digits. It matches 11, 123, 1234567, and 999999999999999999.

Max Match `{,m}`

The next form, {,m}, expects a minimum of zero, up to m occurrence.

The search /fo\{,5} looks for the letter f, followed by no o, up to 5 o's. It matches f, fo, foo, and fooooo. It won't match foooooo (it will only the first 5 o's).

Zero or More Match `{}`

The final variation of the min/max quantifier is {} (or {,}, personally this syntax makes more sense to me). It means zero or more.

/fo\{} expects an f, followed by zero o and up to unlimited o's. It will match f, fo, fooooo, fooooooooooooooo.

Zero or More `*`

The zero or more quantifier matches zero or more of the preceding character and is expressed with an asterisk *. It doesn't need to be escaped.

If you run /fo*, Vim looks for the letter f, followed by zero o, up to infinite o's. It will match f, fo, foo, fooooooooooooooo.

If you think about it, it is similar to /fo\{,}, but instead of typing all those brackets, you just type an asterisk.

One or More `+`

The one or more quantifier matches one or more of the preceding character and is expressed with a plus +. It needs to be escaped, otherwise Vim treats it as a literal plus sign.

If you run /fo\+, Vim looks for the letter f, followed by one or more o's. It will match fo, fooooo, and foooooooooooooo. It won't match an f.

It is also equivalent to /fo\{1,}.

Zero or One `?`

The zero or one quantifier matches either zero or one of the preceding characters. It is expressed with a question mark ?. It needs to be escaped, otherwise it would be treated as a literal ?.

If you run /fo\?, it will match both f and fo, but not foo.

Its min/max equivalent is /fo\{,1}.

Greedy Vs Lazy

There are two different quantifiers: greedy and lazy. By the way, in regex, there's also a third quantifier type, possessive, but I won't cover that here.

Greedy

You actually have seen greedy quantifier in action. * is one example.

Suppose that you have the following sentence:

I say, "I use Vim". You say, "I don't use Vim". Uh-oh.

In this case, when you do /".*" (a string that starts with a double-quote, then zero or more of any character, then a double quote), Vim finds one match: "I use Vim". You say, "I don't use Vim". This is because by using a greedy quantifier, you will get the largest possible value.

But what if you want to match for the smallest pattern? You need to use a lazy quantifier.

Lazy

If you look at lazy quantifiers, they look a lot like the min/max quantifiers, except that they have a -:

{-}
{-n,m}
{-n,}
{-,m}
{-n}

Let's go over the first one. Recall that {} has the same effect as *: zero or more of the preceding character, the largest possible match. {-} is the lazy version of {}. It matches zero or more of the preceding character, the smallest possible match.

Going back to our sentence earlier:

I say, "I use Vim". You say, "I don't use Vim". Uh-oh.

Let's use the lazy search: /".\{-}". You will see two matches: "I use Vim" and "I don't use Vim". Cool!

Let's go over the second variation, {-n,m}. If {n,m} matches at least n and at most m of the preceding character, the largest possible match, then {-n,m} matches at least n and at most m of the preceding character, the smallest possible match.

Suppose that you have the following:

fo
foo
fooooo
foooooooooo

If you do /fo\{-2,5}:

On the first string it will find no match, because it doesn't meet the string requirement of at least two o's.
On the second string, it will match foo, the minimum requirement. - On the third match, instead of matching fooooo, it only matches foo, the least available match (two o's).
On the fourth string, it also only matches foo, the smallest number of possible match.

I will leave the remaining lazy quantifiers, {-n,}, {-,m}, and {-n}, to you. They behave similar to the greedy quantifiers, but instead of finding the largest number of matches, they find the smallest number of matches.

Anchors

Sometimes you need to find a match not based on its content, but based on where it is. To search by location, we use anchors.

Beginning of line `^`

The caret matches the start of the line.

If you have:

donut is life
life is donut
a donut a day

If you do /^donut, it will match "donut is life" because the word donut is at the start of the line. "life is donut" and "a donut a day" do not have a donut at the start of the line, so they won't match.

End of Line `$`

The opposite of the start-of-the-line anchor is the end-of-the-line anchor, $. If you do /donut$, it will match the donut in "life is donut" because the word donut is at the end of the line.

Word Boundaries `< >`

Another useful anchor is the word boundary anchors.

Given the following sentence:

Without further ado, I do like donut very much

If you do (pun not intended :P) /do, Vim will match the do in: ado, do, and donut. What if you only want to match for the do in the word do, not in ado and donut?

Word boundaries can help. The syntax is < >. < means the start of a word and > means the end of a word. You need to escape them, otherwise Vim will match for literal < and >. /\<do\> will match only the standalone do, and not the do in ado and donut.

If you want to match the do in donut and the word do, then you are looking for the start-of-the-word do, so you can use /\<do.

Likewise, to match the do in ado and the word do, it is the same as looking for the end-of-the-word do, hence you can use /do\>.

Or `|`

Sometimes you need to look for either A or B or C. In Vim, you can search for alternatives with the OR (bar) syntax |. You need to escape the bar syntax, otherwise Vim will match a literal bar symbol.

If you need to search for either pancake or waffle (part of a tasty breakfast :D), you can do /pancake\|waffle.

If you need to search for a line that starts with either foo or bar, you can do /^foo\|^bar.

Groups

Earlier you learned about quantifiers. They can help you search for repeating characters. However, more often than not, you need to look for repeated groups, not individual characters. You can do that with capture groups.

Capture Group (Sub-Expression) `( )`

The capture group is represented by a set of parentheses (). In Vim, they need to be escaped  or they will match literal parentheses.

If I need to look for one or more donuts, like donutdonutdonut, I can use /$donut$\+. Recall that way earlier I said that quantifiers like + search for one or more the preceding character. I lied. Technically, it searches for the preceding character or group. In Vim, they are called atoms.

So /fo\+ looks for an f, followed by one or more o's, and matches fo, foo, and fooooo. While /$fo$\+ looks for one or more fo's and will match fo and fofofofo.

Capture groups can be used with quantifiers. /$foo$* looks for zero or more foos, /$foo$\{3,4} looks for 3 or 4 foo's (greedy), /$foo$\{-3} looks for at least 3 foos (lazy).

Let's combine what we've learned together. What kind of string do you think /$super\|duper$\{1,2} yummy$ in my tummy$\? matches? Think about it before you scroll down!

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

Ok, it will match these:

super yummy
superduper yummy
supersuper yummy
dupersuper yummy in my tummy
duper yummy in my tummy

Do you understand why? If you don't, look back at the previous sections and make sure that you understand how they work!

Backreferences `\n`

The capture group sure is very useful. It allows us to construct a pattern group that can be treated as a unit. It works great with quantifiers. But that's not all! Capture groups also work with backreferences.

Back...what?

A backreference lets you match the same text previously matched by a capturing group. You can spot a backreference when you see a backslash followed by a number: \1, \2, \3, ... \9.

For example, when you use /$foo$.*\1 against:

foobarfoo
foo bar foo

They would match the entire string. How?

The first capture group $foo$ captures the string foo.
Then we have zero or more of any character, .*. This matches any string between the first foo and the last foo.
Finally, \1 is a backreference to the first capture group $foo$.

/$foo$.*\1 is effectively the same as doing /foo.*foo, but using \1 gives you far more flexibility as you'll see in a little bit.

You can use multiple backreferences, like /$foo$$bar$.*\2\1\1. Here, the first capture group is foo and is referenced with \1. The second capture group is bar and is referenced with \2. The search above is effectively similar to /foobar.*barfoofoo.

Suppose that you want to match an opening and closing of an XML tag:

<foo>Hello</foo>
<bar>Greetings</bar>
<baz>Hello and greetings</baz>

Since XML opening tags need to match closing tags, we do not want it to match mismatched tags like:

<foo>Nope</bar>

You can use: /<$[^>]*$>.*<\/\1>.

Whoa, that got messy and hard-to-read quickly. Let's break it down!

Without escape characters, we actually have <([^>]*)>.*</\1>. A little simpler, but still a lot of symbols. Let's further break it apart into smaller sub-components.

The pattern above is composed of three components: <([^>]*)>, .*, and </\1>. Let's investigate each starting from the first one.

In <([^>]*)>, the outermost < and > are literal angle brackets to match < and > in <foo> and <bar>. The pair of parentheses are the first capture group. So what's that weird [^>]* syntax inside? Recall that [] is a character class and when you have a caret as the first character inside a [], it means negation. So [^>] means a non-> character. Finally you are looking for zero or more of this non-> character. [^>]* will match foo, bar, and baz. Overall, this pattern effectively matches <foo>, <bar>, <baz>, etc. The capture group captures the contents inside the < >. It captures and temporarily stores the texts foo, bar, and baz.

The second pattern, .*, is a familiar one: zero or more of any character. This matches any text between the HTML tags.

The third pattern is </\1>. The opening and closing angle brackets < and > match literal opening and closing HTML tags. / matches a literal forward slash. Finally, \1 is a backreference to the first capture group, which as you recall was the content of the HTML tags: foo, bar, and baz. Putting the capture group and backreference together, this means that your opening XML tag needs to match the closing XML tag. If the starting XML tag was <foo>, then the closing HTML tag needs to be </foo>.

Whole Match `\0`

There is one more special backreference in Vim: \0. It represents the whole regex match. So if your search pattern is /foo, then \0 is foo. If your search pattern is /foo[0-9] and the string is foo9, then \0 is foo9.

This can come in handy in substitution.

Suppose that you have:

const one = 1;
const two = 2;
const ten = 10;

If you want to enclose the numbers 1, 2, and 10 in double quotes, the fastest way to do it using the substitute command is :%s/[0-9]\+/"\0"

I won't go over how the substitute command works because it is not the scope of this article, but I want to highlight the patterns:

[0-9]\+, matches one or more digits (therefore it matches 1, 2, and 10).
The new substitute pattern, "\0" efficiently encloses all the matches with double-quotes. In the first line, \0 is 1. "\0" is the same as "1". In the third line, \0 is 10. "\0" then is the same as "10".

By the way, \0 can also be aliased with &. :s/\d/"\0"/g is the same as :s/\d/"&"/g. It is one less character to type, if you prefer & over \0.

Non-Capture Group `%( )`

All capture groups come with the backreference feature. If you don't want the backreference capability, use %() pattern to use a non-capture group instead of the regular capture group (). So /\%(foo\)\+ still looks for one or more foo, but you won't be able to backreference it with \1.

So why would anyone want to not backreference it?

Performance. Backreferencing comes at performance cost. If you don't store backreference, you get some performance boosts. However, in my experience, I never really noticed any difference. But it wouldn't hurt to know about it.

Atoms

Earlier I mentioned about atoms. What on earth are atoms?

In Vim regex, an atom is a unit match. Technically almost everything in this article can be considered as atoms. The a in /a is an atom. The ^ in /^hello is an atom. The [0-9] in /[0-9] (any single-digit integer) is an atom. The what in /$what$\+ (group match) is an atom. An atom can be an individual character match, an anchor, or a group match.

Zero-Width

"Zero-width" is a regex term. It is also mentioned in Vim help a few times and earned its place as an entry (:h /zero-width).

So what is zero width? A zero-width pattern is a pattern that doesn't actually match any character. If I search for the letter a (/a), it has a width of one. If I search for the letter a followed by any number (/a[0-9]), it has a width of two. The regex engine looks for a literal letter a. Anchors are good examples of zero-width patterns. If I search for the letter a at the start of the line (/^a), although the pattern a looks for a literal match of the letter a, the caret ^ does not match any character. This makes the caret anchor a zero-width pattern. It is there to specify location, not to match a character.

^, $, \< and \> are examples of zero-width patterns. There are other zero-width patterns that I haven't mentioned yet: look-arounds.

Look-Arounds

So what are look-arounds and why do we need them?

Look-arounds are useful when you have to search for a pattern relative to another pattern. If you need to search for foo only when it is before bar, a look-around can help you.

There are two types of look-arounds: look-aheads and look-behinds.

Look-Aheads

Vim's lookahead syntax is \ze. Think of the e as "ending".

To match a foo that is followed by a bar (foobar), you can search /foo\zebar. The way I think about it is, /foo searches and matches for foo. Then you tell Vim to end the match with \ze. But the pattern doesn't stop there. The search continues. There's a bar after that. But you don't want bar to be part of the match. You're really searching for foobar (/foobar). So up to \ze, it will be searched and matched. After \ze, it will still be searched, but won't be matched. Note that in this section, I am making a subtle distinction between a "match" and a "search". A search is a pattern that the regex engine looks out for. A match is what is being selected / highlighted. All searches are matches but not all matches are searches.

/foo\zebar matches foobar, but not foobaz or foo.

The look-ahead pattern has another form: \@=. If you are familiar with the Perl regex, this is similar to the (?=pattern).

When used in Vim, it matches the preceding atom. The syntax works differently from \ze, but the idea is the same.

To search for foo in foobar (but not in foobaz or foo), run /foo$bar$\@=. Note that you are using a capture group on bar, $bar$.

If the syntax is confusing, don't worry, you're not alone. It took me a while to grasp it when I started to learn about it.

The best way to understand it is, whatever character or capture group that precedes \@= won't be matched or highlighted, but it will still be used as a part of the search pattern. Think of it as a veil that covers it. $bar$\@=. It takes a stretch of imagination, but I see \@= as a magician, @= is the head (looks like a duck magician) and \ is his left hand. $bar$ is a veil containing the word "bar". He is covering it so it won't be highlighted. So /foo$bar$\@= to me is like a giant text that spells "foobar", whereas a duck-magician person comes and covers up the "bar" part so it won't be visible to the audience... sort-of kind-of... Well, anyway, let's go to the next look-around, look-behinds!

Look-Behinds

Look-behinds are principally similar to look-aheads, except they work backwards.

In Vim, you can use \zs. Think of the s as "start". If you want to match bar but only if it is followed by foo (foobar), do /foo\zsbar. Again, the search pattern is technically /foobar. However, the matching only start after \zs, hence only bar is highlighted while foo is not.

Both \ze and \zs are Vim inventions. But they both have regex look-ahead and look-behind syntax counterparts. Just like \ze has a \@= regex counterpart, \zs also has a regex counterpart and it is \@<= (it's like \@=, except now it also has an arrow pointing back). The way it works, is that the atom that precedes it won't be matched (highlighted), although it will still be used as a part of the search pattern.

To search for bar in foobar, use /$foo$\@<=bar. To search for baz in foobaz, use /$foo$\@<=baz.

If the whole look-behind syntax pattern is confusing, I find the duck-magician imagery helps. $foo$\@<= is our pattern. @<= looks like a duck magician that shoots a beam. \ is his left hand. $foo$ is the veil that covers up the word foo. Again, whatever word/pattern that the magician veils will be hidden (not highlighted). So I imagine $foo$\@<=bar like a giant "foobar" text and this duck-magician guy veils up the word foo so it won't be visible to the audience.

Look-Ahead and Look-Behind

You can definitely use both look-aheads and look-behinds in a pattern.

If you need to match and highlight the bar only if it comes after foo and before baz (foobarbaz), not in bazbarfoo, foobar, or barbaz, use /foo\zsbar\zebaz. Alternatively, you can also use /$foo$\@<=bar$baz$\@=.

Negative Look-Aheads

Negative look-aheads are the negative version of the look-aheads. The syntax is \@! (as opposed to \@=).

Negative look-aheads search for a match NOT followed by the given pattern. To match foo not followed by baz, run /foo$baz$\@!. This will match foo and foobar, not foobaz.

Negative Look-Behinds

There are also negative look-behinds. The syntax is \@<! (as opposed to \@<=). It finds a match NOT preceded by the pattern.

To match bar not preceded by foo, run /$foo$\@<!bar. This will match bazbar and bar, not foobar.

More Vim regex

The following are patterns exclusive in Vim. They are not available in most regex engines outside of Vim.

Optional Match `\%[ ]`

You can search for optional, sequential matches with the \%[] pattern. It will match if the string contains, sequentially, any of the characters inside the square brackets.

/do%[nut] will match either do, don, donu, and donut.

Multiple Lines `\_x`

Sometimes you need to search for patterns that may or may not be separated by newlines and/or whitespaces.

If you need to match the chocolate donut string, one separated by a whitespace and another separated by a newline:

chocolate donut

chocolate
donut

You can search with /chocolate\_sdonut.

Recall that \s is a special character for a whitespace character. By adding an underscore, \_s now also includes a newline.

So if you want to match:

chocolate donut

chocolatedonut

chocolate
donut

chocolate



donut

You can use zero-or-more quantifier (*), /chocolate\_s*donut.

Start and End of File `\%^ \%$`

Sometimes you need to search for a pattern at the start of the file. You can use the \%^ pattern. If you need to search for foo that is at the start of the file, use /\%^foo.

To search for a pattern at the end of the file, use \%$. If you need to search for foo at the end of the file, use /foo\%$.

Start Within Visual Area `\%V`

Vim has a Visual mode (v, V, or Ctrl-V) that allows you to highlight a certain area of text. I assume that you know what the visual mode is, if not, check out :h visual-mode.

When you are currently highlighting a visual area, you can search for a pattern within that visual area with \%V.

If you have the text:

barfoobazfoobarfoobazfoobarfoobazfoo

foobarfoobazfoobarfoobazfoobarfoobaz

While you are currently Visually highlighting the first line, you can search for foo within the visual highlight if you do /\%Vfoo.

Magic and Very Magic `\v \m`

Earlier I mentioned about \v, \V, \m, and \M. Some regex syntaxes require them to be escaped for them to be treated as special characters.

For example, to match one or more foo, normally you would do /$foo$\+. Note that the group match () and the one-or-more quantifier + are escaped.

If you don't want to escape them, you can use \v. The v stands for "very magic". Your search would look like this: /\v(foo)+. Vim treats () and + as a special character instead of treating them as literal parentheses and plus signs.

So how do you know which characters no longer need to be escaped and which characters still need to be escaped? The rule of thumb is, all characters except for word characters (digits 0-9, lowercase alphabets a-z, uppercase alphabets A-Z, and underscore _) are treated as special characters. As you've seen earlier, () and + are not word characters, so under very magic, they are treated as special characters. Also, special characters like \d (digits) and \l (lowercase alphabets) still need to be escaped.

Likewise, in very magic mode, since it automatically treats non-word characters as special characters, previously literal characters would need to be escaped if you want to match them literally. So if you need to match a literal parentheses while under very magic mode, like (foo), then you'd have to escape it: /\v$foo$.

"Very magic" has a sibling, "magic". You actually have been acquainted with this magic mode. How so? Because Vim by default uses magic mode! If you run :set magic?, it will return magic. Everything that you've used so far is done under magic mode.

Vim also has two more modes: "no magic" (\M) and "no very magic" (\V). I won't cover them here because I personally think their usage is limited in everyday editing (I could be mistaken). But if you're curious, check out :h /\V and :h /\M.

Conclusion

I think this is a good place to stop.

I hope that you gained valuable insight from this guide. Regex is a lot of fun once you know how to use it. It is an invaluable skill for any programmer. You don't need to master it, you just need to be good enough. Most popular programming languages employ regex to a certain extent. By learning regex in the Vim domain, you will inevitably know how to use it anywhere else. You will also be able to find and edit things much faster. Finally, it simply looks so darn cool.

Take the time reading this. No rush. Make it into your muscle memory. Understanding beats superficial knowledge. Test your knowledge. Have fun with it!

Happy coding!

I am already planning to write more about regex in the future, so stay tuned!

Vimgrep Tips and Tricks

Igor Irianto — Tue, 04 Jan 2022 16:16:12 +0000

When I started using Vim, I wished that Vim had a powerful in-file search feature that other popular IDEs / editors have. How could I search for the files that contain the string "echo"? How could I search for only the .js files containing the string "const"?

It turns out that Vim does come with a powerful in-file search right out of the box.

There are two main in-file searches in Vim: :grep and :vimgrep. The former uses an external grep command and the latter is built into Vim. This article will cover how to use the :vimgrep command. Maybe in the future I will write about :grep.

Why Learn Vimgrep

The ability to perform complex searches quickly can boost your productivity.

It is true that the Vim ecosystem today contains many useful plugins, some of them are search-related plugins like ctrlp, denite, and fzf.vim. These plugins are convenient and powerful, so why bother learning vimgrep?

Just because it is old doesn't mean it is no good. There are a few advantages of learning vimgrep.

First, the :vimgrep command is built into Vim, so you don't have to worry about installing dependencies (and all the issues that might come with it). If you ever had to use vanilla Vim (ex: when you're in an SSH, or using someone else's computer, or in your mobile phone, etc), you can be sure that :vimgrep will always be there.

Second, vimgrep uses Vim's built-in regex engine (remember 'verymagic'? :D). This may sound like a con to some people, but to me, this is a huge pro. Using the same, consistent regex engine as Vim itself means there is zero friction between performing a Vim search (/) and using :vimgrep. Your brain won't have to switch to a different mode. The less you have to use your brain for editing, the more you can use it for the more fun stuff!

Vimgrep has some downsides. The biggest one is that because it loads all the search results into memory, if you have a large search result, it can slow down Vim. However, if you're working on a small / medium project, it is fast enough.

Basic Usage

Did you know that :vimgrep shorthand is :vim? That's right! A :vim command inside Vim? How meta!

Anyway, from now on, I'll refer to it as :vim in the remainder of this article.

The :vim command follows the following syntax:

:vim /pattern/flag path

pattern is your search pattern.
flag is a flag that you can pass to the search pattern.
path is the file argument. You can pass multiple arguments.

Ok, enough theory. You're here to learn some vimgrep, aren't you? Let's go!

Searching for a String Inside a Particular File

If you need to find the string "hello" inside all ruby files (.rb) inside app/controllers/ directory, run the following command:

:vim /hello/ app/controllers/**/*.rb

I use the wildcards * and double wildcards (globstar) ** a lot. The globstar, **, searches recursively (it will match things like app/controllers/dir/, app/controllers/some/dir/, app/controllers/file). The wildcard, *, matches any string of any length. In this case, *.rb matches any string that ends with .rb (like hello_controller.rb, whatever.rb).

Btw, do not confuse the wildcards with the asterisk in regex. These two are different things. Regex asterisk pattern means zero or more of subsequent pattern (ex: a* means zero or more "a"), while the wildcard does not require a subsequent pattern (* means any string of any length).

If you want to learn about globs, check out https://mywiki.wooledge.org/glob.

The :vim search displays the results in quickfix. If you aren't familiar with it, think of it as a set of items. In this case, it is a set of search results.

After running the search command, run :copen to open the quickfix window.

If you're brand new to quickfix and aren't sure how to interact with it, here are some useful quickfix commands to get you started immediately:

:copen        Open the quickfix window
:cclose       Close the quickfix window
:cnext        Go to the next location
:cprevious    Go to the previous location

The above list is by no means comprehensive. I suggest you learn about quickfix if you have time. It shouldn't take long. It's a useful skill to have in your Vim toolbelt. To learn more about quickfix, check out :h quickfix.

Searching for a String Inside a Particular File Extension

If you need to look for the string "echo" but only inside a .sh file:

:vim /echo/ **sh

The globstar is very useful if you have a nested directory structure. Here, it will match both ./some_file.sh and ./some/really/long/dir/then/file.sh.

If you only want to search in adjacent files (like ./hey.sh and ./some_file.sh, not ./some_dir/then/file.sh), instead of using the globstar, use a single wildcard: *sh.

Searching for a String Inside Files Ending With Particular Extensions

If you need to look for the string "echo" but only inside either a .sh or a .rb file:

:vim /echo/ **{sh,rb}

Passing Multiple Files to Search Inside of

Note that earlier I said that vimgrep accepts multiple file arguments. We have been passing it only one argument so far. However, we can totally pass it with more than one argument!

If you need to look for the string "echo" inside either .sh or .rb:

:vim /echo/ **sh **rb

If you need to look for the string "echo" inside of either app/controllers/ or Rakefile:

:vim /echo/ app/controllers/** Rakefile

You are not limited to only two file arguments, you can pass it as many arguments as you want. If you need to look for "echo" inside of either app/controllers/ directory, Rakefile in the current directory, a .json in the current directory, and a sh file somewhere inside the bin/ directory:

:vim /echo/ app/controllers/** Rakefile *.json bin/**/*sh

Finding Multiple Matches in the Same Line

When we did :vim /echo/ app/controllers/**, Vim returns the first match on each line.

That means if we have a line that contains multiple keywords, like echo "I like to echo echo echo", the search result only displays one result instead of four. Using the pattern /echo/ only matches the first "echo" of that line.

What if we want our search result to display all four of them?

To catch all of the "echo" strings whenever it occurs multiple times in a line, we need to use the global flag (g).

:vim /echo/g app/controllers/**

Now it will match all 4 "echo" occurrences in that line.

I like the global flag and I use it in over 80% of my vimgrep searches.

Fuzzy Search a String Inside a Particular File

Vimgrep is also capable of running a fuzzy search. We need to pass it a f flag. To fuzzy search the string "echo" inside a .sh file:

:vim /echo/fg  **sh

This will fuzzy search all lines inside **sh pattern for strings that resemble "echo".

So how does a vimgrep fuzzy search differ from a regular search? In addition to matching a literal "echo" string, it would also match something like: puts "Checking Homebrew..." because the "ec" in "Checking" and "Ho" in "Homebrew" constructs an "echo".

Search a Regular Expression Pattern in a Particular File

Vimgrep accepts regular expression in your keyword search pattern. If want to search for either "echo" or "ecko" inside a .sh file:

:vim /ec[hk]o/g **sh

The [] in [hk] is a character set syntax. In this case, it will match either "h" or "k" letters.

If you need to search for a text surrounded by a single quote (like 'hello', or 'foo', or '1234') inside a .sh file:

:vim /'[^']*'/g **sh

There is so much more you can do with regex. I won't cover how to use regex here - but I want to show you that vimgrep works great with regex. If you want to learn more regex, I like to go to https://www.regular-expressions.info/tutorial.html.

Search for a String Inside a Particular Directory

The double star (globstar) ** and the wildcard can be used at the start, in the middle, or at the end. It can also be used multiple times in a file pattern.

If you want to search for "echo" inside the /controllers/ directory:

:vim /echo/g **/controllers/**

If you want to search for "echo" inside the /controllers/ directory and inside a file that begins with "shipment" and end with "rb" (ex: shipment_domestic.rb, shipment_incoming.rb):

:vim /echo/g **/controllers/**/shipment*rb

Search for a String Inside a Different Directory Than Your Current Working Directory

Vimgrep searches in your working directory. But what if you need to search for the string "echo" inside a different directory? Easy. Just go to that other directory, then do the search!

Vim has a :cd command that changes the directory you are currently in.

:cd somewhere/else
:vim /echo/g **js

When you're done, just :cd back to your previous directory.

Search in the Current File

You can use Vim's filename expansion to shortcut your file pattern search. % in Vim represents the current active buffer (the file you're currently on).

If you need to search for "echo" the current file:

:vim /echo/g %

For more: :help :_%

Using Other Search Commands

There are times when we need to perform a more advanced search. We may need to use other commands, like find. No problem. To search for "echo" inside all files whose names start with "docker" using the find command:

:vim /echo/g `find . -type f -name 'docker*'

For more on how find works, check out man find.

The git ls-files is another useful shell command for git-related searches. Assuming that you are inside a git repository, to search for "echo" inside of all modified files only:

:vim /echo/g `git ls-files --modified`

For more on how git ls-files works, check out man git-ls-files.

Searching in-Files Within Arglist

The argument list (arglist) is a Vim feature wherein Vim stores a list of files.

The gist of arglist is, if you open Vim with multiple files (ex: vim file1.js file2.rb file3.py), Vim collects these files inside the arglist. To see them, run :args.

Arglist does not necessarily have to be populated on start too. You can create your own arglist while in Vim by running :args file1.js file2.rb file3.py. To see them, run :args.

Once you have a list of files, you can quickly go to the next or previous arglist files with :next or :prev.

Ok, so arglist is a collection of files. So how does arglist relate to vimgrep?

Usually when performing a task, you would gather all the relevant files first. Once you have all your relevant files in a collection, you can very quickly navigate between them. Arglist is a very useful feature for that.

Vim has a number of file expansion shortcuts. Just like how % represents the current buffer, Vim has one for arglist too! ## represents the current arglist.

So if we want to search within our arglist files for the string "echo":

:vim /echo/g ##

Why is this useful? I mean, it looks like I'm adding an extra step to the search process: first, I need to gather the files to an arglist and second, I run the vimgrep command. That's two steps altogether. Why can't I just run :vim /echo/g file1.js file2.rb file3.py and be done with only one step?

Speaking from experience, often I find myself needing to perform multiple keyword searches within the same set of files, like:

:vim /echo1/g file1.js file2.rb file3.py
:vim /foo2/g file1.js file2.rb file3.py
:vim /bar3/g file1.js file2.rb file3.py

I find it painful each time I have to re-type the same set of files. This is where arglist can save time!

Why not collect an arglist first:

:arglist file1.js file2.rb file3.py

Then reuse it in subsequent vimgrep searches?

Now I can just run:

:vim /echo1/g ##
:vim /foo2/g ##
:vim /bar3/g ##

If you need to perform different keyword searches against the same set of files, arglist can save you time.

If you're curious about how ## works, check out :h :_##. If you want to learn more arglist, check out :h :arglist.

Quickly Get the Last Search Pattern

Sometimes I need to search for a complicated pattern. Before I enter that in the :vim command, I like to test it with search (/) first.

For example, if you want to search for a string surrounded by a single quote, while excluding the single quotes, you could do '\zs[^']*\ze'. But this pattern may not be intuitive at first. When using a semi-complicated pattern, I like to test if it does what I think it does, so before I run :vim /'\zs[^']*\ze'/g **sh, I would usually do a quick search command /'\zs[^']*\ze' to test if it works.

Once I confirm that the pattern meets my expectations, I would then enter it to the :vim command. But do I really want to re-type '\zs[^']*\ze' all over again? I mean, look at those brackets and single quotes and backslashes... I could easily mistype them when I am typing them on the :vim command.

Moreover, what if my pattern is a lot longer, like $["']$$\%(\1\@!.$*\)\1? Oh boy, look at those backslashes, parentheses, and brackets... what are the chances of me retyping that correctly in the first try?

Luckily, there is a trick that allows you to "paste" your most recently used search command. After typing :vim /, type Ctrl-r then /. The secret is that Ctrl-r when used in insert mode (or in this case, command-line mode) invokes the Vim registers. Here we ask Vim for the value from the search register (/).

This is where the :vim command has an advantage over the regular :grep command. The search command (/) uses Vim regex flavor, which :vim also uses. But the :grep command doesn't use Vim regex flavor (it uses whatever grep external command you set up; for more, check out :h 'grepprg'). Using the same regex flavor for / then :vim command means zero friction and a buttery-smooth search experience!

Albeit, performance-wise, :grep is faster, but if speed is not a big issue (it isn't really noticeable in most cases), :vim offers a better user experience.

Conclusion

This is a good place to stop. You've learned a number of cool tricks for the :vim program. I wish I knew half of these tricks when I started Vim. Don't just speed read this and leave. Take your time going through each command. Go through each one of them - tweak it, break it, and understand it. Make it your goal to be able to perform them without much mental effort. This is by no means a comprehensive list of :vimgrep tips and tricks. There are so many other combinations that you can do with vimgrep. Don't stop learning!

Vim is a great editor even without plugins. Vim is a universal program that can be found/installed in practically any machine. There may be times when you can't use search plugins. This will be the time where your vanilla Vim knowledge will shine. Don't let the lack of plugins cripple your Vim productivity. Learn to use Vim with and without plugins. Learn :vimgrep and also learn :grep.

Happy Vimming!

The Easy Way to Copy Text in Tmux

Igor Irianto — Mon, 22 Nov 2021 15:34:08 +0000

How to Easily Copy Texts in Tmux

If you've used tmux for a while, you will realize that highlighting a text with a mouse in tmux to copy them is a painful experience. That's because it's now how tmux is designed. Having used text editing softwares like Microsoft Word / Google Docs and to some extent, Atom / VSCode / IntelliJ, it may feel natural to grab your mouse, highlight the body of texts, and press Ctrl + C.

Not so with tmux. Copying with tmux is more like copying in Vim, where it's best done with a keyboard rather than a mouse. This is done in tmux copy mode. In this article, I will show you how to utilize tmux copy mode to easily copy text.

Vi Copy Mode

Tmux is similar to vim in many ways. One of them is that they are modal programs. What that means is that to accomplish a specific task, you need to switch to a mode that's optimized for that task. In Vim, we have a normal mode where you can move around with your keyboard. Vim's normal mode is designed for moving (and to a certain extent, modifying) within your file. If you need to insert texts, you need to switch to vim insert mode.

To navigate your terminal history and to copy text, you need to switch to tmux copy mode (technically it is vi-copy-mode, but to keep it simple, let's call it copy mode).

So what exactly is a copy mode?

If you try to copy a text from a tmux window with your mouse, you may have seen a warning saying that you can't simply copy the text. The correct way to copy a text from tmux is to first switch to copy mode, then copy it, then paste it.

To enable this copy mode, in you tmux config file, add:

setw -g mode-keys vi

Then save and source the tmux config. This will enable vi mode-keys. If you are unsure about tmux config, check out my previous article on tmux config.

To enter the copy mode, use Ctrl + [. You should be able to see a yellow visual indicator on the top right of your tmux window. With this, you can now move around using vim navigation keys.

Although tmux copy mode doesn't translate to 100% vim navigation keys - overall they are good enough to feel natural. Some navigation keys that you can use:

h / j / k / l to move left/down/up/right
w / W / e / E / b / B to move forward to the start / to the end / backward a word or WORD
{ / } to move backward / forward a paragraph
Ctrl + e / d / f to scroll down a line / half screen / whole screen
Ctrl + y / u / b to scroll up a line / half screen / whole screen
/ / ? to search forward / backward
n / N to repeat the previous search forward / backward
etc

There are a lot more navigation keys. Check out inside man tmux and search for the mode-keys keyword.

In this mode, you can move around the terminal like you move around vim. To exit this mode, press q or Enter.

To begin highlighting, press Space. Note that your cursor will highlight the letter under it. It will expand the highlight as you move around your cursor.

Once you highlight all the text you want to copy, press Enter. You should automatically exit the copy mode. The text that you copied are stored inside a tmux buffer. It is an allocated space in the memory where tmux temporarily stores data.

To paste from the tmux buffer, press Ctrl + ]. Woot! Congratulations, you've copied a text with tmux - stress-free!

To recap:

Add setw -g mode-keys vi in your tmux config
Ctrl + [ to enter tmux vi copy mode
Move around with vim navigation keys
Begin highlight with Space
Copy with Enter
Paste with Ctrl + ]

Making Copy-Paste More Intuitive

I find a number of the copy-pasting keys unintuitive. Let's modify them to mimic vim keybindings.

Recall that vim has a visual mode (v) that allows you to highlight a body of text. You can also "yank" text with y. Finally, you can paste the yanked text with p or P.

Let's use similar keymaps. Add these lines in the tmux config:

bind -T copy-mode-vi v send -X begin-selection
bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"
bind P paste-buffer
bind -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "pbcopy"

The first line, bind -T copy-mode-vi v send -X begin-selection, lets you begin selection (highlight) by pressing v while in copy mode (copy-mode-vi). The second line allows you to yank the text with y. The third line allows us to paste from the tmux buffer (where our text is saved) with Ctrl + P. The last line is a bonus. It lets you copy the text that you highlight with the mouse (note that it has the same effect as the second line).

Notice that on the second and fourth line, I use pbcopy. I need to use it to pipe the copied text into the clipboard on my Mac. If you're on linux, omit pbcopy:

bind-key -T copy-mode-vi y send -X copy-selection-and-cancel
bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel

As always, don't forget to save and source the config file. With this new setting, the workflow is:

Enter the copy-mode with Ctrl + [
Position yourself to the start of the text you want to copy with vim navigation
Start highlight with v (similar to vim visual mode)
Yank the highlighted text with y
Paste with Prefix + P

I use an uppercase P instead of lowercase p because Prefix + p is how tmux goes to the previous window (recall: Prefix + p to go to the previous window and Prefix + n to go to the next window. If you are not familiar with this, I'd highly recommend you to read my first tmux article).

Taking Advantage of the Vi Mode

The vi-copy-mode is not only useful for copying texts. You can use it to quickly search through your terminal.

For example, in the terminal, if you are looking for a text, you would press Cmd + f (or Ctrl + f) and type in the string that you want to search. This method has limitations. First, you can only search for that exact string (what if instead of searching for the string "mux", you want to search for "mux", "mix", and "max" simultaneously?). Second, if you have multiple panes in a window, this method will search for the text in all panes (what if you need to constrain your search only to the current pane?). Third, it is limited to what is currently displayed on tmux at the moment. Due to the nature of tmux's scrolling, it can't search for texts that are above the displayed window.

A better way to search is to leverage the vi-copy-mode. Recall that in Vim, you can search forward with / and backward with ?. With vi mode, you can do that too.

Suppose that I need to search for "redis_1" in my terminal. Here's how I would do it.

From inside a tmux session, enter the vi mode:

Prefix + [

Then search backward with:

? + KEYWORD

In this case, KEYWORD is "redis_1". I find myself using ? much more than /, because 80% of the time I would be searching backwards. Tmux should highlight all "redis_1" texts. To keep jumping to the subsequent or preceding matches, use either n or N. Sweet!

But wait, there's more! Just like you can use regular expressions in Vim while searching, you can with tmux too!

Suppose that I want to search for words like "redis_1" OR "node_1", OR "rails_1", I can search for all of them with [a-z]+_1:

? + [a-z]+_1

Regex breakdown:

[a-z] is the lowercase a-z
+ means one or more subsequent characters (which was a-z). [a-z]+ means one or more any lowercase alphabet character
_1 is a literal underscore followed by a literal one.

This will match "redis_1", "node_1", and "rails_1" (it will also match strings like "java_1", "sidekiq_1", etc.

If you want to match ONLY "redis_1", "node_1", or "rails_1", you can use a group match:

? + (redis|node|rails)_1

Pretty cool! I won't go through regex here because it's outside the scope of this article. The point is, searching in tmux using vi mode is a powerful tool especially if you're proficient with regex (even if you don't, you can get pretty far with just a little regex knowledge).

Emacs Copy Mode

If you look at the man tmux page, in addition to the vi-copy-mode, tmux also has an emacs-copy mode. It is similar to vi-copy-mode, but instead of using vi key bindings, it uses emacs key bindings.

If you're more of an emacs guy (don't worry, we can still be friends) and want to set it up to use emacs keybindings instead, check out inside the man tmux page under mode-keys section. There you will find instructions on how to set it up, including a list of keymaps.

Conclusion

In this article, we learned how to leverage the copy mode to make it easier to copy-paste from your tmux terminal. We also learned how to configure it to mimic vim copy-pasting behavior. This copy mode can be leveraged to be an effective search tool.

Tmux is a powerful tool. It complements with vim well. To make it even more powerful, you can configure it to behave like vim behaves.

Happy hacking!

Tmux Tutorial for Beginners

Igor Irianto — Wed, 10 Nov 2021 16:33:24 +0000

Intro

Tmux is life. That is not an exaggeration. Once you started using Tmux, you will ask yourself why you have not used it until now.

What Tmux Is

According to man tmux, Tmux stands for "Terminal MUltipleXer". Before you get perPLEXed by the phrase Terminal MUltipleXer, I'll explain what it means.

A terminal multiplexer lets you to leave a terminal in the middle of a process and return to it seamlessly. For example, suppose that you are running a rails server, vim editor, and a mysql console in the middle of a rails workflow. Then someone asks you to debug a completely different node project. Without tmux, I would probably stop the rails server, close vim, and exit the mysql server before starting the node-project task. This context switch causes a grinding halt in your flow. What if instead of killing those rails-related processes, you can "put them aside" (while they're still running), run whatever processes you need to complete your node task, then return to your original rails-project task as if you never left? That would be nice, wouldn't it? Tmux lets you do just that!

To be fair, you could argue that you could just open more tabs for node tasks instead of killing the previous rails processes. Although that would work, this could cause tab chaos. At some point, you'll start asking, "which of these 6 tabs did I just run the jest test?" or "which of these two Vim tabs was my rails codebase?". When you start mixing tabs from completely unrelated tasks without clear boundaries, you can't tell which tab is for what. This also causes a grinding halt to your workflow.

The terminal is the crux of my workflow. I need to organize my terminal. Imagine this: I can contain all my rails processes inside a session named "rails_project" and all my node processes in a session named "node_project". If I need to do node tasks, I'll leave rails_project and visit node_project session. When I'm done, I'll leave node_project and revisit rails_project. Easy!

Tmux allows me to create any number of terminals from a single screen and group them. I can "detach" them and they will still continue running in the background. The best part? I can "attach" them at any time. Tmux is great for long-term running processes and local development.

Don't you want to learn how to do that too?

Why Do I Want to Use Tmux?

Over time, the number of process dependencies you need to get a job done increases. Today, it is often not enough to have just two terminals: one for running rails server and one for running vim to accomplish your task. In reality, you probably need a rails server, a webpacker, a sidekiq, a redis instance, and a growing number of microservices to launch your app. In addition, you may need to have mysql console and rails console to see what's inside your app. You may even need a dedicated terminal to run your tests. Don't forget that SSH window to get the sql dump too! Even if you have docker-compose to host multiple services, if you need to debug them, you'll need multiple terminals to debug each service. My point is, a simple task today would require more than 10 different active processes! It makes it harder to switch context.

Even if you don't need to switch context often, it is still useful to categorize your sub-workflows within your workflow. Maybe today you are focusing on writing tests, so you need to use vim and a free terminal to run your test code; they would need to fit inside a display. The next day, you may need to solve a data migration issue, so you need a vim editor, a mysql server to view your databases, and a rails console to check your models. Within a single project, you can still experience a grinding halt when trying to accomplish a different task.

The point is, you need to reduce the frictions caused by context-switching in today's increasingly complex tasks. Tmux can help with that.

What to Expect From This Guide

Ultimately, you decide whether you want to use tmux or not. You don't have to use tmux. There are alternatives like GNU Screen, Terminator, Byobu, etc. Check them out and you decide whether or not to use tmux.

Personally, I think tmux is a better fit for my workflow. I am writing this guide to share what I understand about tmux. I hope that you will learn one or two useful things.

Here is what you will learn in this guide:

Sessions
Windows
Panes
Servers
Basic configs

By the end of this article, you will be faster than you would ever be without tmux. Hopefully you will learn enough to continue pursuing learning tmux on your own, just like the proverbs say:

Teach a man tmux, you improve his productivity for a lifetime (someone, probably)

Please read this guide slowly. It is tempting to speed-read through a book, call it done, and move on to the next book. To get the most out of this, take your time understanding each section. For every 5 minutes you spend reading, spend 15 minutes tinkering around with what you just read. Break things.

With that said, let's learn some tmux!

Installation

First, you need to install tmux if you haven't already. A good way to visit the tmux repository.

I am using a Mac, so for me, I just needed to run:

brew install tmux

Cool! Verify that it is installed. Run which tmux. It should return with a path. Now that tmux is installed, let's learn tmux's cornerstone: sessions.

Tmux Sessions

A tmux session is a collection of pseudo-terminals. Imagine running 10 different terminal processes, each doing different things. All these terminals are contained in a neat space that you can leave unattended and revisit at any time.

Creating a New Session

Let's use it. Run the command:

tmux

This will launch a new tmux session.

If you're still unsure about the tmux session, don't worry. I initially had a hard time grasping the concept too. It would become much easier once I started getting immersed in it. So let's continue.

Attaching and Detaching a Session

To exit a session, you need to *d*etach. Press:

Prefix + d

Hold up, what is a Prefix? I don't see any prefix key on my keyboard.

The prefix key can be anything you want. Many tmux shortcuts require you to press a prefix key first. If you're a Vim user, it is similar to the concept of a leader key. Think of it like a key to signal tmux that you are executing a tmux command. By default, tmux uses Ctrl + b as the Prefix key. From now, each time you see Prefix, it means Ctrl + b (hold Ctrl then press b). In this case, Prefix + d means holding Ctrl, then press b, then release them, then quickly press the letter d. Later, you'll learn how to change the prefix key from Ctrl + b to any key you want.

If you do it correctly, you should be taken out of the tmux session back to the original terminal.

When you're detaching from a session, any process running in that session is not terminated. It's still running. You just don't see it. Think of it like a background job.

Let's stop and appreciate how awesome this is. On a regular terminal, if we close the tab, whatever process that we were running would be terminated immediately. If I had rails server running and I close the tab, the rails server process would be killed. But if we detach from a session with rails server running, the rails server is still there. You are hiding the current process so you can focus on a different one. Later when you're ready to resume, you can "unhide" the rails server session by attaching into it.

To attach, from the terminal, run:

tmux attach

Aaannd you're back. Cool!

The command line equivalent to detach (Prefix + d) is:

tmux detach

Named Session

With tmux, you can liberally generate as many sessions as you need. Right now we have only one session running. To generate more sessions, you first need to be on the regular terminal (not inside a session). This time though, let's give our session a name. It's around breakfast time as I type this, so let's name it "breakfast" session (you can give it any name you want :D). Type:

tmux new -s breakfast

The alternative (verbose) command is tmux new-session -s breakfast, but I like to keep it short. With that, you should be in the tmux breakfast session. Yum!

While you're inside the breakfast session, recall that we also have the original session running. To see a list of sessions and travel between sessions, run:

Prefix + s

Now, let's detach from whatever session you are in and go back to the regular terminal (you're not inside any session). We now have two detached sessions: the original session and the breakfast session. So how do we attach to a particular session from the terminal? Earlier we ran the tmux attach to attach to the only available tmux session. Now that there are two sessions, we need to be more specific.

First, if you're forgetful like me and already forgot the name of your sessions, you can list the name of all the sessions by running

tmux ls

If I want to attach to the breakfast session, run the attach command with -t (target) followed by the session name:

tmux attach -t breakfast

Now I'm back to the breakfast session. Tmux is smart enough that you can give it a partial string. So if I run tmux attach -t b, as long as I don't have any session starting with b other than breakfast, tmux knows that I intend to go to breakfast.

Think of sessions like terminal containers. Modern development usually requires you to launch multiple services and jobs just to get the app running. For example, maybe the app that you're working on requires a redis server, a rails server, two node services, and a background job. You can use a session to contain all of those processes. This makes your workflow manageable and identifiable. If you ever need to leave them to work on something else, no need to kill them, just detach it, do whatever else you need to do, and -re-attach.

Killing a Session

Once you're done with the session task, you can kill that session.

There are two ways to kill a session:

Run the terminal command to kill a session
Close all the windows until there is no more

I'll start with method 1. To kill the breakfast session, run this from the terminal:

tmux kill-session -t breakfast

The kill-session command needs a target (-t) and a session name that you want to kill. Note the -t (target) argument is similar to the attach -t command. In tmux, anytime you have multiple targets and you need to pinpoint a single abstraction (like a session name), you probably need to pass it a target (-t) plus the target name.

Anyway, running tmux kill-session -t breakfast will effectively kill that session. Note: killing a session terminates all processes inside it - make sure that you save all your changes.

The second method is to kill all the panes and windows inside a session until there is nothing left. We will go over panes and windows in a little bit. For now, just follow along. To kill a pane, press:

Prefix + x

If you do that to every single pane and window, upon closing the last pane in the last window in a session, the session is effectively killed.

An alternative shortcut to Prefix + x is:

Ctrl + d

It does the same thing as Prefix + x. Personally, I prefer Ctrl + d because it only requires two keypresses as opposed to Prefix + x.

Tmux Sessions Conclusion

We are done with tmux sessions. Let's recap what we learned!

We learned that a session is like a container to a set of terminals. You can:

Create a session in tmux with tmux new -s MY_SESSION
Detach from a session with Prefix + d or tmux detach
List sessions with tmux ls
Attach to a session with tmux attach -t MY_SESSION
List sessions and switch to a different session with Prefix + s
Kill a session with tmux kill-session -t MY_SESSION
Close a pane / window with either Ctrl + d or Prefix + x

If you are new to tmux, let this soak in. Take time to internalize this. Practice, practice, practice. Don't rush to the next one. It's better to go at a slower pace but to retain more than go at full-speed but forget almost everything.

When you're ready, let's learn about tmux windows!

Tmux Windows

Tmux windows are subsets of tmux sessions. When you're creating a new tmux session (tmux new -s MY_SESSION), what you're seeing is technically a tmux window. Earlier I said that a tmux session is like a container of terminals. While that was true, each terminal activity happens inside a window. So technically, a tmux session is a container for tmux windows.

You can have as many windows as you want in a session. Since a window contains a terminal on its own, you can have a window dedicated for running your application server, another window for logging, and another window for text-editing.

Many tmux window commands are conceptually similar to the session commands. You can create, delete, and switch windows, just to name a few. I won't go through every single tmux window operation because in my opinion, you can be very productive just by learning only a few of them.

Creating a New Window

You can only create a new window from inside a tmux session. Since it's almost lunch time at the time I wrote this, let's start a new lunch session. From the regular terminal (not from inside tmux), create a new session. This should look familiar:

tmux new -s lunch

Cool! You're inside a session named lunch. You're looking at a tmux window. When you create a new session, tmux automatically creates a new window.

So right now there is one window - the default window - in the lunch session. To create a new window inside a session, run this command:

tmux new-window -n fried-rice

This creates a new window named fried-rice (I had that earlier this week). If the new-window command is too verbose, you can shorthand it a bit with neww. Let's create a new window named ramen, because I'm craving that right now:

tmux neww -n ramen

Practically speaking though, I almost never use the new-window terminal command. 99% of the time, I use the following new-window keyboard shortcut:

Prefix + c

Try creating two or three new windows! Get this in your muscle memory. Window creation is one of the most often-used commands in my tmux workflow.

Switching Windows

By now you should have multiple windows in a session. Let's learn how to quickly switch windows.

Right now I have three windows:

the default window
fried-rice window
ramen window

I am currently on the first window. If I want to go to the *n*ext window, I can do that with:

Prefix + n

Retrospectively, to go to the *p*revious window:

Prefix + p

Another thing to know is that tmux window is indexed like an array data structure. In many programming languages, an array data structure is zero-indexed. Tmux window is also zero-based. The first window is window number 0, the second window window number 1, etc. To go to window number N, you can run:

Prefix + N

Whereas N is the window number. So if I want to go to the first window, Prefix + 0 will do it. What if I want to go to the second window? Prefix + 1. Third window? Prefix + 2. In my regular workflow, I try to keep my window collections small. Normally I don't have more than 5 tmux windows in any session (if I have more, it can quickly get out of control). However, people's workflows are different. You may function better by having dozens of windows in any session. Use whatever works for you.

If that's the case, how can you quickly jump to window number 11? The Prefix + N shortcut only accepts one key. When you try to do Prefix + 10 (the 11th window), tmux thinks you're doing Prefix + 1. To quickly jump to double window digits, you can use:

Prefix + ' + N

Whereas N is the window number. First, press the prefix. Then press ' (a single quote). This lets you enter any window index number, like 10. Then press Return.

I forget things a lot (my wife can vouch for that :D). I can hardly keep track of the 5 windows I have opened in the current session. I definitely can't keep track of all the windows across all my sessions if I have multiple sessions running. Luckily, you can quickly list and switch to any window in any session with:

Prefix + w

When you do Prefix + w, tmux lists all the windows inside all the sessions you have (even the windows from detached sessions). Try it! I also use this command a lot.

Renaming Windows

A window name is used to identify what the window is about. It's good to give it a succinct name. If I'm debugging a controller test, then I'll create a new window named "controller test" (yes, not original, but it's concise!). However, sometimes your task changes. The "controller test" task may morph into "feature test" (shudders). In this case, you may want to rename your window. To rename the current window:

Prefix + ,

Your cursor is now on the lower window area where you can edit the window name.

Deleting Windows

When you're done with a window, you may want to delete it so it doesn't crowd your session. There are two ways to kill a window:

kill the window with a terminal command
kill all panes inside a window

For method 1, you can run this from inside a window:

tmux kill-window

This kills the current window you're in. If you want to kill a different window, you can pass a target option to the command -t. To kill the "ramen" window:

tmux kill-window -t ramen

For a less verbose option, you can use killw instead of kill-window:

tmux killw -t fried-rice

For the second method, you can run:

Prefix + x

Ctrl + d

Tmux Windows Conclusion

We are done with tmux windows. Let's recap.

A window is where your terminal lives. A session consists of one or more windows. Some window commands that we learned:

Create a window with tmux new-window -n MY_WINDOW or Prefix + c
Switch to a different window with Prefix + n, Prefix + p, and Prefix + N (where N is the window index number, zero-based)
Kill a window with tmux kill-window -t MY_WINDOW
Close a pane / window with either Ctrl + d or Prefix + x

As always, take your time to internalize this. Practice what you've learned about windows and sessions. Try to create several windows, navigate between them, and delete them. Create a new session and create some new windows there too.

Don't rush. When you're ready, it's time to learn about tmux panes!

Tmux Panes

Earlier I said that when you started a new session, what you saw was a tmux window. I lied, again. What you saw was actually a tmux pane inside a tmux window inside a tmux session. When you started a new session, tmux automatically created a new window. When a new window was created, tmux generated a new pane. Just like how a tmux session has at least one window, a tmux window always contains at least one tmux pane.

Now that we've been exposed to sessions, windows, and panes, let's get the terminology straight. A tmux window is a container to tmux panes. A tmux session is a container to tmux windows. When you start a session, you have at least one tmux window. Inside a session, you can create many windows (Prefix + c). Inside a tmux window, you have at least one tmux pane. When you split a window for the first time, you are splitting it into two panes. Each boxed terminal is a pane in its own right. The hierarchy goes like this: Session > window > pane.

Let's go through some tmux pane operations.

Creating a New Pane

If you own tablets or large smart phones, they probably have a feature to split the screen in half so you can open two apps simultaneously. Panes are similar such that you can split the screen vertically (or horizontally) so you can have multiple terminals in a single window.

A tmux window can be split many times into smaller panes. The command to split a window horizontally is:

tmux split-window -h

To split it vertically:

tmux split-window -v

They are rather easy to remember: -h for *h*orizontal and -v for *v*ertical.

To split a window horizontally with a keyboard shortcut:

Prefix + %

To split a window vertically:

Prefix + "

Split windows are also one of my most frequently used tmux commands. Commit them to your muscle memory!

Deleting a Pane

To delete a pane is similar to deleting a window:

Prefix + x

Ctrl + d

This is our third time seeing Prefix + x and Ctrl + d. Now you finally understand what this command actually does. It deletes a pane. When the last pane of a window is deleted, that window is automatically removed. When the last window of a session is deleted, that session is automatically killed.

Navigate Between Panes

Let's learn the different ways to navigate between panes. First, create multiple panes in a window. Use the Prefix + % or Prefix + & shortcut to do that.

To switch to the "next" pane, run:

Prefix + o

Tmux focuses on a different pane each time you run that command.

You can also move directionally with:

Prefix + Up
Prefix + Down
Prefix + Left
Prefix + Right

These commands give you slightly more control. Now you can instruct tmux which direction you want to focus on.

But that's not all. Tmux can also display all the pane numbers of the current window for you to select from. Run:

Prefix + q

You should see numbers displayed in the foreground center of each pane. If you type a particular number, tmux will focus on that pane number.

So if I want to go to pane number 1, I just run:

Prefix + q + 1

To go to pane number 5, run:

Prefix + q + 5

Btw, you could also have done this with:

tmux display-panes
tmux select-pane -t N

The first command lists all the panes and the second command jumps to pane number N. I personally would rather to Prefix + q + N. Ain't nobody got time to type all that! :)

Resize a Pane

I usually have about 2-3 panes in a window. But you may need to adjust their sizes. For example, the other day I had to debug a controller spec. I had the tmux window split horizontally into two panes: top and bottom. I had Vim on the top window and the terminal on the bottom for running the specs. By default, tmux splits them equally, but I prefer to have Vim to have more screen real-estate. To resize a pane, you can run one of the followings:

tmux resize-pane -D 10
tmux resize-pane -U 10
tmux resize-pane -L 10
tmux resize-pane -R 10

The number 10 is a measurement unit (tmux "cells"). The -D/U/L/R options stand for Down/Up/Left/Right. Unfortunately, there are no keyboard shortcuts for this. You can create your own shortcuts to make resizing quicker. I'll show you how to do that in a later section.

Zoom a Pane

Another feature I find helpful is pane zooming. If you have four panes displayed in a window, each taking up 25% of that window total area, you can zoom your current pane into 100% and hide the other panes with:

Prefix + z

Now it looks as if you only have a single pane, allowing you to view the current pane at maximum area. This is useful if you need to remove distractions and focus on a specific task at a specific pane. Then once you're done, you can de-zoom and return to the previous layout by running Prefix + z one more time.

Swapping Panes

If you have two panes in a window side-by-side, you can swap them with:

Prefix + {
Prefix + }

You can also rotate the pane positions with:

Prefix + Ctrl + o

Tmux Layouts

While we are discussing panes, let's learn about tmux layouts. because they are closely related.

"Wait a minute, what are tmux layouts?" Good question! Tmux layouts are pane arrangements to organize your panes in a window. Tmux comes with five ready-to-use layouts. If that description is ambiguous and you're still confused, don't worry. Just follow along and you'll understand it soon enough!

Create a new window. Then split it horizontally once (Prefix + %). Then split it vertically once (Prefix + "). Your window should now have three panes: one half on the left, and a quarter on top right and a quarter on bottom right.

Let's go back to layouts. Tmux comes with 5 different layouts:

even-horizontal
even-vertical
main-horizontal
main-vertical
tiled

Let's try them. Type:

tmux select-layout even-horizontal

Note how your tmux window is now split horizontally evenly. Just like the name says, the even-horizontal layout re-arranges the current panes into equidistant horizontal panes.

Let's try the vertical one:

tmux select-layout even-vertical

Let's try a different flavor:

tmux select-layout main-vertical

Your tmux window is now split horizontally with the "main" pane taking up more space - while the other two panes are split evenly, taking up less window real estate. Let's try the horizontal version:

tmux select-layout main-horizontal

Finally, let's see what the last one looks like:

tmux select-layout tiled

Now your tmux window is split equally. If you had 3 panes, it wouldn't exactly be split evenly, but if you had 4 panes, it would split them perfectly equal.

You can toggle tmux layouts with a keyboard shortcut. Press:

Prefix + Space

The first time you press Prefix + space, tmux goes to even-horizontal layout, then it goes to even-vertical layout, then main-horizontal, etc. It cycles between those five layouts.

Tmux Panes Conclusion

Let's go over what we learned.

You learned about tmux pane. A pane is where your sub-terminals are displayed through. A window can have one or more panes. Here are the commands you learned:

Split a window horizontally with tmux split-window -h or Prefix + %
Split a window vertically with tmux split-window -v or Prefix + "
Delete a pane with Prefix + x or Ctrl + d
Navigate to the next pane with Prefix + o
Navigate to another pane directionally with Prefix + Up/Down/Left/Right
Navigate to pane number N with Prefix + q + N
Resize a pane by N unit with tmux resize-pane -D/U/L/R N
Zoom/de-zoom a pane with Prefix + z
Swap panes with Prefix + { or Prefix + } and rotate panes with Prefix + Ctrl + o
Toggle layouts with tmux select-layout even-horizontal/even-vertical/main-horizontal/main-vertical/tiled or Prefix + Space

Tmux pane is a unique feature that differentiates tmux from most regular terminals. Usually, to start a new terminal, you need to open a new tab. But what if you need to have two terminals side-by-side? With tmux, you can easily split a window into two or more panes. You can even organize how the panes are displayed.

As always, take your time to digest what you just learned. Play around! Create multiple panes in a window, then navigate around them. Delete some panes. Resize them. Zoom in and out. Change the layouts.

Combine this lesson with what you've learned. Create a new session. Create a few new windows with multiple panes in them. See how fast you can go from the current pane to another pane in a different window from a different session. Do this until you can navigate around effortlessly. Take as much time as you need.

When you are ready, let's learn about tmux servers!

Tmux servers

By now, you should have a good idea what tmux can do. You should also understand how sessions, windows, and panes relate (otherwise, stop and review the last three sections). There is one more missing piece: tmux servers. Although you can do fine merely knowing about sessions, windows, and panes without knowing about tmux servers, it is good to know the whole picture to have a more accurate mental model. Understanding tmux server will explain why some commands, like tmux kill-server, exist (to kill the server, duh!)

When we run the command tmux, tmux not only creates a new session, but it also creates a new server instance. This whole ecosystem that you have been interacting with - you can think of it like the client in client-server interaction. If it is like a client-server interaction, then there must be a tmux server somewhere. Tmux server is what runs in the background while Tmux client runs in the foreground.

When we create multiple sessions: tmux new -s breakfast, tmux new -s lunch, and tmux new -s dinner, those three are connected to the same tmux server. Since we don't mention a server name, these sessions are connected to a default server.

To launch a named server - let's name it the food server - run this from the regular terminal:

tmux -L food

This creates a new server named food. Running this command also launches a new session by default. Cool! Let's detach from this server (Prefix + d).

So we have a food server running somewhere in your machine, but you are detached from it. What if you want to reconnect to the food server? Run:

tmux -L food attach

You'll be reattached to the food server. Wait a minute, this looks like the attach command from way earlier when we only had one session (tmux attach). It's because it is. The difference is that we are attaching back to a session from the food server instead of the default server.

Running tmux -L food creates a default session inside the food session. What if we want to create a named session? To create a new named session inside the food server, say a roast-duck session, we can run:

tmux -L food new -s roast-duck

Recall that running tmux ls will list the sessions from the default server. But what if we want to view all the sessions in the food server? Easy, run:

tmux -L food ls

If we want to attach to the roast-duck session in the food server, run:

tmux -L food attach -t roast-duck

Finally, to kill this food server, you can run:

tmux -L food kill-server

The kill-server command kills a server. When a server is killed, it kills everything inside it (sessions, windows, and panes) - make sure that you save everything before closing it. By the way, to kill the default (unnamed) server, just run:

tmux kill-server

If you run tmux kill-server when nothing is running, you'll see:

no server running on /private/tmp/tmux-501/default

Your exact path might be different from what I have, but the important ideas are:

The command kill-server is looking in the tmp/ directory, which is usually where linux sockets are. Wait, did you say socket? That sounds like a client-server interaction!
The directory is named "default" because we tried to kill the default server. By the way, if you created multiple servers, you'll find all those server names stored in here. So if you created a food server, you would find /food in there too.

Phew. That's a lot to take in. Let's practice what we just learned to solidify what we just learned. Do the following:

Create 2 new tmux servers (give them any name you want)
Inside each server, create multiple sessions. Inside each session, create multiple windows. Inside each window, create multiple panes
Detach from one server and attach to the other one
Delete the servers

Practically speaking, I almost never use more than one server in my workflow. However, your use case might be different. Regardless, it wouldn't hurt to know! The more you know, the less you don't know.

Customizing tmux

In my opinion, tmux could use a better set of keys. For example, I find that using the Ctrl + b keys are not comfortable. Let's change some key shortcuts.

You can modify tmux keys with the tmux config file. When you launch tmux, it looks for a file named .tmux.conf in the HOME path - in my case, it is ~/.tmux.conf. If it isn't there yet, create a file .tmux.conf in your HOME path.

Let's change the tmux prefix. Some of the popular prefix alternatives are:

Ctrl + a
Ctrl + Space
Ctrl + s
Ctrl + u
Backticks
Tab + key variation instead of Ctrl + key
etc

Personally, I use Ctrl + Space mainly because my Vim leader key is the Space key. But ultimately, use whatever keys that make the most sense to you.

To change your prefix to Ctrl + Space, add these in the tmux config file:

unbind C-Space
set -g prefix C-Space
bind C-Space send-prefix

The changes above won't take place immediately. You first need to source the file. You can either close tmux (kill your tmux session and start a new one) or source the config file.

To source tmux config file, from inside a tmux session, run:

tmux source-file ~/.tmux.conf

By the way, in the future, I would like to be able to source my configurations quickly with Prefix + r. Add this in the config file:

bind-key r source-file ~/.tmux.conf \; display-message "Tmux config reloaded!"

Don't forget to restart the tmux session. Now you can just run:

Prefix + r

To quickly source your file.

By the way, with some changes, you may notice that even running Prefix + r isn't enough. You need to also restart the tmux server. Detach from the session, kill the server (tmux kill-server), then start a new session. Alternatively, you can also run Prefix + I (note the I is uppercased) to reload the tmux environment.

In short, if running Prefix + r is not sufficient, try running Prefix + I also. If all fails, restart the tmux

Two more shortcuts that I don't find intuitive are the window splits, Prefix + % and Prefix + ". To me, it makes more sense to use | for a vertical split and - for a horizontal split. Add these lines:

bind | split-window -hc "#{pane_current_path}"
bind - split-window -vc "#{pane_current_path}"

Now when I press Prefix + |, tmux does a vertical split and when I press Prefix + -, tmux does a horizontal split.

More configs?

There are many different ways you can configure your tmux config. To address them all would be out of the scope of this article.

If you want to learn more about tmux configs, I am currently working on another article to address tmux configs in more detail, so stay tuned! I will update this post with the link to the said article when it is done.

11/18 Update: Part 2 is out! Check it out here: Useful Tmux Configuration Examples.

If you want to see what my personal configs look like, check out my dotfiles.

Conclusion

Phew, we have now reached the end of this guide. I hope that you learned valuable things about tmux. If there is anything that is unclear, please feel free to drop by the comment section.

Here's the final recap. In this guide, we learned about tmux session, window, pane, and server. We learned about their relationships with each other. We also learned a little about configuring tmux. In the next article, you will learn more about configuring tmux in detail. I will update this guide with the link to the next article when it is ready.

More importantly, take your time reading this guide. It can be tempting to read through the entire guide without doing any practice. Take a day to read about a section and let it digest. Apply what you learn that day. Instead of reading for 15 minutes and practicing for 5 minutes, for every 5 minutes you learn about something, spend 15 minutes. Yes, it is a lot. Yes, you'll read less on average. But you will learn a lot more. In the end, what you learn is what actually matters, not the amount of articles/ books you read.

Happy coding!

What Is Inside My Vimrc

Igor Irianto — Thu, 16 Sep 2021 14:55:08 +0000

A vimrc is an important file for us Vim users.

Edit: My Vimrc has changed since I began writing this article (it is now 7 lines long), but the principle is still the same. If you want to look at the state of the Vimrc at the time I wrote this article, check out this link.

If you're like me, you probably have spent an ungodly amount of time tinkering with it until it grows massive. At some point, it is a good idea to split your vimrc into multiple parts for maintainability. Plus, if you want to share your vimrc to the world, splitting it into an organized structure will help clarify with other devs who are looking at your vimrc.

In this article, I will share how I organize my vimrc. Everything here is a matter of personal preference. There is no objectively right or wrong way to organize a vimrc. I hope that by sharing what's inside my vimrc, you will gain insight into how you can organize your own vimrc to meet your needs. Don't put down any line in your vimrc that you don't understand.

Lastly, this article makes the assumption that your default vimrc file and Vim files directory are in the root directory, ~/.vimrc and ~/.vim/, respectively.

Source, The Secret Sauce

The secret sauce of a modular vimrc is the source Vimrscript command. Think of it like the require, include, or import command.

If you have this inside your ~/.vimrc:

source '~/my-script.vim'

Inside ~/my-script.vim:

echo "Hello from outside yo vimrc"

The next time you open Vim, it will output "Hello from outside yo vimrc". Great! This is how you can split your vimrc into multiple parts.

Dotfiles

My Vim configs are stored inside my dotfiles repository - this way I can access them when I'm away from my computer. So if I have to login from a foreign computer, all I need to do is symlink the Vim files from the dotfiles repository, install the dependencies (I have a script for that too, but that's for another time), and I'm set to go!

The Structure

This is the structure for my Vim-related files:

dotfiles/
├─ vim/
│  ├─ custom-functions/
│  │  ├─ function1.vim
│  │  ├─ function2.vim
│  │  ├─ function-N.vim
│  ├─ custom-plugins/
│  │  ├─ ale.vim
│  │  ├─ fzf.vim
│  │  ├─ plugin-N.vim
│  ├─ main/
│  │  ├─ settings.vim
│  │  ├─ themes.vim
│  │  ├─ keymaps.vim
│  ├─ UltiSnips/
│  │  ├─ javascript.snippets
│  │  ├─ ruby.snippets
│  ├─ vimspector.json
├─ vimrc

The important ones are the vimrc file and the vim/ directory.

Note that I name them without the dot (vimrc and vim/ as opposed to .vimrc and .vim/). This is so that when I clone it, they won't be invisible. It's easier to deal with visible files than invisible ones.

Inside the vim/ directory, I divide them into multiple sub-directories. The three important ones are:

custom-functions/ where I store my own custom functions
custom-plugins/ where I store configs specific for Vim plugins
main/ where I store the main Vim configurations and basic keymaps

If you notice, I also have a vimspector.json file and a UltiSnips/ directory. I use the Vimspector plugin and it requires a config file. I also use the ultisnips plugin. It usesUltiSnips/ directory to store custom snippets. If you don't use any of these plugins, just ignore them.

Vimrc

The vimrc file is called first whenever you launch Vim. Inside it, we have:

if empty(glob('~/.vim/autoload/plug.vim'))
  silent !curl -fLo ~/.vim/autoload/plug.vim --create-dirs
    \ https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
  autocmd VimEnter * PlugInstall | source $MYVIMRC
endif

call plug#begin('~/.vim/plugged')
  Plug 'iggredible/totitle-vim'
  Plug 'tpope/vim-sensible'
  Plug 'sjl/badwolf'
  Plug 'itchyny/lightline.vim'
  Plug 'junegunn/fzf.vim'
  Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
  Plug 'ludovicchabant/vim-gutentags'
  Plug 'tomtom/tcomment_vim'
  Plug 'mattn/emmet-vim'
  Plug 'sheerun/vim-polyglot'
  Plug 'tpope/vim-fugitive'
  Plug 'Yggdroot/indentLine'
  Plug 'preservim/nerdtree'
  Plug 'luochen1990/rainbow'
  Plug 'tpope/vim-dispatch'
  Plug 'junegunn/vim-peekaboo'
  Plug 'machakann/vim-sandwich'
  Plug 'simnalamburt/vim-mundo'
  Plug 'tpope/vim-endwise'
  Plug 'tpope/vim-unimpaired'
  Plug 'godlygeek/tabular'
  Plug 'mhinz/vim-signify', { 'branch': 'legacy' }
  Plug 'ryanoasis/vim-devicons'
  Plug 'dense-analysis/ale'
  Plug 'szw/vim-maximizer'
  Plug 't9md/vim-choosewin'
  Plug 'Shougo/unite.vim'
  Plug 'puremourning/vimspector'
  Plug 'SirVer/ultisnips'
  Plug 'honza/vim-snippets'
call plug#end()

let b:fileList = split(globpath('~/.vim/main', '*.vim'), '\n')
let b:fileList += split(globpath('~/.vim/custom-functions', '*.vim'), '\n')
let b:fileList += split(globpath('~/.vim/custom-plugins', '*.vim'), '\n')

for fpath in b:fileList
  exe 'source' fpath
endfor

My vimrc is less than 50 lines long, including empty lines. Hey, that's pretty readable! Let's go over what they do.

Automatically Installing Vim Plug

I use vim-plug as my plugin manager. The code below checks for the existence of ~/.vim/autoload/plug.vim when you start Vim. The plugin manager uses that file to read the plugin files. If plug.vim doesn't already exist, then it will download the plug.vim file and create the ~/.vim/autoload/plug.vim directory.

if empty(glob('~/.vim/autoload/plug.vim'))
  silent !curl -fLo ~/.vim/autoload/plug.vim --create-dirs
    \ https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
  autocmd VimEnter * PlugInstall | source $MYVIMRC
endif

You can also find the automatic install script above in the vim-plug tips page.

I haven't really looked at other plugin managers, but I'm confident that you can pull something similar with other plugin managers.

Plugins

The next line lists a list of plugins I use:

call plug#begin('~/.vim/plugged')
  Plug 'iggredible/totitle-vim'
  Plug 'tpope/vim-sensible'
  Plug 'sjl/badwolf'
  Plug 'itchyny/lightline.vim'
  Plug 'junegunn/fzf.vim'
  Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
  Plug 'ludovicchabant/vim-gutentags'
  Plug 'tomtom/tcomment_vim'
  Plug 'mattn/emmet-vim'
  Plug 'sheerun/vim-polyglot'
  Plug 'tpope/vim-fugitive'
  Plug 'Yggdroot/indentLine'
  Plug 'preservim/nerdtree'
  Plug 'luochen1990/rainbow'
  Plug 'tpope/vim-dispatch'
  Plug 'junegunn/vim-peekaboo'
  Plug 'machakann/vim-sandwich'
  Plug 'simnalamburt/vim-mundo'
  Plug 'tpope/vim-endwise'
  Plug 'tpope/vim-unimpaired'
  Plug 'godlygeek/tabular'
  Plug 'mhinz/vim-signify', { 'branch': 'legacy' }
  Plug 'ryanoasis/vim-devicons'
  Plug 'dense-analysis/ale'
  Plug 'szw/vim-maximizer'
  Plug 't9md/vim-choosewin'
  Plug 'Shougo/unite.vim'
  " Plug 'puremourning/vimspector'
  Plug 'SirVer/ultisnips'
  Plug 'honza/vim-snippets'
call plug#end()

This part is totally up to you. Use whatever plugins that you need, not what you see other people use.

Sourcing Stuff

Here's what the next 3 lines look like:

let b:fileList = split(globpath('~/.vim/main', '*.vim'), '\n')
let b:fileList += split(globpath('~/.vim/custom-functions', '*.vim'), '\n')
let b:fileList += split(globpath('~/.vim/custom-plugins', '*.vim'), '\n')

We are creating an array named fileList and appending it with the paths for all the files inside main/, custom-functions/, and custom-plugins/.

Finally, we have this loop. This is where the magic happens.

for fpath in b:fileList
  exe 'source' fpath
endfor

It iterates through the fileList array and calls source on each file. This keeps my vimrc to be concise and spark joy :D.

Next, let's explore some contents of my main/, custom-functions/, and custom-plugins/

the Main Directory

The main directory contains the base vimrc configs that don't depend on any custom plugin.

Inside, I sub-divide them into three files:

settings.vim
keymaps.vim
themes.vim

Main Settings

This is what's inside the settings.vim file:

set clipboard=unnamed
set noswapfile
set relativenumber number
set tabstop=2
set shiftwidth=2
set expandtab
set ignorecase
set smartcase
set hlsearch
set confirm
set hidden
set shortmess-=S

let s:english_dict = "/usr/share/dict/words"

if filereadable(s:english_dict)
  let &dictionary=s:english_dict
endif

This file primarily deals with base settings (if you're curious what they do, consult :help). The last command with the english_dict adds a dictionary autocompletion (CTRL-X CTRL-K), if a dictionary exists.

Main Keymaps

The keymaps.vim file contains key mappings independent from plugins. For plugin-specific maps, they are inside custom-plugins/.

Inside my keymaps.vim, I have:

let mapleader = "\<Space>"

nnoremap <Leader>vs :source ~/.vimrc<CR>
nnoremap <Leader>ve :vsplit ~/.vimrc<CR>

nnoremap <Esc><Esc> :noh<Return><Esc>

I like to use Space as the leader - but you can use whatever leader key you feel comfortable with.

I have three custom maps. The first two, <Leader>vs and <Leader>ve, are to quickly open and source (vs mnemonic: Vimrc Source) Vimrc (mnemonics: Vimrc Edit and Vimrc Source). I've used this countless times.

I also have a <Esc><Esc> mapped to :noh (nohighlight). This is used to remove the highlights after searching for keywords.

Main Themes

The themes.vim file contain configurations for the color schemes and various UI-related settings.

silent! colorscheme evening
silent! colorscheme badwolf

highlight CursorColumn guibg=#ecf0c1
highlight CursorLine guibg=#ecf0c1

set termguicolors
set background=dark

If you notice, I use two color schemes. What's up with that?

badwolf is a custom color scheme plugin. When I launch Vim for the first time on a new machine, I won't have the plugins installed yet, using badwolf immediately will cause it to fail on that first Vim run. evening is a built-in Vim color scheme. By putting silent! colorscheme evening followed by silent! colorscheme badwolf, if badwolf isn't available, it will, in effect, falls back to evening. silent! will also omit the error message (otherwise you'll see an error message when Vim couldn't find badwolf)

Custom Functions

The custom-functions/ directory is where all the custom functions live. These are user-specific functions. What I need might be different from yours. But I'll go over some of mine anyway. Feel free to take them, modify them, and steal them (I stole two of them somewhere sometime ago :P).

I have four custom functions. Here are some of them.

Custom Functions to Delete Buffers

function! DeleteAllBuffers()
  let l:current_pos = getpos('.')
  execute "%bd | e# | echo 'Buffers Deleted'"
  call setpos('.', l:current_pos)
endfunc

function! DeleteMatchingBuffers(pattern)
    let l:bufferList = filter(range(1, bufnr('$')), 'buflisted(v:val)')
    let l:matchingBuffers = filter(bufferList, 'bufname(v:val) =~ a:pattern')
    if len(l:matchingBuffers) < 1
        echo 'No buffers found matching pattern ' . a:pattern
        return
    endif
    exec 'bd ' . join(l:matchingBuffers, ' ')
endfunction

command! -nargs=1 DelBuf call DeleteMatchingBuffers('<args>')

nnoremap <silent> <Leader>bD :call DeleteAllBuffers()<CR>
nnoremap <silent> <Leader>bd :DelBuf<Space>

I won't go into how Vimscript works. If you want to learn Vimscript, check out my Learn Vim book (free to read).

The main point is, I have a target-delete <Leader>bd to delete a specific buffer(s) and mass-delete <Leader>bD to delete all buffers except the current one.

After coding for a few hours, my buffer list would usually balloon and get convoluted. I'd need to clear them up.

If you run <Leader>bD, it will indiscriminately delete all items in the buffer list (:ls).

If you run <Leader>bd, it will ask for a pattern. Vim will delete all buffers matching the pattern. So if you have users_controller.rb, packages_controller.rb, user_model.rb, and package_model.rb and you enter "controller" as pattern, it will delete the controller buffers and keep the model buffers.

Custom Functions to Open Url Under Cursor

function! OpenURLUnderCursor()
  let l:uri = expand('<cWORD>')
  silent exec "!open '" . l:uri . "'"
  redraw!
endfunction

nnoremap gx :call OpenURLUnderCursor()<CR>

This one is actually a native feature of Vim (NETRW actually - :help netrw-gx). By pressing gx while your cursor is inside a URL, Vim will open that document. However, in Mac, that behavior doesn't work.

Custom Functions to Toggle Cursor Display

function! ToggleCursor()
  if(&cursorcolumn == 1)
    set nocursorcolumn
  elseif (&cursorcolumn == 0)
    set cursorcolumn
  endif

  if(&cursorline == 1)
    set nocursorline
  elseif (&cursorline == 0)
    set cursorline
  endif
endfunction

nnoremap <leader>tc :call ToggleCursor()<CR>

You can toggle the horizontal cursor highlight with :set cursorline / :set nocursorline and the vertical cursor highlight with :set cursorcolumn / :set nocursorcolumn. This can be useful if you need a makeshift straight edge.

Custom Functions to Toggle Numbers

function! ToggleNumber()
  if(&relativenumber == 1)
    set norelativenumber
  else
    set relativenumber
  endif
endfunc

nnoremap <leader>tn :call ToggleNumber()<CR>

I like using relativenumber to see how far apart a text is from the cursor. However, there are times when I need to see the absolute line number instead. This allows me to quickly toggle the number setting.

Custom Plugins

Finally, the custom-plugins/ section is where the settings for each plugin is.

Since there are so many of them, I will only cover one or two in this article. If you're curious, feel free to check out my dotfiles repository and see what else I have.

Inside the custom-plugins/ directory, I have files named after the plugin itself (you can name them anything you want).

For example, inside ale.vim (ale is a linting engine for Vim):

" -------------------------
" Configs
" -------------------------

let g:ale_linters = {
      \   'javascript': ['eslint'],
      \   'ruby': ['rubocop'],
      \}

let g:ale_fixers = {
      \   'javascript': ['eslint'],
      \   'ruby': ['rubocop'],
      \}
let g:ale_linters_explicit = 1 " Only run linters named in ale_linters settings.
let g:ale_sign_column_always = 1

" -------------------------
" Keymaps
" -------------------------

nmap <silent> <C-k> <Plug>(ale_previous_wrap)
nmap <silent> <C-j> <Plug>(ale_next_wrap)

nnoremap <Leader>at :ALEToggle<CR>

Here, I have ale configured for Javascript and Ruby (using eslint and rubocop) - because I mainly work with Ruby and Javascript. Finally, I also have some keymaps related to the ale plugin.

Many of the plugins that I use don't need any configurations, like emmet-vim, tcomment_vim, vim-sandwich, etc. You'll find that you don't need as many custom-plugin files as you have plugins installed.

What Is Next?

This concludes this article. I hope that you learned a thing or two. Make your vimrc uniquely yours. Keep improving everyday.

For max usage, I strongly recommend you reading this in conjunction with my dotfiles article for a complete guide on portability.

If you're still hungry for more, I suggest looking up other people's Vimrcs. Here are a few that I can think of.

Resources

Some great resources to learn and steal (cough) Vimrcs (and dotfiles):

How to Use Rsync to Backup Your Files

Igor Irianto — Fri, 03 Sep 2021 16:00:13 +0000

What Is Rsync

If you've been programming for a while, you may have heard of rsync. It is a tool to transfer and synchronize files in different directories. These directories can be inside the same machine or between two connected machines.

Some of you may wonder, "Well, why can't I just use the copy command cp, that way I don't have to learn a new command?" These two are two different programs. cp copies everything from one location to another, while rsync copies the deltas (the differences) from one location to another.

Suppose that your source directory A contains files totaling 1GB in size. Assume that you also have directory B with the same 1GB of files. Then you add small changes of about 0.1GB. With rsync, you won't have to copy the whole 1.1GB of data from A to B. You will only have to transfer 0.1GB of data. Why copy mostly the same data if you can just copy only the differences? This lets you minimize the network usage, which can be useful if you have a small bandwidth.

Let's jump straight to the code. I would strongly encourage you to code along. I find it more useful when learning a new thing if I actually type the commands. Moreover, don't just type everything you see in this article and stop there. Experiment with these commands. Read the man rsync page. Make variations. Experiment. Do things that I don't mention here. Break things! Just make sure you make a backup first (see what I did there? :D) Only by doing these you'll get the most out of this article.

Basic rsync

At its core, the rsync command looks like this:

rsync source destination

Suppose that you have a file ~/Projects/source/file1.txt that you want to sync to ~/Projects/destination/. Run:

rsync ~/Projects/source/file1.txt ~/Projects/destination/

You should see file1.txt inside destination/ now. Cool! However, practically speaking, you probably don't need to rsync a single file. Rsync is usually used on a directory.

To rsync the source/ directory (including all its files) to the destination/ directory, run:

rsync source/* destination/

Now you will find all the files inside source/ are copied inside the destination/. If you run the command rsync source/* destination/ again without making any changes, rsync won't do anything (there are no deltas).

If you add a file inside source/ that is not yet in destination/, running the rsync command adds that file into destination/.

If you remove a file inside source/ and that file is also inside destination/, running the rsync command will not remove that file from destination/. Rsync by default has an additive nature. To also delete a file in destination/ when the source file is deleted, pass the --delete option.

Finally, if you add a directory inside source/, the rsync command above won't sync the directory (and neither the contents inside that directory). To sync directories within a source directory, you need to use rsync recursively.

Recursive Rsync

The -r option syncs a directory recursively. If your source/ directory contains:

file1.txt
file2.txt
dir1/
dir1/file1.md
dir1/file2.md

Running rsync source/* destination/ won't bring dir1/ (and the files inside it) into the destination/ directory. However, if you run:

rsync -r source/ destination/

Everything will carry over. Neat!

Rsync Archive

If you read online articles about rsync, you will notice that many developers use the -a command (--archive). This is analogous to running rsync -rlptgoD. Whoa, that's a lot of options! Don't worry, let's break it down:

-r is recursive, just as you saw above
-l copies symlinks and keep them as symlinks
-p preserves file permissions / privileges
-t preserves time metadata in a file
-g preserves a group
-o preserves owner (only for super-user)
-D preserves device and special files

The big picture is, running rsync -a preserves all the important metadata when transferring files. It is safe to say you will want to run rsync -a 90% of the time.

Rsync and SSH

You can use rsync over a network connection. If you have access to a remote server, you can quickly sync your directory locally with a remote server, vice versa.

Wait a second... doesn't that sound like dropbox? Yup! There are tons of other features that Dropbox has that rsync doesn't, but at the gist of it, dropbox is a fancy and glorified rsync with durability added.

For this section, if you're coding along, I am assuming that you have access to a remote server. If you don't, keep reading but take a mental note. There will probably come a time when you need to do this in the future.

To rsync your source/ directory to the remote server's ~/stash/destination/, run:

rsync -a source/ yourUserName@123.456.788.000:~/stash/destination/

If you store a Host inside SSH config, you can also use that. For example, I have a Host named gc (Google Compute). To sync the Projects/ directory, I can run:

rsync -a ~/Projects gc:~

Notice that I don't have a forward slash after Projects even though it is a directory. When you rsync a directory but you don't pass it a slash, rsync will create a directory with the same name as the source. What this does is it creates a ~/Projects/ directory inside my gc Host.

Here are some options that can be helpful when transferring files over the net:

-z to compress data during transfer
-v stands for verbose. This will show the outputs of the file transfer
-P stands for --partial and --progress: partial creates a partial file, in case a transfer is interrupted and progress shows the file transfer progress. This option is useful for large files.

Btw, did you know that you can pass a command when running rsync?

For example, if I want to rsync only test1.txt, test2.txt, ... test9.txt files from the remote server, I can run:

rsync -avz gc:'`find . -name "*test[0-9].txt"`' ~/Projects/source

The trick here is yourRemoteHost:'YOUR_CMD'. Note the backtick surrounding the find command.

Use this when you need to filter for specific files from a remote host instead of having to manually pick-and-choose the files.

Rsync and Cron

Rsync reminds me of file-backup services like Dropbox. When combined with cron, you can create an automated job to automatically sync data every day, hour, etc.

In Mac, I can edit a cron job with the crontab -e command (yours might be different depending on what OS you have).

To create a multiple backups:

00 */1 * * * rsync -a --delete /Users/iggy/source/ /Users/iggy/backup/hourly
00 17 * * * rsync -a --delete /Users/iggy/source/ /Users/iggy/backup/daily
00 18 * * 5 rsync -a --delete  /Users/iggy/source/ /Users/iggy/backup/weekly
00 19 1 * * rsync -a --delete /Users/iggy/source/ /Users/iggy/backup/monthly_$(date +%Y%m)

This performs 4 backups:

an hourly backup
a daily backup every day at 5 PM
a weekly backup every Friday (day 5) at 6PM
a monthly backup on the 1st at 7PM

The first three backups will overwrite the previous backup (it will rsync into the directory with the same name). The monthly backup will have a unique name.

Conclusion

Rsync is a powerful command for creating backups or syncing two directories. If you only need to do a one-time copy, the cp command is probably simpler. But if you need to keep two directories in sync, rsync is a better option.

Rsync and cron are like peanut butter and jelly. Together they let you perform automated backups easily. What other uses of rsync can you think of?

Who knows, maybe in the future you will use rsync to create the next Dropbox rival! When you do, please let me know :).

Until then, happy coding!

Hard Link Vs Symbolic Link 101

Igor Irianto — Wed, 25 Aug 2021 13:03:17 +0000

You probably have heard of "hard link" (ln) and "symbolic link" (ln -s). You may have some vague idea that these commands have something to do with linking a file to another file... or something like that. This article will clarify the differences between ln and ln -s and provide some use cases.

To get the most out of this, I strongly encourage you to code along as you read. Meaningful reading is not passive. It is an active act where you, the reader, must also put in the work to get the most out of this article.

As much as you can, do lots of experiments on your own: try different variations of a command, repeat the command without looking at the article, and repeat it again the next day to fortify your memory (you'll be surprised at how fast you forget things!).

Hard Link

If you have Googled "hard vs soft link" in the past, you might have seen a reference to an "inode". An inode is a file's unique serial number. When you create a new file (touch newfile.txt), you are actually creating an inode and a link to that inode. That file that you just created consists of at least two parts: an inode (a unique identifier) and a file name.

Let's create a file, test1.txt. Inside it, add some texts:

touch 'hello test1' >> test1.txt

Aight, you created a file. Now let's create a hard link - let's call it hard1.txt. Remember - when you create a new hard link, you are creating a new link to the inode of the original file.

ln test1.txt hard1.txt

Now run ls -l. You should see two files displayed: a test1.txt and a hard1.txt. If you run cat hard1.txt, you'll see that it has the same content as test1.txt.

Next, add a line into test1.txt:

echo "Hello again test1" >> test1.txt

You'll see "Hello again test1" inside both test1.txt and hard1.txt. Changing the original file changes the hard link file as well!

What if we change the content of hard1.txt instead? Let's find out!

echo "Hello from hard1" >> hard1.txt

You should see "Hello from hard1" text inside both hard1.txt and text1.txt. So changing either the original or the hard link file changes the other.

Finally, let's see what happens if we delete the original file, test1.txt.

rm test1.txt

Notice that hard1.txt is still there and the text inside hasn't changed. Great!

Let's recap. When you created test1.txt, you created an inode. It contained "hello test1" initially. This inode (I'll call it "test1 inode") is connected to a file name test1.txt. When you ran ln test1.txt hard1.txt, you created a new file name, hard1.txt, connected to the test1 inode. Think of test1 inode like an underground rabbit's burrow. test1.txt and hard1.txt are the two holes connecting that burrow to the surface. From the outside, we see two holes. If you remove one hole, the bunny can still go out from the other hole. If you create a new hard link, you are just creating a third hole to the same, existing burrow. If you delete the test1.txt burrow, it won't affect hard1.txt at all! The only way to remove it is to completely remove all references to the inode. You need to remove all the hard links.

A few things that I'd like you to do:

We've deleted test1.txt but we still have hard1.txt. Create another hard link out of hard1.txt, name it anotherhard1.txt. What do you expect to happen? What does this tell you about the rm command? (It doesn't really "delete" the file. It actually deletes a link to an inode)
Rename hard1.txt to another name, hardy1.txt. What is the relationship between anotherhard1.txt and hardy1.txt?
Modify the content of one of the hard links. What do you think will happen to the content of the rest of the links?
When do you think a hard link might come in handy? What is the use case?
By the way, if you want to see the inode of a file, you can use ls -i hard1.txt. Compare the inode number of a file vs its hard link and the inode number of a file vs its symlink (do this one later after you read the symlink section). You will find that the hard link has the same inode number as the original link and that a symlink has a different inode number as the original link.

Don't go to the next section yet. Spend some time creating your own hard links. Modify them. Do things that weren't covered in this section.

Symbolic / Soft link

Unlike a hard link that points a file to an inode, a symbolic link (sometimes known as a soft link) connects by a file name, not an inode. Because it doesn't connect to an inode like that underground rabbit burrow analogy and it only connects on the surface level, their connection is "softer / weaker" than hard links (that's how I think about it anyway). As a result, by simply changing the name of the original file, you destroy its connection.

Create a new file test2.txt and add a line into it:

echo "hello test2" >> test2.txt

Now create a symlink:

ln -s test2.txt soft2.txt

If you check the content inside test2.txt and soft2.txt, you'll notice that they are one and the same. Good.

Let's update the content:

echo "hello soft2" >> soft2.txt
cat soft2.txt
cat test2.txt

echo "hello original" >> test2.txt
cat soft2.txt
cat test2.txt

Notice that updating either the symlink file or the original file updates the other file. So far symlink acts like a hard link.

Now here comes the kicker. If you either change the name of the original file or remove the original file (rm test2.txt), it will break the connection.

rm test2.txt

cat soft2.txt
cat: soft2.txt: No such file or directory

Retrospectively, if you had renamed the original file:

mv test2.txt somethingelse2.txt

cat soft2.txt
cat: soft2.txt: No such file or directory

However, if you instead had removed the symlink file instead and kept the original file, the content of the original file is preserved.

rm soft2.txt

cat test2.txt
# content is still there

Spend some time to play around with symlinks. Do the things that I didn't mention in this section. Learn by breaking things.

Here are some things to think about:

Can you create a soft link out of a soft link?
What would happen if you move the location of the original file to a different directory (but keep the same name)?
Can you create a soft link out of a hard link?
Can you create a hard link out of a soft link?
Create a symlink and a hard link from a file. Do different things to each. Notice how they differ.

Usage

Now that you know what the differences between ln and ln -s are, let's talk about usage.

One usage for a symbolic link is to create portable dotfiles. I use Vim as a text editor. Vim can be configured with a .vimrc file and a .vim/ directory in the root directory. But what if I want to keep my dotfiles portable and my config files source-of-truth inside ~/Projects/iggy-dotfiles/vimrc and ~/Projects/iggy-dotfiles/vim/?

Before learning about ln, I used to copy-paste the vimrc file and vim/ directory from my dotfiles into the root directory. But if I copy-paste them, anytime I make changes to ~/.vimrc, I would have to apply the same change to my ~/Projects/iggy-dotfiles/vimrc file (I can also use rsync, but that still requires a manual syncing). That's not good. I want to change either ~/.vimrc or ~/Projects/iggy-dotfiles/vimrc and have the other file to update automatically - wait a second... this sounds like symlink!

A better way is to run:

rm ~/.vimrc
ln -s ~/Projects/iggy-dotfiles/vimrc ~/.vimrc

With this, each time I make changes to either dotfiles vimrc or root vimrc, the content will always be the same. Btw, you can also use a symlink on a directory, so ln -s ~/Projects/iggy-dotfiles/vim/ ~/.vim should work.

By the way, you could've also used a hard link, but the popular convention is to use symlink. If I ever need to delete a file, I can just delete ~/Projects/iggy-dotfiles/vimrc and my ~/.vimrc will automatically become obsolete. Having only one source of truth makes it easier to keep track of where things are. If you used a hard link, you'll have to remember to delete all of your vimrc sources.

You can use this technique with any config files like .zshrc, .bashrc, .launch.json, etc.

On the other hand, hard links are useful for backups. For example, if you have a directory full of books:

aesop_fables.pdf
bradbury_fahrenheit.pdf
calvin_institutes.pdf
darwin_origin.pdf
...

Assume that you need to create multiple directories so you can sort them based on author and title. It doesn't make sense to copy all your books into the directory authors/ and once more in title/. It makes more sense if you keep the original books, then create a hard link twice (remember, creating a hard link barely takes up any space). Inside the authors/ directory you can have your books named and sorted by author. Inside the title/ directory you can name and sort them by title. You can "duplicate" and "sort" your data as many ways as you want and they will barely take up any space.

We've reached the end. Thanks for making it this far. Hopefully by now you've understood ln vs ln -s and put this knowledge to good use. Keep learning and happy coding!

Debugging a Rails App in Vim With Vimspector

Igor Irianto — Sat, 14 Aug 2021 15:08:11 +0000

Follow @learnvim for more Vim tips and tricks!

I recently published an article on Vimspector (Debugging in Vim with Vimspector). There I covered different ways to run Vimspector for various Javascript environments. If you're a Rails developer like me, you may ask, "I'm sold on Vimspector, but how can I run it in Rails?"

To be frank, there are not a lot of resources online on how to accomplish this. After tinkering for a few days, I found a few setups that work on a basic Rails application.

I am not claiming that this is the foolproof way to debug any Rails application. There are rooms for improvement and exploration. But for starting out, this is sufficient.

This article assumes that you have had some experience with Vimspector. At minimum, you need to know how to step into, step over, and step out of breakpoints. You also need to know how to launch and restart Vimspector. If you don't, please read my previous article first.

Create a Basic Rails App

I am a huge fan of practical learning. I believe you'll get far more mileage if you actually do the steps as you are reading this article. So for the sake of hands-on approach, let's create a brand new Rails app. Don't worry, it should take less than 5 min.

Create a new Rails app:

rails new hello

Create a controller:

rails generate controller Says hello

Let's go to the controller and write up some codes. Inside ./app/controllers/says_controller.rb, modify the hello action:

class SaysController < ApplicationController
  def hello
    @time = DateTime.now
    @greetings = "Greetings"
  end
end

Modify the hello.html.erb file:

<h1>Says#hello</h1>
<p><%= @greetings %></p>
<p>It is now <%= @time %></p>

Excellent! Let's quickly test if the Rails app is running properly.

rails s

Visit http://localhost:3000/says/hello. You should also see the values of the @greetings and @time instance variables.

Adding Important Gems

Vimspector isn't a debugger. It's a "middle-man" that talks to a debugger. Vimspector provides a standard protocol to communicate with different debuggers. With Vimspector, you can communicate the same way with a Node debugger, Python debugger, Go debugger, etc.

For Vimspector to work with Ruby, you need to install a Ruby debugger. We will use ruby-debug-ide.

In addition, you also need to install debase (source). Add these two in your gemfile (in a real project, you probably want to put them inside the group :development, :test do ... block)

gem 'ruby-debug-ide'
gem 'debase'

Vimspector JSON

Create a .vimspector.json at the Rails project root. Inside it:

{
  "configurations": {
    "rails": {
      "adapter": "cust_vscode-ruby",
      "default": true,
      "configuration": {
          "name": "Debug Rails server",
          "type": "Ruby",
          "request": "launch",
          "cwd": "${workspaceRoot}",
          "pathToBundler": "/Users/iggy/.rbenv/shims/bundle",
          "pathToRDebugIDE": "/Users/iggy/.rbenv/versions/2.6.6/lib/ruby/gems/2.6.0/gems/ruby-debug-ide-0.7.2",
          "program": "${workspaceRoot}/bin/rails",
          "args": [
              "server"
          ]
      }
    }
  }
}

Note that you have to update pathToRDebugIDE and pathToBundler with your own paths. I'll explain below.

Bundler, Debugger, and Adapter

There are three things that you need to provide Vimspector with:

The path to bundler.
The path to the debugger.
Which adapter to use.

To get the path for pathToBundler, run:

which bundler

In my case, it returns /User/iggy/.rbenv/shims/bundle. Use whatever path your machine uses.

Assuming you have installed the ruby-debug-ide gem via your Rails' Gemfile, to get the pathToRDebugIDE path, run:

bundle show ruby-debug-ide

In my case, it returns /Users/iggy/.rbenv/versions/2.6.6/lib/ruby/gems/2.6.0/gems/ruby-debug-ide-0.7.2. Use whatever path you see.

Finally, recall that Vimspector requires a special adapter for each language / environment you use (in my previous article, I installed adapters - also known as "gadgets" - for node and chrome). Since we're debugging a Ruby framework, we need a Ruby adapter.

Adding a Ruby Adapter

If you look at the Vimspector config file above, you'll see:

"adapter": "cust_vscode-ruby",

Unfortunately, Ruby is not in one of the supported languages in the Vimspector page (darn it!). Don't worry, if you dig the Vimspector repo deep enough, you will find instructions on how to "install" a Ruby gadget there.

Here's the page with information for languages not officially mentioned in the README. If you scroll down, you'll find an instruction for Ruby.

Follow the instruction on the introduction section

Inside the Vimspector directory (in my case, it is in ~/.vim/plugged/vimspector/gadgets/custom/cust_vscode-ruby.json - yours could be in a different directory depending on what plugin manager you use), add a custom json file for your language.
Run ./install_gadget.py --upgrade. Vimspector should install some files from vscode-ruby.

Phew! We are done with the preliminary setup.

If you're still curious what just happened, here are a few pages to read:

Program and Args

Let's take another look at a section inside the Vimspector config file:

"program": "${workspaceRoot}/bin/rails",
"args": [
  "server"
]

Recall from the previous article, program is the program that Vimspector will run when you tell it to launch something and args is the argument that gets passed to program.

When running a rails app, you would (usually) run bin/rails server. The config does exactly that.

Running the Vimspector

Now we are ready to run Vimspector. Our config is set to launch, so do not run rails s from the terminal. We will run it from the debugger.

Go to the says_controller.rb and add a breakpoint on @time:

class SaysController < ApplicationController
  def hello
    @time = DateTime.now # add a breakpoint here
    @greetings = "Greetings"
  end
end

Excellent. Now here comes the moment of truth - let's launch Vimspector!

Wait a few seconds, you should see on the Console window that Vimspector is launching a Rails app.

Now, visit http://localhost:3000/says/hello. The app should pause.

Check your Vimspector. You should see it paused at the breakpoint.

If this is what you see, congratulations! You've successfully launched a Rails debugger - from Vim!

From there, you can step into, step over, and step out of different lines of code.

Attach Vs Launch

There are two ways you can run Vimspector: attach and launch. The former attaches the debugger into an already running process. The latter launches a process from the debugger.

The Rails example above is an example of launch, as it launches a Rails process directly from the debugger. Theoretically, you should be able to perform either attach or launch.

Attaching a Debugger to a Rails Server

You've seen how to launch a Rails app from Vimspector. Let's see how you can attach Vimspector to a Rails process.

First, modify our .vimspector.json file:

{
  "configurations": {
    "rails": {
      "adapter": "cust_vscode-ruby",
      "default": true,
      "configuration": {
          "name": "Debug Rails server",
          "type": "Ruby",
          "request": "attach",
          "cwd": "${workspaceRoot}",
          "remoteHost": "0.0.0.0",
          "remotePort": "1234",
          "pathToBundler": "/Users/iggy/.rbenv/shims/bundle",
          "pathToRDebugIDE": "/Users/iggy/.rbenv/versions/2.6.6/lib/ruby/gems/2.6.0/gems/ruby-debug-ide-0.7.2"
      }
    }
  }
}

Here are the changes:

request is now attach.
We added remoteHost and remotePort.
We removed "programs" and "args" (they are unnecessary for attach).

The remoteHost and remotePort are the IP address and port number that we will be running the debugger on. The host is set to 0.0.0.0 and the port is set to 1234. These numbers will make sense in a little bit.

Once your vimspector.json file is configured, let's run the app. Instead of running the regular bin/rails s, run:

rdebug-ide --host 0.0.0.0 --port 1234 --dispatcher-port 1234 -- bin/rails s

This will launch the ruby-debug-ide program installed earlier. Note the host and port numbers: we are running the debugger on host 0.0.0.0 and port 1234 in addition to running the rails server.

Next, add the breakpoints inside the says_controller.rb file, then launch Vimspector. Since we are running Vimspector on attach mode, it won't launch a Rails server this time. Head to the page related to this controller: http://localhost:3000/says/hello. Watch your Vimspector pauses at the breakpoint(s).

Sweet chocolate pancake! Super cool, isn't it? Well, this also concludes this article.

Conclusion

Congratulations! You've successfully debugged a Rails app. You are one step closer from becoming a supreme master developer.

There is still much to explore about Vimspector and Rails applications. There are different settings, environments, and configs that I don't mention in this article. Experiment. Share this article. Let me know how you do things differently.

In the end, I hope that this article has given you a good place to start. Happy Vimming!

Reducing a Screenshot Size in Mac

Igor Irianto — Wed, 11 Aug 2021 13:46:09 +0000

Motivation

I have a retina 15-inch Macbook (2016, used 🙂). Whenever I take a screenshot, it usually captures a PNG with 2-4MB in size.

Although storage is getting cheaper nowadays, for its purpose, having 2-4MB screenshots are, in my opinion, still overkill. It could be smaller. Especially if you are using these screenshots in an online storage (they cost $$!). If I can shrink a 2MB image by 90%, I can store ten times as many images!

In this article, I’ll share simple tips / tricks to reduce the size of my screenshot images. Even if you don’t use Mac, this article should largely be relevant to you - so keep reading!

ImageMagick

The main ingredient to accomplish this is a tool called ImageMagick

The quickest way to install is to use homebrew:

brew install imagemagick

If you have a Windows or a Linux machine, or if you have Mac but want to download it outside of Homebrew, check out the ImageMagick's download page!

Converting Image With ImageMagick

ImageMagick has a long list of APIs. When you have the time, I strongly encourage you to read what else it can do.

By default, Macbook a full-screen screenshot has a size of roughly 2000 x 3000 px. Usually, half of that size is sufficient.

To reduce an image size, we can use ImageMagick's convert command. To convert an image by 50%, run:

convert MY-SCREENSHOT.png -resize 50% MY-RESIZED-SCREENSHOT.png

The -resize 50% option will resize the input image by 50%.

Try it! Take a screenshot of the current window with Cmd + Shift + 4 then press Space. Click on the window that you want to take a screenshot on. In my case, the resulting screenshot is 2.1MB and has a dimension of 3548 x 2030. That's big!

Running the convert command above reduces the dimension to 1792 x 1015. The file size is also reduced down to about 430KB. That's a 80% reduction for a short one-line command!

Some of you may think 50% is too small - if that's the case, feel free to play around with the resize option. A good place to start is ImageMagick's resize documentation: Resize or Scaling (General Techniques).

PNGQuant

Reducing an image from 2MB to 400KB is already a significant improvement. However, we can do more. We can do a lossy compression of our image. This is a job for PNGQuant.

Although ImageMagick also performs an image compression, I prefer to use PNGQuant because it has a cleaner API and produces a better output than ImageMagick (disclaimer: I actually haven't spent that much time with ImageMagick's compression tools - take my word with a heavy grain of salt and experiment around with ImageMagick compression tools yourself!)

You can download PNGQuant with homebrew:

brew install pngquant

Compressing with PNGQuant

By default, the screenshots taken by my Mac are PNG files, so it works right out of the box.

To compress an image, run:

pngquant MY-IMAGE.png

I prefer to add a few extra safeties, so my preferred command is:

pngquant --skip-if-larger --force --ext=.png MY-IMAGE.png

The option --skip-if-larger skips the image compression process if the resulting image is larger than the input image. I personally always run PNGQuant with this option.
The --ext=.png creates an image whose extension is a png. By default, PNGQuant creates an output file name ending with -fs8.png. This option prevents that.
The --force works in conjunction with --ext.
- Without force, the command above will complain that the file name already exists.
- With force, pngquant will overwrite the image with the compressed version.

The --force --ext=.png command technically mutates the image. If you prefer to keep the original copy of the image, just remove the --force --ext=.png options.

You can either run the PNGQuant command by itself against a freshly captured screenshot or against a resized screenshot. If you choose to run both the ImageMagick and PNGQuant commands together, run the ImageMagick command first. If you run the PNGQuant first followed by the ImageMagick command, you may end up with a less compressed image.

Putting Them Together and Creating a Bash Command

Inside my .bashrc / .zshrc / whatever, I created this mini utility function:

minimg() {
  echo "Resizing $1"
  convert $1 -resize 50% $1
  pngquant --skip-if-larger --force --ext=.png $1
  echo "Done!"
}

Don't forget to save and source the file. With this, I can just run this to resize the image and compress it:

minimg MY-IMAGE.png

On average, this reduces a screenshot image from 2MB to roughly 150KB, a 92.5% reduction. Not bad!

Extra: taking screenshot and resizing the image

If you prefer to run everything from the terminal, you can modify the function to include the screencapture command:

screencap() {
  echo "Screencapturing.."
  screenshot=$(which screencapture)
  $screenshot -i $1
  if test -f "$1"; then
    echo "Resizing $1"
    convert $1 -resize 50% $1
    pngquant --skip-if-larger --force --ext=.png $1
    echo "Done!"
  fi
}

The screencapture command above is equivalent to Mac's Cmd + Shift + 4.

For example, to take a screencapture from CLI:

screencapture -i say-cheese.png

After running this command, notice that your cursor turns into a screencapture crosshair (if you press Space in this mode, it turns into a window screen capture). With this function, you can take a screenshot, resize it, then compress it.

Conclusion

That's it. That’s how I resize my screenshots. I hope you're now able to take much lower resolution screenshots and make a better use of your local / cloud storage. More importantly, now that you have smaller screenshots, they will be easier to transport around. Plus you get to learn a little bit about image modification. I think it's a win-win.

Debugging in Vim with Vimspector

Igor Irianto — Sat, 07 Aug 2021 13:57:58 +0000

Follow @learnvim for more Vim tips and tricks!

Debugging in Vim with Vimspector

Vimspector is a powerful graphical debugger plugin for Vim. However, it also will take you a while to get started. In this article, I will show you how to use Vimspector to debug:

A Node file.
Client-side app using Chrome.
Jest testing.
An Express app.

Both their Github page and their website are very comprehensive. I would suggest you read them when you have the chance!

Much content found in this article can be found inside the Vimspector websites. However, when I was reading them, I was overwhelmed by the sheer amount of the information. This article serves as a bridge to get you started as early as possible. I think it is beneficial to get our hands dirty early-on. Once you start using it, reading the docs becomes clearer. Although I am using the Javascript ecosystem as examples (backend, frontend, testing), you should be able to apply the same concept to any language of your choice.

Requirements

At the time of this writing, I am using Vim 8.2 on MacOS Catalina. This guide should work with any OS (with appropriate modifications). The Vimspector Github page though, recommends you to have either Vim 8.2 or NeoVim 0.4.3. You also need to have Python 3.6 or up.

Quick Overview

So what is Vimspector? How does it work?

Vimspector is not a universal language debugger. It technically does not handle the debugging. Think of it like a middle-man that facilitates communicating with the debugger for your language-of-choice. It relies on specific gadgets depending on what language you are working with. So if you want to debug a node application, use the vscode-node-debug2 gadget. If you want to debug a go app, use vscode-go gadget. If you want to debug a client-side JS app, use debugger-for-chrome gadget.

Different languages have different debuggers. Some have built-in debuggers while some use external libraries for debugging. If we want to integrate multiple languages into our favorite editors / IDEs, it could get messy. A Python debugger communicates differently from a Node debugger. A Node debugger behaves differently from a front-end JS debugger via Chrome. If you're a Ruby / Javascript developer, you could technically have a Ruby and Node debuggers installed in your editor / IDE. But these two debuggers probably have different protocols and exhibit different behaviors. The more languages / environments you deal with, the more the complexity increases.

So having different language environments to debug can get messy. To reconcile these differences, we need to bridge the gap between language X debugger and our editor / IDE - we need an abstract protocol. This protocol is known as Debug Adapter Protocol (DAP). DAP was originally created by the VSCode team. But luckily for us, they decided to make it (somewhat) editor agnostic, so developers can use it for other editors / IDEs. Vimspector is the result of DAP development for the Vim editor. For a list of tools that support DAP, check out this page: Tools Supporting the DAP.

Although not required readings, but when you have the time, I would strongly recommend you to look into these pages to get a better understanding on DAP:

Well, enough theory - let's get started with an actual example!

Getting started

To get started, install Vimspector if you haven't. Follow the Vimspector installation guide.

For me, I used vim-plug. All I did was add the following in my vimrc's list of plugins:

Plug 'puremourning/vimspector'

I then sourced my vimrc and ran :PlugInstall.

Examples

The fastest way to learn a new skill is to jump into it and learn it along the way. You may have a lot of questions right now, but once you see how it works, by the end of this article, I hope that some of your questions will be answered.

Let's go through the node example.

Debugging a node app

The Vimspector plugin itself already comes with examples. Go to the directory where Vim saves your Vimspector plugin. I am using vim-plugged, so my plugins are installed inside the plugged/ directory. In my case, the directory is in ~/.vim/plugged/vimspector/. Yours might be in a different location, depending on your plugin manager and your system. Once you find them, from the vimspector/ directory, go to the /support/test/ directory. Inside this directory, you will find different examples that I also strongly encourage you to check out once you're done reading this article.

Since this section is about debugging a node app, let's check out the node directory.

cd node/

Inside, at the time of this writing, you should find a directory named simple/. Go there and you'll see a simple.js file.

Before we debug this file, there are at least two requirements to debug with Vimspector:

A relevant gadget.
A Vimspector config file.

A gadget is a debug adapter (like the ones listed in Microsoft's Debug Adapters page). Since we are debugging a node app, we need a node adapter. This node adapter will relay messages between NodeJS and the abstract protocol DAP.

(By the way, before installing the node adapter, per Vimspector's site, you need to be using a Node version between 6 and 12).

For the first requirement, to install a node adapter, from Vim, run :VimspectorInstall vscode-node-debug2.You need a different gadget when you are debugging a different language/environment. If you need to debug a Python file, you have to install a python gadget. If you are debugging a Go file, you have to install a Go gadget. Since we are debugging a node app, we need to install a node gadget. For a list of gadgets, check out this section from the Vimspector Github page: Supported Languages.

For the second requirement, the .vimspector.json file is conveniently already located at the root of the project (inside simple/). If you check the hidden files of the vimspector/support/test/simple/ directory, there should already be one .vimspector.json file available, so you don't need to do anything. Keep in mind that when you are inspecting your own project, remember to create your own vimspector file.

With those two requirements in place, let's debug.

Vimspector offers many commands and shortcuts. Using them all when you're starting can be overwhelming. I found that the following are sufficient to get started with. Below are some of my vimrc vimspector shortcuts:

nnoremap <Leader>dd :call vimspector#Launch()<CR>
nnoremap <Leader>de :call vimspector#Reset()<CR>
nnoremap <Leader>dc :call vimspector#Continue()<CR>

nnoremap <Leader>dt :call vimspector#ToggleBreakpoint()<CR>
nnoremap <Leader>dT :call vimspector#ClearBreakpoints()<CR>

nmap <Leader>dk <Plug>VimspectorRestart
nmap <Leader>dh <Plug>VimspectorStepOut
nmap <Leader>dl <Plug>VimspectorStepInto
nmap <Leader>dj <Plug>VimspectorStepOver

Feel free to steal what I have or make your own. Vimspector also comes with a set of shortcuts called the human-mode mapping. If you're used to VSCode debugging shortcut, you may feel more at home with them.

Finally, let's open simple.js. It should look something like this:

var msg = 'Hello, world!'

var obj = {
  test: 'testing',
  toast: function() {
    return 'toasty' + this.test;
  }
}

console.log( "OK stuff happened " + obj.toast() )

To launch vimspector, run the launch command. Press <Leader>dd (:call vimspector#Launch()). You should see a Vimspector window. Pretty cool!

There should be 6 different windows displayed - depending on your Vim orientation, you may see them in different order. If you have never used a debugger before, don't feel intimidated. You'll get used to some of them after playing with them for a while. To exit Vimspector, press <Leader>de (:call vimspector#Reset()).

By the way, there will be some prompts on the bottom of the windows when you launch vimspector, asking for something like ...Break on Uncaught Exceptions?. I usually pressed N. If you don't want to get prompted all the time, add these in your vimspector.json file inside the "run": { ... block:

  ...
  "breakpoints": {
    "exception": {
      "all": "N",
      "uncaught": "N"
    }
  },
  ...

My full vimspector json (so you can just copy paste it) for this file looks like this:

{
  "configurations": {
    "run": {
      "adapter": "vscode-node",
      "breakpoints": {
        "exception": {
          "all": "N",
          "uncaught": "N"
        }
      },
      "configuration": {
        "request": "launch",
        "protocol": "auto",
        "stopOnEntry": true,
        "console": "integratedTerminal",
        "program": "${workspaceRoot}/simple.js",
        "cwd": "${workspaceRoot}"
      }
    }
  }
}

Back to the debugging, start the vimspector again (<Leader>dd). Since we have stepOnEntry to be true in the Vimspector json file, Vimspector will stop on the first line even though you haven't marked a breakpoint.

To traverse through the file, you can either:

Step out (steps out of the scope)
Step into (steps into the function scope)
Step over (steps to the next line, in scope)

Here are the key maps that I use. Note that I use hlj keys similar to the Vim movement keys.

nmap <Leader>dh <Plug>VimspectorStepOut
nmap <Leader>dl <Plug>VimspectorStepInto
nmap <Leader>dj <Plug>VimspectorStepOver

If you are not sure what stepping out, stepping into, and stepping over are, I found these short video tutorials very helpful:

Back to our debugging - now that we are on the first line of the code, press <Leader>dj (<Plug>VimspectorStepOver). Note the highlight moves to the variable declaration. If you press <Leader>dj one more time, it will move down again. If you keep stepping over, eventually you will reach the end of simple.js file. Unfortunately, you can't step "back" to the previous line. Once you're on the next step, you continue forward until you reach the end.

If you accidentally step over an important line, just restart the debugger. To restart, run <Leader>dk (<Plug>VimspectorRestart). When you restart, Vimspector starts over from the beginning. Alternatively, you could also Reset and Launch Vimspector again.

You can put breakpoints throughout the file. Back in the main simple.js file, run <Leader>dt (:call vimspector#ToggleBreakpoint()) on the line where you want to add a breakpoint (run that command again on the line with the breakpoint to remove it).

Once you sprinkle breakpoints all over your file, launch Vimspector again. If you press <Leader>dc (:call vimspector#Continue()), Vimspector will jump to the next breakpoint. Pretty cool!

To clear the breakpoints, run <Leader>dT (:call vimspector#ClearBreakpoints()).

Before moving on to the next section, spend 10-15 minutes experimenting with simple.js. Change the codes in simple.js. Move around. Play.

Before we move on to the next section, let's briefly go over what the 6 Vimspector windows do.

Variables window

The Variables window contains the available variables (and their current values) relative to their current scope.

- Scope: Local
  + this (Object): Object
  - __dirname (string): "/Users/iggy/.vim/plugged/vimspector/support/test/node/simple"
  - __filename (string): "/Users/iggy/.vim/plugged/vimspector/support/test/node/simple/simple.js"
  + exports (Object): Object {}
  + module (Object): Module {id: ".", path: "/Users/iggy/.vim/plugged/vimspector/support/test/n…", exports: Object, …}
 *- msg (undefined): undefined
 *- obj (undefined): undefined
  + require (Function): function require(path) { … }
+ Scope: Global

In the above example, inside the Local scope, I have common Node variables like this, __dirname, __filename and the written variables msg and obj. Pay attention as you step over to the next variable. Watch them go from undefined to having a value.

Do this: step over and into different function scopes. Find a way to get inside a function and see what the available variables are. Then step outside and compare them. Also check what is inside Scope: Global. Why does it have the variables it has? What does it tell you about Node?

Watch Window

The Watch window is where you can watch for specific values. Initially it will be blank. If you want to watch the value of the msg variable, type into the Watch window that variable, msg. When you're at the start of the file, the value will be undefined. Then as you steps over, the value will change into 'Hello, world!'.

Stack Trace window

The Stack Trace window displays the call stack of the node file execution.

Console window

In the Console window, you can enter the defined variables like msg. You can also evaluate expressions.

Terminal window

The Terminal window displays all the outputs throughout the entire debugging session.

Debugging in a Browser

Let's explore how to use the Chrome-debugger to debug a client-side app. Lucky for us, there is also an example in the Vimspector directory. Inside ~/.vim/plugged/vimspector/support/test/chrome/ directory, you will find a file named run_server, a test.js, and a .vimspector.json.

Let's check out what is inside the vimspector config file:

{
  "configurations": {
    "launch": {
      "adapter": "chrome",
      "configuration": {
        "request": "launch",
        "url": "http://localhost:1234/",
        "webRoot": "${workspaceRoot}/www"
      }
    }
  }
}

This configuration sure looks different from the Node Vimspector config one we saw earlier. One important line is "adapter": "chrome" - it indicates that we will be using a Chrome adapter. The URL is defined to be on localhost:1234 because that's the port where our server will be running on.

Btw, when you launch Vimspector later, it will prompt if you want to break on uncaught exceptions etc again. If you don't want to deal with those prompts, add these lines inside the .vimspector.json just like you added it to your Node app earlier.

"breakpoints": {
  "exception": {
    "all": "N",
    "uncaught": "N"
  }
},

We need to install the correct gadget. In the earlier section, we installed one with :VimspectorInstall vscode-node-debug2. This time we have to install one for chrome. Run this from Vim:

:VimspectorInstall debugger-for-chrome

Once done, run the server (make sure you have PHP installed):

./run_server

Check out localhost:1234. You should see a simple app with some pop-out modals.

Now open www/js/test.js. Add breakpoints anywhere you like. Run the Vimspector launch command <Leader>dd. By running it, it will automatically launch the Chrome browser. Vimspector will pause the Chrome browser where your breakpoints are. Step over and step into your breakpoints. Watch some variables. Change the code. Play around!

Note: check out the Variables window. Check out both the Local and Global scope. Did you see anything different in the Global scope compared to when you're debugging with Node? What does this tell you about client-side vs backend code execution?

Note 2: notice how this time, when you launch Vimspector, it launches a Chrome browser. If you look at the .vimspector.json, you'll see a "request": "launch", instead of "request": "attach", from earlier Node debugging. How are they different? There are two ways you can debug an app: by attaching it to an already running process or by launching a new process.

Debugging a Jest test

Now let's learn how to debug a Jest test. For this section, I will be using the vscode-recipes repository. First go to the site and clone the repository. Then go to the debugging-jest-tests/ directory. You will find two directories: lib/ and a test/. This is our workspace root directory.

First, install the dependencies: npm i.

Make sure that the Jest test is running and they are all passing: npm run test.

Debugging a Jest test requires a node debugger. If you've been typing along, you should already have the Node debugger from earlier. With Vimspector, you install your gadget only once (Vimspector saves all the installed gadgets inside the Vimspector directory - in my case, they are stored inside ~/.vim/plugged/vimspector/).

Inside the debugging-jest-tests/ directory, add a .vimspector.json file. Inside it:

  "configurations": {
    "my awesome jest test": {
      "adapter": "vscode-node",
      "breakpoints": {
        "exception": {
          "all": "N",
          "uncaught": "N"
        }
      },
      "configuration": {
        "request": "launch",
        "name": "Jest debugger",
        "type": "node",
        "console": "integratedTerminal",
        "program": "${workspaceRoot}/node_modules/.bin/jest",
        "skipFiles": ["*/<node_internals>/**/*.js", "node_modules/**/*.js"],
        "cwd": "${workspaceRoot}"
      }
    }
  }
}

The configuration looks familiar, with a new addition of: "program": "${workspaceRoot}/node_modules/.bin/jest". Here's the breakdown:

The workspaceRoot is the current directory (the debugging-jest-tests/ directory).
The node_modules/.bin/jest is the Jest executable from the node_modules/ (which you should have after npm i).

This time when you run the debugger, Vimspector needs to run the Jest executable. One place where you can find a Jest executable is inside the node_modules/ directory. You could've also run it from the global Jest command, but I like to keep it compartmentalized (what if I am running this from a container and I'm not guaranteed to have a global Jest command? By using the .bin/jest command, I'm guaranteed to have it - but that's just my personal preference).

Cool! Let's put some breakpoints inside the test files, then launch the Vimspector (<Leader>dd). Voila! Your test suite will pause and you can now debug your code.

If you put your breakpoint on the line where it calls the function, like the function add() below:

...
it('Should return correct result', () => {
  const result = add(1, 2); // put a breakpoint here
  expect(result).toEqual(3);
});
...

When you step into it (<Leader>dl), it will go into the original function declaration inside lib/calc.js, allowing you to investigate the source code. How awesome is that!? With this, you can debug a faulty test down to where the function originated!

There is one problem. With the current Vimspector config, it will run all the tests when you launch it. That's great but in real life, your app probably has hundreds of tests (if you've been practicing TDD... wink wink). Running all tests are probably not the best way to live your life. What if you want to run one particular test at a time?

You sure can!

In Jest, you can run a specific file by passing that file name (or part of the name) as an argument. If you want to run only the add.spec.js, you can run the command jest add. Jest is smart enough to match the add.spec.js and not the subtract.spec.js.

If you want to match a particular test in a file, Jest is also smart enough to match any keyword you pass using the -t option.

Suppose that inside the add.spec.js I have two tests (notice that I modified the test descriptions):

const { add } = require('../lib/calc');

describe('When adding numbers', () => {
  it('one should return correct result', () => {
    const result = add(1, 2);
    expect(result).toEqual(3);
  });

  it('two should not return correct result', () => {
    const result = add(1, 5);
    expect(result).not.toEqual(3);
  });
});

I want to run only the second test. To do that, from the CLI I can run test add -t two. Jest is smart enough to run only add.spec.js and only the 'two should not return correct result' test! Try it.

Armed with that knowledge, we need to pass these arguments when running Vimspector. Turns out that Vimspector has the args attribute where you can pass argument(s) to your program.

{
  "configurations": {
    "jest": {
      "adapter": "vscode-node",
      "breakpoints": {
        "exception": {
          "all": "N",
          "uncaught": "N"
        }
      },
      "configuration": {
        "request": "launch",
        "name": "Jest debugger",
        "type": "node",
        "console": "integratedTerminal",
        "program": "${workspaceRoot}/node_modules/.bin/jest",
        "skipFiles": ["*/<node_internals>/**/*.js", "node_modules/**/*.js"],
        "cwd": "${workspaceRoot}",
        "args": [
                "${FileName}",
                "-t",
                "${TestName}"
            ]
      }
    }
  }
}

Our new attribute, args, is an array with 3 elements. The funny looking variables (${FileName} and ${TestName}) are the Vimspector's named arguments. With this I can pass the FileName and TestName variables when launching Vimspector.

Let's launch Vimspector again. This time it will prompt: "Enter value for FileName" (in which you'll enter "add"). After that, the Vimspector will prompt: "Enter value for TestName" (in which you'll enter "two"). And watch it runs only that particular test from that particular file. Success!!

Now you have no excuse not to practice TDD! :D

Debugging an Express App

For the next example, let's try to debug a simple Express app. Since express is a node library, a node gadget is required.

Create a directory (mkdir express-debug) and go in there. Run npm init -y to initialize an NPM project. Install express (npm i express). Then create an app.js. Inside it:

const express = require('express');
const app = express();
const port = 3000;

const helloFunc = () => {
  const hello = 'hello';
  return hello;
};

app.get('/', (req, res) => {
  const msg = helloFunc();
  res.send(msg);
});

app.listen(port, () => {
  console.log(`Example app listening on port ${port}!`)
});

Create a .vimspector.json in that directory. At minimum you should have:

{
  "configurations": {
    "run": {
      "adapter": "vscode-node",
      "default": true,
      "configuration": {
        "type": "node",
        "request": "attach",
        "processId": "${processId}"
      }
    }
  }
}

However, it's probably better if we enable some default configs:

{
  "configurations": {
    "run": {
      "adapter": "vscode-node",
      "default": true,
      "breakpoints": {
        "exception": {
          "all": "N",
          "uncaught": "N"
        }
      },
      "configuration": {
        "name": "Attaching to a process ID",
        "type": "node",
        "request": "attach",
        "skipFiles": ["node_modules/**/*.js", "<node_internals>/**/*.js"],
        "processId": "${processId}"
      }
    }
  }
}

Then run the express app in inspect mode:

node --inspect app.js

You should see your app running on localhost:3000. Next, add a few breakpoints inside app.js, then launch Vimspector (it will also ask for processId, but I find that not giving it any value and simply pressing the Return/Enter key works).

Finally, refresh the page and you should see the debugger pauses at your first breakpoint. From there, you can step out, step into, and step over your code.

Congratulations! You've successfully debugged an express app.

What's next?

This article barely scratched the surface of what a debugger can do. There are many more things that you can do with Vimspector. Hopefully by approaching it from different angles, you'll gain a more thorough understanding of this plugin.

Your debugging needs probably differ from the examples I gave in this article, but I am a sincere believer that if you understand the principles behind it, you should be able to implement Vimspector to meet your needs.

With that, thanks for reading this far. Happy Vimming!

Executing a Command in Multiple Files in Vim

Igor Irianto — Thu, 03 Jun 2021 15:15:28 +0000

Executing a Command in Multiple Files in Vim

When editing, you may need to execute a command across multiple files. For example, replacing all let with const.

There are eight different ways you can do this in Vim.

:argdo    argument list (files)
:bufdo    buffers
:windo    windows in the current tab
:tabdo    tabs
:cdo      each item in the quickfix list
:cfdo     each file in the quickfix list
:ldo      each item in the location list
:lfdo     each file in the location list

Eight sounds like a lot of methods learn at once. However, the principle behind all of them is the same: make a list of what you want to change, then run the command to the entire member of that group, then save. The only difference is the scope of each entry.

Let's go over two of them here. Once you get a feeling how it works, using any of the methods above is just a matter of syntactical differences.

Argument List

The argument list (argdo) uses file as the scope. To create an argument list consisting of file1.txt, file2.txt, and file3.txt, run :args file1.txt file2.txt file3.txt (you can also use the blob operator: run :args *txt to collect all txt files in the current directory, run :args **txt to collect all txt files recursively, run :args z*txt to collect all txt files in the current directory that starts with "z").

To check that you have the correct files, run :args. On the bottom screen, you should see something like [file1.txt] file2.txt file3.txt, indicating that you are currently on file1.txt. You can move around the argument list with :next, :prev, :first, :last, etc. Make sure that you are on the first entry before running the command.

Now run :argdo %s/kale/pancake/g | update. That's it. All kales inside file1.txt, file2.txt, and file3.txt are now substituted with pancakes. Sweet!

Command breakdown:

:argdo performs the given command on all entry in the argument list.
:%s/kale/pancake/g is the substitute command.
| lets you to chain multiple commands together.
update saves each file.

Quickfix List

Next, let's go over the quickfix list. If you not familiar, quickfix is Vim's special mode originally created to handle edit-compile-edit cycle error messages, but eventually evolved and used for all sorts of other things from displaying STDOUT when running async operations in vim-dispatch, fuzzy searching in fzf.vim, etc. For our purpose, think of it as a list of pointers to various location in your files.

Some commands in Vim automatically uses quickfix, like :make, :grep, and :vimgrep.

If you need to list all occurrences of "veggies" inside any text file, run :vimgrep /veggies/ **txt. To see the quickfix matches, run :copen (quickfix open). To apply the substitute command to all quickfix matches, run :cfdo %s/kale/pancake/g | update. That's it. It follows a similar pattern like the argument list: collect-apply-save.

You can move around in a quickfix list with :cfirst, :clast, :cnext, :cprev, etc.

If you notice, on the list above you'll see cfdo and cdo quickfix operations. What's the difference? The difference is that cfdo is a per-file operator and cdo is a per-match operator. cfdo will run the command once per file and cdo will run the command once per match.

If you have 5 matches for "veggies" inside file1.txt, running :cfdo %s/kale/pancake/g will run the command once while running :cdo %s/kale/pancake/g will run the command 5 times.

Since we are running a file-wide command (%s), it makes sense to run it only once per file.

Conclusion

Vim's multi-file operations are useful to apply a change across multiple files. There are eight different ways to accomplish this, although the underlying principle is the same: collect-apply-save. Play around with the args / argdo and vimgrep / cfdo combos. Once you get comfortable with them, play around with the other commands.

Happy Vimming!

Shameless disclaimer: if you enjoy this, there's a 98.39% (not scientifically proven) you will also enjoy my Vim Cookbook: Gourmet Vim. Check it out!

DEV Community: Igor Irianto

Vim Global Command

What Commands Can I Run With the Global Command?

CMD: Delete

CMD: Substitute

CMD: Normal

CMD: Put

CMD: Print

CMD: Move

CMD: Copy

Range in The Global Command

Address Range

Pattern Range

CMD: Sort

Conclusion

Learning Vim Regex

Learning Vim Regex

Using Regex in Vim

To Magic or Not

The Good Parts of Vim Regex

Basic Search /

Any Character .

The Character Class

Character Class []

Negated Char Class [^]

Special Characters

Quantifiers

Min/Max

Exact Match {n}

Min Max Match {n,m}

Min Match {n,}

Max Match {,m}

Zero or More Match {}

Zero or More *

One or More +

Zero or One ?

Greedy Vs Lazy

Greedy

Lazy

Anchors

Beginning of line ^

End of Line $

Word Boundaries < >

Or |

Groups

Capture Group (Sub-Expression) ( )

Backreferences \n

Whole Match \0

Non-Capture Group %( )

Atoms

Zero-Width

Look-Arounds

Look-Aheads

Look-Behinds

Look-Ahead and Look-Behind

Negative Look-Aheads

Negative Look-Behinds

More Vim regex

Optional Match \%[ ]

Multiple Lines \_x

Start and End of File \%^ \%$

Start Within Visual Area \%V

Magic and Very Magic \v \m

Conclusion

Vimgrep Tips and Tricks

Why Learn Vimgrep

Basic Usage

Searching for a String Inside a Particular File

Searching for a String Inside a Particular File Extension

Searching for a String Inside Files Ending With Particular Extensions

Passing Multiple Files to Search Inside of

Finding Multiple Matches in the Same Line

Fuzzy Search a String Inside a Particular File

Search a Regular Expression Pattern in a Particular File

Search for a String Inside a Particular Directory

Search for a String Inside a Different Directory Than Your Current Working Directory

Search in the Current File

Using Other Search Commands

Searching in-Files Within Arglist

Quickly Get the Last Search Pattern

Basic Search `/`

Any Character `.`

Character Class `[]`

Negated Char Class `[^]`

Exact Match `{n}`

Min Max Match `{n,m}`

Min Match `{n,}`

Max Match `{,m}`

Zero or More Match `{}`

Zero or More `*`

One or More `+`

Zero or One `?`

Beginning of line `^`

End of Line `$`

Word Boundaries `< >`

Or `|`

Capture Group (Sub-Expression) `( )`

Backreferences `\n`

Whole Match `\0`

Non-Capture Group `%( )`

Optional Match `\%[ ]`

Multiple Lines `\_x`

Start and End of File `\%^ \%$`

Start Within Visual Area `\%V`

Magic and Very Magic `\v \m`