Learn Neovim - Autocommands, Filetype Detection & Custom Commands

#Introduction

After building options.lua and keymaps.lua in episode 7 — the first two pillars of a Neovim config — you now have an editor that feels comfortable and shortcuts that are responsive. But notice one thing: everything we have built so far waits for your commands. You press the keys, you run the commands. Not a single behavior runs on its own.

In the real world, developers do not work like that. We want the editor to react to what happens: tidy up automatically when saving a file, remove trailing whitespace without being asked, restore the cursor position when reopening the same file, and expose custom commands that save repetitive steps. This is the topic of this episode — making Neovim work for you, not just with you.

Technically, we will master three complementary mechanisms:

1. Autocommands (vim.api.nvim_create_autocmd) — execute code when an event occurs in the editor.
2. Custom User Commands (vim.api.nvim_create_user_command) — create new commands in the :Name style callable from the command-line.
3. Filetype Detection & Modeline — make Neovim adapt its behavior automatically based on the type of file being opened.

All three are "reactive programming" at editor scale: a living system that changes behavior based on context. As a DevOps/SRE, you are surely familiar with similar patterns — event-driven automation in Kubernetes (webhooks, controllers), CI/CD triggers, or monitoring that responds to metrics. Autocommands are how Neovim realizes the same pattern.

#Autocommands: Responding to Editor Events

#Basic Concepts

An autocommand works like a webhook: Neovim emits certain events during its lifecycle, and you register handlers that run when those events occur. The modern syntax is vim.api.nvim_create_autocmd(events, opts).

vim.api.nvim_create_autocmd(events, {
  pattern = "*",        -- pola buffer yang dipantau (bisa "*.go")
  callback = function() -- handler yang dijalankan
    -- kode Lua di sini
  end,
  group = augroup,      -- wadah untuk mencegah duplikasi (lihat bawah)
  once = false,         -- true = hanya dijalankan sekali
  desc = "Keterangan",
})

The events most often used in production configs:

#Building lua/config/autocmds.lua

Here is a complete file containing the three most useful autocommands for daily use:

-- 1. Buat augroup unik untuk config kita.
--    clear = true menjamin handler tidak terdaftar dua kali.
local augroup = vim.api.nvim_create_augroup("UserConfig", { clear = true })
 
-- 2. Hapus trailing whitespace otomatis setiap kali menyimpan.
vim.api.nvim_create_autocmd("BufWritePre", {
  group = augroup,
  pattern = "*",
  callback = function()
    local save = vim.fn.winsaveview()       -- simpan posisi kursor & folds
    vim.cmd([[%s/\s\+$//e]])                -- hapus spasi di akhir baris
    vim.fn.winrestview(save)                -- pulihkan posisi kursor
  end,
  desc = "Hapus trailing whitespace saat menyimpan",
})
 
-- 3. Sorot sementara teks yang baru disalin (yank).
vim.api.nvim_create_autocmd("TextYankPost", {
  group = augroup,
  pattern = "*",
  callback = function()
    vim.highlight.on_yank({ timeout = 150 })
  end,
  desc = "Sorot teks saat yank",
})
 
-- 4. Kembali ke posisi kursor terakhir saat membuka file.
vim.api.nvim_create_autocmd("BufReadPost", {
  group = augroup,
  pattern = "*",
  callback = function()
    local last = vim.fn.line("'\"")
    if last > 1 and last <= vim.fn.line("$") then
      vim.api.nvim_win_set_cursor(0, { last, 0 })
    end
  end,
  desc = "Kembali ke posisi terakhir saat membuka file",
})

#Why Is augroup So Important?

Notice the first line: vim.api.nvim_create_augroup("UserConfig", { clear = true }). This is the shield against the most classic autocommand bug — handlers that get registered repeatedly.

#Why winsaveview() and winrestview()?

This is a detail that is often ignored but determines quality of life. When %s/\s\+$//e runs in BufWritePre, the cursor position and fold state can shift. vim.fn.winsaveview() saves the view state (cursor position, top line, folds), and vim.fn.winrestview(save) restores it after the substitution. The result: the file gets tidied without you ever noticing anything happened — the cursor does not jump and the screen does not flicker.

#Restricting with pattern

Autocommands can be restricted to specific file patterns. pattern = "*" means all buffers; pattern = { "*.go", "*.py" } only applies to Go and Python files. This matters for events like BufWritePre, where we do not want to tidy files that intentionally contain significant whitespace (for example deliberate .md files, or auto-generated files).

#Custom User Commands: Extending the : Language

Autocommands work automatically; user commands work when you call them. With vim.api.nvim_create_user_command, you can add new commands to the Neovim command-line that behave exactly like built-in commands — complete with autocomplete.

#Basic Syntax

vim.api.nvim_create_user_command(name, handler, opts)
 
-- name : nama perintah (wajib diawali huruf besar)
-- handler : fungsi Lua atau string perintah Ex
-- opts : nargs, range, complete, desc, bang, cmdtype

The most commonly used options:

#Practical Examples

-- 1. Perintah sederhana: hapus trailing whitespace seluruh buffer
vim.api.nvim_create_user_command("TrimWhitespace", function()
  vim.cmd([[%s/\s\+$//e]])
end, { desc = "Hapus trailing whitespace di seluruh buffer" })
 
-- 2. Perintah dengan argumen: sapa nama
vim.api.nvim_create_user_command("Greet", function(args)
  print("Halo, " .. args.args .. "! Selamat datang di Neovim.")
end, { nargs = "*", desc = "Sapa nama", complete = "file" })
 
-- 3. Perintah dengan range: substitusi hanya pada baris yang dipilih
vim.api.nvim_create_user_command("ReplaceHello", function(args)
  local start, finish = args.line1, args.line2
  vim.api.nvim_buf_call(0, function()
    vim.cmd(start .. "," .. finish .. "s/hello/halo/ge")
  end)
end, { range = "%", desc = "Ganti hello dengan halo di range" })
 
-- 4. Perintah untuk menyalin path absolut ke clipboard
vim.api.nvim_create_user_command("CopyPath", function()
  local path = vim.fn.expand("%:p")
  vim.fn.setreg("+", path)
  print("Path disalin: " .. path)
end, { desc = "Salin path absolut buffer ke clipboard" })

#Naming Rules: First Uppercase Letter

#Autocommand + User Command: One Unit

Both mechanisms work best when combined. Real example: the format-on-save we promised in episode 7. Instead of hard-coding the logic in an autocmd, we create the :Format command first:

vim.api.nvim_create_user_command("Format", function()
  -- placeholder: di episode 17 kita ganti dengan conform.nvim
  if vim.bo.filetype == "lua" then
    vim.cmd("silent !stylua %")
  end
end, { desc = "Format buffer dengan formatter sesuai bahasa" })
 
-- Panggil :Format otomatis sebelum menyimpan
vim.api.nvim_create_autocmd("BufWritePre", {
  group = augroup,
  pattern = { "*.lua" },
  callback = function()
    vim.cmd("Format")
  end,
  desc = "Format file Lua saat menyimpan",
})

The pattern of command as a building block + autocmd as the trigger is very common in production-grade configs — we will see it again in episode 17 when we discuss real formatters.

#Filetype Detection & Modeline

So far all our autocommands are global. But one of Neovim's strengths is its ability to adapt behavior based on the type of file — this is the last topic of this episode.

#How Neovim Detects Filetype

Neovim enables filetype detection by default (filetype on). When opening a file, it determines the file type from the file's extension, name, or contents. Check the result with :set filetype? — for example filetype=lua for init.lua, filetype=go for main.go.

#Per-filetype Options with ftplugin

There are two main ways to tailor behavior per language: ftplugin and the FileType autocommand. The most idiomatic is ftplugin — Lua files placed in after/ftplugin/ that are automatically loaded whenever a specific filetype is detected.

~/.config/nvim/
└── after/
    └── ftplugin/
        ├── lua.lua       # dimuat untuk file .lua
        ├── go.lua        # dimuat untuk file .go
        ├── python.lua    # dimuat untuk file .py
        ├── typescript.lua
        └── make.lua

-- Opsi khusus Go: tab nyata (Go mewajibkan tab), indentasi 4 kolom
vim.opt_local.tabstop = 4
vim.opt_local.shiftwidth = 4
vim.opt_local.expandtab = false
vim.opt_local.smartindent = false

-- Opsi khusus Python: indentasi 4 spasi, tampilkan nomor relatif
vim.opt_local.tabstop = 4
vim.opt_local.shiftwidth = 4
vim.opt_local.expandtab = true
vim.opt_local.relativenumber = true

The alternative to ftplugin is the FileType autocommand — suitable for logic beyond simple options:

vim.api.nvim_create_autocmd("FileType", {
  group = augroup,
  pattern = { "python", "lua", "javascript" },
  callback = function()
    vim.opt_local.expandtab = true
    vim.opt_local.shiftwidth = 4
  end,
  desc = "Indentasi 4 spasi untuk bahasa tertentu",
})

When to use which? Use ftplugin for simple option settings (lightweight, idiomatic, automatically loaded per buffer). Use the FileType autocmd when you need more complex logic or are already integrated with the same augroup.

#Modeline: Settings Inside the File Itself

Sometimes you open someone else's file that follows different conventions — for example a project using 2-space indentation while your default is 4. Modeline lets a file declare its own settings inside its first or last line:

# vim: set ts=2 sw=2 expandtab:

/* vim: set ts=2 sw=2 expandtab: */

When Neovim opens a file with a modeline like the above, the ts, sw, and expandtab options are automatically set for that buffer — the file "talks" to the editor about how it should be displayed. This is very useful for files with special conventions like Makefiles (which require tabs):

# vim: set noexpandtab ts=8 sw=8:

#Common Pitfalls of Autocommands, Filetype & Custom Commands

1. Autocommand handlers registered twice because the config reloads without an augroup. Solution: always create an augroup with { clear = true }.
2. Using pattern = "*" when it should be specific. A BufWritePre autocommand with pattern = "*" will tidy trailing whitespace in all buffers, including .log files or files that intentionally have spaces. Restrict with patterns or enable buffer-locally when needed.
3. Forgetting winsaveview() in BufWritePre so the cursor jumps to line 1 every time you save. Always save and restore the view for autocommands that modify buffers.
4. User commands without desc. The command still works, but it is hard to debug when there are many. Get in the habit of writing desc from the start.
5. A lowercase user command name → error E183. Always start with an uppercase letter, or deliberately use force = true.
6. Using vim.opt (global) in an ftplugin so per-language settings leak into other buffers. Use vim.opt_local.
7. A filetype that is not detected. Check :set filetype?; if empty, the file extension is not recognized. You can add vim.filetype.add({ extension = { mdx = "markdown" } }).
8. Modeline enabled for untrusted files — a security risk. Disable modeline when opening suspicious files.

#Closing

In episode 8 we turned Neovim from a passive editor into a reactive one. You mastered autocommands with vim.api.nvim_create_autocmd — from trimming trailing whitespace on BufWritePre, highlighting yanked text, to restoring the cursor position on BufReadPost — all neatly tied into a single augroup to prevent duplication. You built custom user commands with vim.api.nvim_create_user_command, complete with nargs, range, and complete. Finally, you understood filetype detection, set per-filetype options via after/ftplugin/, and leveraged modeline for files with special conventions.

Key points to take with you:

• Always register autocommands inside an augroup with { clear = true } to prevent duplication.
• Autocommands that modify buffers on BufWritePre must use winsaveview() / winrestview().
• User command names must start with an uppercase letter.
• Use vim.opt_local in ftplugins so per-language settings do not leak into other buffers.
• Modeline is a powerful but security-prone feature — beware of untrusted files.

You can now make Neovim respond to events and understand each file's context. But there is one big leap we have not taken: the plugin ecosystem. Every plugin we will discuss from episode 10 to the end of the series — Treesitter, Telescope, LSP, formatters, up to AI assistants — needs a foundation to be installed and managed cleanly. In episode 9, we will build that foundation: The Modern Plugin Manager with lazy.nvim — the bootstrap script, the lua/plugins/*.lua structure, and the beautiful :Lazy UI. Stay motivated!