Vim

Ripscope works with Vim’s built-in cscope support. Its plugin connects Vim to your project as soon as you open a C file, so :cs find works right away.

Requirements: Vim with +cscope and +quickfix (and +job on Windows). The workflows are checked with Vim 9.2.1164 on Linux and Windows 11.

Set up in one step

With vim-plug, add this line to your vimrc and run :PlugInstall. It installs the plugin and the ripscope executable.

Plug 'pederbe/ripscope', { 'branch': 'release', 'do': ':RipscopeInstall' }

The release branch holds the latest release, and :RipscopeInstall installs the executable of that same version.

Or run the installer. It installs the executable and puts the plugin where Vim loads packages by itself, so there is nothing to add to your vimrc.

With another plugin manager, install the release branch of https://github.com/pederbe/ripscope and run :RipscopeInstall as its build step.

First search

Open a C file in your project and find a definition (a new file connects once you save it):

:cs find g main

The first time, Vim says ripscope: indexing ... for the first time while it indexes the project, which takes a moment on a large one. Then use :copen to see the results and press Enter on one to jump to it. Save an edit and search again: the results include it.

Ripscope picks the project and keeps its index for you:

• The project is the nearest directory above the file that holds a cscope.files, else the nearest Git repository, else Vim’s current directory when the file is inside it, else the file’s own directory.
• The sources are the files cscope.files names, when there is one. Otherwise Ripscope finds the C sources in the project and its subdirectories.
• The index lives in your cache directory, ~/.cache/ripscope on Linux and %LOCALAPPDATA%\ripscope on Windows, named after the project. On Windows a search briefly makes a marker file in the project directory.

Your home directory and a drive are never taken from Vim’s current directory, and a Git repository there, such as one for dotfiles, is not taken as a project. Where the project is your home directory or a drive, only the files directly in it are indexed. ripscope --project FILE shows what Ripscope picks for a file.

Searches

Search with Vim’s own cscope commands:

:copen shows results in the quickfix window; :cnext and :cprevious move through them. These optional mappings search for the word under the cursor:

nnoremap <Leader>cg :cs find g <C-R><C-W><CR>
nnoremap <Leader>cc :cs find c <C-R><C-W><CR>
nnoremap <Leader>cs :cs find s <C-R><C-W><CR>
nnoremap <Leader>ca :cs find a <C-R><C-W><CR>

Commands

Vim searches one project at a time: the project of the first C file you open. :RipscopeConnect switches to the current file’s project. Ripscope leaves Vim alone when cscopeprg names another program, such as gtags-cscope, and keeps your own cscopequickfix.

Vim finds ripscope on PATH, else where the installer puts it (~/.local/bin, or %USERPROFILE%\.local\bin on Windows). If it finds none, opening a C file says so and suggests :RipscopeInstall.

Choosing the project yourself

Set g:ripscope in your vimrc to change the defaults. Without a root, these apply to every project:

let g:ripscope = {'auto_refresh': 0, 'include_dirs': ['include']}

With a root, you choose the project, the index and its sources, and nothing connects by itself: run :RipscopeBuild to build the index and connect.

let g:ripscope = {
      \ 'backend': '/home/me/.local/bin/ripscope',
      \ 'root': '/home/me/project',
      \ 'index': '/home/me/project/ripscope.db',
      \ 'sources': ['src/main.c']}

On Windows use drive paths such as 'C:/Users/me/.local/bin/ripscope.exe' and 'C:/Projects/example'; backslashes are also accepted. Settings are read when the plugin loads, so restart Vim to change them. Without a plugin manager, set g:ripscope and then source the plugin’s plugin/ripscope.vim.

Good to know

• Save and search. Searches refresh changed files automatically in the same connection, including external edits and header changes. Unmodified loaded buffers can be reloaded with :checktime after external edits.
• Explicit source lists stay fixed. With a file list, add or rename its entries when membership changes. Saves and searches never rewrite that list.
• :RipscopeBuild reads saved files and blocks Vim while it runs. The default automatic refresh explicitly overrides the -d Vim supplies to its backend.
• An invalid query raises E609; a valid query without matches raises E259.
• Warnings keep the available rows and raise E609 too. See results, warnings and failures for diagnostics and recovery.
• Ripscope leaves Vim alone when another cscope connection is open, and refuses to replace unrelated cscope connections.
• Because of how Vim starts cscope programs, the executable, project and index paths may contain only ASCII letters, digits, /, ., _ and - (plus the drive colon and \ on Windows). On Windows, Ripscope hands Vim the short 8.3 name of an executable or project path with spaces, which needs short names on that drive (Windows keeps them on the system drive by default). The index path cannot hold spaces, since Vim turns a short name back into the long one there. With a space in your Windows user folder’s name, set the environment variable RIPSCOPE_CACHE_DIR to a folder without spaces, such as C:\ripscope-cache, and the one-step setup works as usual. Ripscope’s message suggests a folder in your own user folder when that path has no spaces. For other paths, use Neovim.
• Result paths use cscope’s line format: printable ASCII without spaces. For other paths, use Neovim or another JSON client.