I spend most of my day in Emacs, and a significant part of my work involves searching for code—finding function definitions, tracking down variable usage, or looking for TODO comments across multiple files. While Emacs has powerful search tools like grep-find and find-grep, there's often a better option: occur-mode.
The Problem with Traditional Search
When you use grep-find or similar tools, you're searching your entire project directory. This has two problems:
- It searches files you haven't even opened, which can be slow in large projects
- It can find outdated code in backup files, build directories, or other places you don't care about
Often, what you really want is to search just the files you're currently working on—the buffers you already have open in Emacs.
What is Occur Mode?
Occur-mode is Emacs's built-in solution for searching across open buffers. Think of it as grep, but limited to your current workspace—the buffers you've already loaded.
When you run occur, Emacs:
- Searches the current buffer for your pattern
- Creates a new buffer showing all matching lines
- Lets you click on any match to jump directly to that line
It's fast, focused, and integrates perfectly with your editing workflow.
How to Use Occur
The basic command is simple:
M-x occurEmacs will prompt you for a search pattern (a regular expression). Type your search term and hit Enter.
A new buffer appears showing all matching lines, with line numbers. Click on any line (or press Enter with your cursor on it) to jump to that location in your original buffer.
Example: Searching for "function" in your current buffer shows you every function definition and usage, organized by line number.
Multi-Occur: Searching Multiple Buffers
The real power comes with multi-occur, which searches across multiple buffers at once:
M-x multi-occurEmacs asks which buffers to search. You can select multiple buffers interactively. This is perfect when you're working on related files and need to find where something is used across all of them.
There's also multi-occur-in-matching-buffers:
M-x multi-occur-in-matching-buffersThis lets you search all buffers whose names match a pattern. For example, search all .rb files, or all files in a specific directory.
When to Use Occur vs. Grep
Use occur when:
- You're actively working on a small set of files
- You want to search only what you've already opened
- You need fast, focused results
- You're iterating on code and searching repeatedly
Use grep-find when:
- You need to search the entire project
- You're looking for something in files you haven't opened yet
- You need to search based on file patterns or directories
Practical Examples
Finding function calls: Search for functionName to see everywhere you've called a function in your open files.
Reviewing TODOs: Search for TODO or FIXME to see all your pending tasks across the codebase you're currently editing.
Tracking variable usage: When refactoring, search for a variable name to see all its uses before making changes.
Debugging log messages: If you have log buffers open, occur can find specific error messages or patterns quickly.
Learning More
I discovered occur-mode through an excellent article on Mastering Emacs that covers more advanced usage and tips: Searching in Buffers with Occur Mode
If you're serious about Emacs, that entire blog is worth reading.
The Bottom Line
Occur-mode is one of those Emacs features that seems simple but becomes indispensable once you start using it. It's faster than grep for common cases, more focused than project-wide search, and integrates seamlessly into your workflow.
Next time you're about to run grep-find, consider whether occur or multi-occur might be a better fit. You might be surprised how often the answer is yes. Last modified: 2011-07-25 WordPress ID: 987
