Ripscope documentation

Find your way around C code with familiar cscope searches, a single executable and your favorite editor.

Install Ripscope, search your C project and connect your editor. Start with the steps below, then use the guides and reference as you need them.

Keep navigation in your editor

Jump from a symbol to its definition, open a caller or inspect a result list without leaving your code. Each editor guide includes setup and useful commands.

A little more context

• Coming from cscope? Read Differences from cscope for the familiar parts and the changes.
• Automating a workflow? The JSON interface gives scripts structured results, including paths with spaces and Unicode.
• Keeping an editor connected? Sessions explains the line protocol and index refreshes.
• Want to contribute? Start with Contributing and the architecture overview.

Installation

Install Ripscope for x86-64 Linux or Windows in one step, then open a C file and search. Pick the way you prefer.

The installer

The installer verifies and installs Ripscope in ~/.local/bin (%USERPROFILE%\.local\bin on Windows) and sets up Vim and Neovim, which load Ripscope by themselves from then on. Neovim set up with lazy.nvim needs the one line the installer prints, as below.

Linux

In your terminal, run:

curl -fsSL https://ripscope.com/install.sh | sh

Windows

In PowerShell 5.1 or newer, run:

irm https://ripscope.com/install.ps1 | iex

Emacs and lazy.nvim

The installer also prints one line to add to your Emacs init file, such as:

(when (load "~/.local/share/ripscope/emacs/ripscope" t) (ripscope-setup))

Neovim set up with lazy.nvim (as LazyVim, kickstart, AstroNvim and NvChad are) loads only the plugins in its list. Where the installer finds lazy.nvim, it prints the line to add there too.

Your plugin manager

One line installs the editor plugin, and its build step installs the ripscope executable.

The release branch holds the latest release, and the build step installs the executable of that same version.

The Vim, Neovim and Emacs guides cover other plugin managers and Emacs 29.

Start searching

Open a C file in your project and search: :cs find g main in Vim, :RipscopeFind g main in Neovim, or C-c s g in Emacs. The first search indexes the project into your cache directory, and later searches see your saved edits.

To search from the command line too, check that your terminal finds Ripscope:

ripscope --version

If the command is not found, add Ripscope to PATH. The editors find it either way. Then continue to the quick start.

For system packages, manual downloads or source builds, see other installation methods.

Quick start

Install Ripscope, then open a terminal in your C project. Keep the project index on a local disk. For other storage arrangements, see index locations.

1. Find a definition

Search for a function in your project. This example finds main.

ripscope -R -L -1 main

Ripscope creates the index, searches subdirectories and prints each matching file, function, line number and source line. Replace main with another function name to explore your code.

2. Find more code

Use the search that fits your question.

Replace NAME with a function or variable from your project. Command-line searches refresh the index automatically after edits.

3. Search from your editor

With the installer or one plugin-manager line, open a C file in your project and search: :cs find g main in Vim, :RipscopeFind g main in Neovim, or C-c s g in Emacs. The first search indexes the project into your cache directory, and later searches see your saved edits. The Vim, Neovim and Emacs guides explain how the project is found, file-list selection and optional manual updates.

Prefer a guided example? Follow the example project. For include directories, file lists and other project options, see building an index.

Example project

This optional tutorial uses a tiny project. Install Ripscope first. Every output shown is what Ripscope prints.

demo/
├── greet.c
├── main.c
└── include/
    └── greet.h

/* include/greet.h */
void greet(const char *name);
extern int greet_count;

/* greet.c */
#include <stdio.h>
#include "greet.h"

int greet_count;

void greet(const char *name)
{
    greet_count = greet_count + 1;
    printf("Hello, %s!\n", name);
}

/* main.c */
#include "greet.h"

int main(void)
{
    greet("world");
    return 0;
}

1. Build the index

From the project directory:

$ ripscope -bk -I include

• -b builds or updates the index, as in cscope. With no file arguments, Ripscope uses cscope.files if it can be read, otherwise the source files in the current directory with cscope’s suffixes (.c, .h and others). Add -R to include subdirectories.
• -k leaves out the system include directory, as in cscope; without it, headers such as stdio.h are indexed too.
• -I include lets #include "greet.h" resolve, so include/greet.h is indexed too.
• Ripscope creates ripscope.db in the project directory for you; -f names another.

2. Ask questions

Each query names a field (-0 to -9) and a pattern. -L prints matching rows as file context line text.

$ ripscope -L -1 greet          # where is greet defined?
greet.c greet 6 void greet(const char *name)

$ ripscope -L -3 greet          # who calls greet?
main.c main 5 greet("world");

$ ripscope -L -2 main           # what does main call?
main.c greet 5 greet("world");

$ ripscope -L -9 greet_count    # where is greet_count assigned?
greet.c greet 8 greet_count = greet_count + 1;

$ ripscope -L -8 greet.h        # who includes greet.h?
greet.c <global> 2 #include "greet.h"
main.c <global> 1 #include "greet.h"

The second column is the context: the enclosing function, <global> for file scope, or <unknown> where it does not apply. See Queries for all the fields.

3. Keep it fresh

-L brings the index up to date before answering, analysing only files that changed. Add a new caller and ask again:

$ echo 'void helper(void) { greet("x"); }' >> main.c
$ ripscope -L -3 greet
main.c main 5 greet("world");
main.c helper 8 void helper(void ) { greet("x"); }

Use -dL to query the index as it is. Stored queries work even when the source files are gone.

4. Use it from your editor

Vim and Neovim keep a Ripscope Session open and send one query per line:

$ printf '1greet\n3greet\nq\n' | ripscope -l
>> cscope: 1 lines
greet.c greet 6 void greet(const char *name)
>> cscope: 2 lines
main.c main 5 greet("world");
main.c helper 8 void helper(void ) { greet("x"); }
>>

You rarely type this yourself. With Vim, Neovim or Emacs set up, open main.c and search there instead. The editors keep their own index of the project in your cache directory. Save an edit and search again to see it. Each editor reuses its session between searches.

Exact output

Paths are printed as they are, spaces included, as cscope prints them. Add --json to get one JSON array per row, which carries every byte:

$ ripscope --json -L -3 greet
["main.c","main",5,"greet(\"world\");"]
["main.c","helper",8,"void helper(void ) { greet(\"x\"); }"]

See the JSON interface.

Building an index

ripscope -b [-R] [-k] [-u] [-I DIR]... [-f INDEX] [--] [SOURCE...]
ripscope -b [-R] [-k] [-u] [-I DIR]... [-f INDEX] -i LIST

-b builds the index, or updates one that exists, then stops. The index is one file, ripscope.db unless -f names another. It is created only where no file exists, in an empty file, or over an index Ripscope made: a cscope database or any other file at that path is left untouched and the index build fails.

Every readable file contributes navigation facts. The analyzer reads C as the reference cscope does, with Corrections where cscope misreads it; code it cannot read well costs accuracy only where it is.

Choosing the files

Ripscope saves how you selected files (the selection rule), and every later update applies it again, as cscope does at each index build. The first matching rule wins:

1. A file list, -i LIST. File names given beside it are not read, as in cscope.

2. Source files given as arguments. A name given twice is read once.

3. Automatic discovery, when neither is given:

   • cscope.files in the current directory, if it can be read;
   • otherwise the source files directly in the current directory, or in the whole tree with -R.

   Because it is applied again at every update, creating or deleting cscope.files changes what the next update indexes.

A named file (an argument or a list entry) that does not exist or is not a regular file is reported, as cscope reports it (ripscope: cannot find file X), and the rest is indexed; one that cannot be read is reported as cannot read X. When none of the selected files can be indexed, the index build fails with no source files found: a new index is not made, and an index that already existed keeps what it had. Unlike cscope, a symbolic link you name is followed.

In every case, literal #include directives are followed (see Include directories), so headers reached from the selected files are indexed too.

Directory discovery

Source files are regular files whose last suffix is one of cscope’s: .c .h .l .y .C .G .H .L .bp .qc .qh .sd .cc .hh .tcc .cpp .cxx .hpp .hxx (case-sensitive). SCCS-style names such as s.file.c are skipped, as in cscope. Symbolic links found in a directory are not followed, as in cscope. With -R, discovery also descends into subdirectories. A directory that cannot be read is reported; its files keep what the index knew about them.

File lists

A file list names one source per entry, relative to the directory you build the index in:

src/main.c
src/util.c
"src/file with spaces.c"
-I include
-k

• Entries are separated by spaces, tabs or newlines. Double quotes allow spaces; inside quotes, \" and \\ are the only escapes.
• A list may hold the options cscope reads there: -I DIR and -k, and -q, -c and -p N, which change nothing in Ripscope’s answers. -T would cut symbols to eight characters, so a list naming it is refused.
• A name the list gives twice is indexed twice, as cscope does.
• The list is read again at every update, so editing it changes what is indexed. Reading a list from standard input (-i -) is not supported.

Include directories

#include "file.h" is looked up first relative to the directory the index is built in; then, for both forms, in each -I directory in the order given, the list’s -I directories, the directories in the INCLUDEDIRS environment variable, and last the system directory (/usr/include, or INCDIR) unless -k is given, as cscope does. Headers that cannot be found are skipped. A computed include such as #include MACRO is not followed.

Updating

Run the same -b command again, or query with -L or use r in a session: each brings the index up to date. An update:

• applies the saved selection rule again;
• re-reads a file when its size, modification time or identity changed, or when it was modified too close to its last read to trust the timestamp, and analyses it again only if its bytes changed;
• publishes a new revision in one transaction when anything changed (re-reading a file whose bytes did not change publishes nothing), so a query or session always reads a complete revision, and sessions see the new one at their next query.

-u updates unconditionally, as cscope says: every file is read and analysed again, and nothing the index held is kept. It is also how a damaged index is repaired (see Checking and repairing).

A -b with different sources, -i, -R or -I replaces the saved selection rule. A file that cannot be read keeps its last facts in an update and is tried again next time; an index build (-b) leaves it out.

Where the index may live

SQLite’s write-ahead log, which lets queries read while an update runs, is unsafe on network file systems. Ripscope therefore does not create or update an index on NFS, SMB and other network or cluster file systems, on WSL’s view of Windows drives, on FUSE mounts other than a block device’s (sshfs, cloud-sync clients, and also gocryptfs or mergerfs over a local disk) or on Windows shares. Keep the index in a local folder; the sources may be anywhere.

An index may live in a folder OneDrive synchronises, such as a Documents or Desktop folder OneDrive backs. OneDrive may lock the index or copy it while it is written, so the index build that makes the index there warns once, and -f can keep it in a folder OneDrive leaves alone. Ripscope knows OneDrive’s folders by the OneDrive, OneDriveCommercial and OneDriveConsumer environment variables. If the index is ever damaged there, -bu builds it again.

Use an index from one machine only. SQLite’s write-ahead log needs every process that uses the index to run on the same machine, so a query from another machine, over NFS or a share, is unsafe, although it is not refused.

Sharing an index between users (Unix)

A new index gets the permissions the umask gives any new file, as cscope’s database does. An index rebuilt over another keeps that index’s permission bits, and its group when the user rebuilding it belongs to that group (root keeps its owner too). Only a user who may write an index can rebuild it.

Every user of an index must be able to write it, and the files SQLite keeps beside it, which it gives the index’s permissions. An index also holds the text of the lines that hold symbols in the files it covers, so anyone who can read it can read those lines, even of files they cannot read. For a group to share an index privately, keep it in a directory of the group with the setgid bit, so that the index and SQLite’s files belong to the group, closed to other users, and build it with umask 007, so that the group may write them:

chgrp team DIR && chmod 2770 DIR
(umask 007 && ripscope -b -f DIR/ripscope.db)

Or give the directory an ACL for the group and a default one, which lets the group write every new file in it, whatever the builder’s umask; the entries for other users decide who else can read the index:

setfacl -m g:team:rwx,o::---,d:g:team:rwx,d:o::--- DIR

Do not set the sticky bit on such a directory: members could no longer remove each other’s SQLite files. Users outside the group cannot open the directory, so they cannot use the index.

Queries

ripscope  -L [-f INDEX] [-C] [-P PATH] [--json] -FIELD PATTERN     update, then query
ripscope -dL [-f INDEX] [-C] [-P PATH] [--json] -FIELD PATTERN     query without updating

Query fields

Each result row has four parts, separated by single spaces:

greet.c greet 6 void greet(const char *name)
│       │     │ └── displayed source text
│       │     └──── line number
│       └────────── context: enclosing function or macro, <global>, or <unknown>
└────────────────── file path

For field 2 the context is the called function. For field 1 it is the pattern you searched for, as in cscope; a field-1 pattern with blanks cannot be shown that way, so it is refused with a pointer to --json.

Rows come in cscope’s order: rows at file scope first, then the rest. Each row’s context is the function or macro its name sits in, worked out within its file; cscope’s contexts can differ, depending on how its database was built (see Differences from cscope).

Patterns

Symbol patterns (fields 0, 1, 2, 3, 9). A plain C identifier matches exactly. If the pattern contains any of ^ . [ { * + $ | (, it is a POSIX extended regular expression that must match the whole name: greet.* matches greet and greet_count, but reet matches nothing. Trailing blanks are ignored.

Text (fields 4 and 5) is a literal byte string, including spaces.

Regular expressions (field 6) are POSIX extended regular expressions applied to each line. ^ and $ anchor to line boundaries, and . never matches a newline. A line of a CR LF file ends with its carriage return, as in cscope.

File and include patterns (fields 7 and 8) are regular expressions that may match anywhere in the path or include name: -7 greet finds greet.c and include/greet.h.

Patterns are limited to 4096 bytes. Matching is byte-based in the C locale: a pattern in fields 4 to 6 may hold any byte but NUL and a line break, UTF-8 or not, one in fields 7 and 8 any but those and a carriage return, and symbol patterns are printable ASCII. A pattern that cannot be used gives no rows, as in cscope, with the reason on standard error; a few that cscope does answer, such as back-references, are refused too (see Differences from cscope).

Case-insensitive matching

Add -C (or send c in a session) to ignore ASCII letter case in every field. Non-ASCII letters are always compared exactly. As in cscope, the pattern itself is lowercased, escapes and classes included, so under -C \W means \w, \S means \s, and [[:upper:]] matches nothing.

Updating or not

• -L first brings the index up to date from the saved selection rule, then answers from the new revision. If another process is updating the index, it answers from the last published revision and says so.
• -dL answers from the index as it is, and never creates one.
• An index that has published nothing yet, because another process is building it afresh or its first index build failed, is no index: -dL fails and says so, as does -L while another process is building it; otherwise -L builds it, as it builds a missing one.

Stored and live fields

Fields 0, 1, 2, 3, 7, 8 and 9 are answered from the index, so they keep working when sources are moved or deleted. Text searches (fields 4, 5 and 6) read the current contents of the indexed files, as cscope does, even with -d. A file that cannot be read is skipped, with a warning on standard error.

Live searches read files relative to the directory the index was built in. -P PATH does what it does in cscope: relative names are read below PATH, and text rows show them with it (PATH/src/main.c). Stored rows keep the names the index holds.

Output

Paths are printed as they are, spaces and non-ASCII characters included, as cscope prints them. A row whose path holds a control character cannot be carried by the line format and is skipped, with one warning. Displayed text is compacted as cscope compacts it; control bytes in it are shown as \xHH. A line a text search finds keeps its tabs and a CR LF ending, as cscope prints it. --json carries every byte.

Warnings go to standard error before the first row, where xcscope and Vim pass over them.

Exit status

Ripscope exits with status 0 when the query ran, including when nothing matched or the pattern could not be used, and 1 on any other error, with a message prefixed ripscope: on standard error.

Sessions

A session keeps one Ripscope process open and answers many queries. This is how editors use Ripscope, exactly as they use cscope -l.

ripscope -l [-f INDEX] [-d] [--auto-refresh | --no-auto-refresh] [-C] [-P PATH] [--json | --vim-errors]

Without -d, the session brings the index up to date at startup and again before the first query after its sources change. With -d, it uses the index as it is until an explicit r command. A missing index, or one that has published nothing yet, cannot be queried.

--auto-refresh explicitly enables updates, including startup, even if an editor adds -d. --no-auto-refresh explicitly disables them. Either control takes precedence over -d regardless of argument order. The two controls cannot be combined. Explicit r works with either setting.

Commands

Each command is one line; as in cscope, its first character decides what it is:

cscope’s C and F commands, which change its file list, are answered with an empty line and change nothing: the saved selection rule decides the files. Other commands are reported on standard error.

In the default line format, the session prints the prompt >> , then for each query cscope: N lines followed by N result rows. A query with no matches, or one that cannot be answered, prints Unable to search database; for the latter, the reason follows on standard error. r is answered with an empty line, as in cscope.

$ ripscope -l -f project.db
>> 1greet
cscope: 1 lines
greet.c greet 6 void greet(const char *name)
>> q

A request line is at most a field digit and 4096 bytes of pattern; a longer one is read to its end and refused as a whole.

Seeing updates

An updating session watches what its index was made from: the indexed files and their directories, the file list, the directories discovery searches and every include it looked for, found or not. Before each query it takes in every change saved so far, and when one could change an answer it refreshes first, analysing only the changed files. So a saved edit, a new or removed file, a changed file list, a listed file that appears or a header that appears outside the project shows in the next search, whether it came from your editor, another editor, a generator or a branch switch. Explicit source lists stay fixed.

Queries between changes answer at once from the published revision, without looking at the files. Swap and backup files, build output and other files a refresh would not read change nothing, except in a directory checked by its times (below), where any file made or removed makes the next query refresh. Several saves before a query make one refresh, and a refresh that finds nothing changed publishes no new revision. An edit saved while a refresh runs is taken in by the next query. Text searches read the current files, from the file list as of the last refresh.

The watch uses inotify on Linux, and ReadDirectoryChangesW on Windows, where each query briefly makes a marker file, .ripscope-PROCESS-N.sync, in the project directory to know that every earlier change has been reported. When events are lost, a directory above the watched files is made, removed or renamed (a clean build, an SDK swapped for another, a directory link pointed elsewhere), or another process publishes a revision, the next query refreshes anyway and the watch starts again where it must. Where the sources cannot be watched, every query refreshes, which is slower on large projects, and the first answer says so. That happens past Linux’s fs.inotify.max_user_watches, for sources on a network or FUSE file system (NFS, SMB, sshfs, WSL’s Windows drives and the like), which may not report changes made elsewhere, and on a Windows drive that reports no changes at all. Names in a directory that cannot be watched, or outside the project on such a file system, are checked before each query. So are include directories outside the project on Windows. Where many names looked for in such a directory are missing, its times are checked instead, with the names found in it. A network file system mounted inside the project directory is not noticed: send r after changes made there from another machine. A directory reached through a link is watched where the link led when the watch began: when the directory it leads through is renamed or replaced, rather than the link itself, send r. On Windows, a link to a file is not followed: send r after changing the file it names.

-u applies at startup and to r. Refreshes before queries analyse only what changed.

Every query reads the newest published revision. If another process (or your editor’s index build command) updates the index, the next query sees the change, also when the index was deleted and built again. While the index cannot be read, or is being built afresh and has published nothing yet, a query fails and says why, as a one-shot query does. If a refresh before a query fails or another process is updating, the query answers from the last published revision with a warning that freshness is unconfirmed, and the next query tries again. An unreadable file keeps its last facts, with a warning, until a refresh can read it. Warnings use the same transport as other answer warnings. If explicit r fails or is skipped, its diagnostic goes to standard error or a JSON error frame.

Warnings

Warnings about an answer, such as a file a text search could not read, are written to standard error before the answer, where cscope writes its own messages and Vim passes over them.

The editor diagnostic guide describes how Vim, Neovim and Emacs distinguish warnings, failures and valid empty answers, and how to recover.

Vim error handshake

--vim-errors is for Vim’s built-in cscope support. After a query that cannot be answered, Ripscope prints a short message on one line (with the reason, when the index cannot be read) and Press the RETURN key to continue:, then waits for one empty line; Vim shows the message as E609, so an unusable query is told apart from an empty result (E259). After an answer that came with warnings, a short fixed notice does the same. Other clients should not use this flag.

JSON sessions

With --json, every line Ripscope writes is a JSON value. See JSON interface.

JSON interface

cscope’s line format separates fields with spaces and has no quoting, so a row whose path holds a control character cannot be carried, and a line’s bytes may be shown escaped. Add --json to any query or session to get exact output instead. Nothing else about the query changes: the same rows, in the same order, with the same contexts and text.

--json cannot be combined with --vim-errors, index builds or --verify.

One-shot queries

Each result is one line containing a JSON array [path, context, line, text]:

$ ripscope --json -dL -f "navigation index.db" -1 greet
["src/café/greet.c","greet",6,"void greet(const char *name)"]

• path is a string. Relative paths are relative to the directory the index was built from, or below -P PATH for text searches.
• context is a string and line a positive integer.
• text is a string when the line is valid UTF-8, and otherwise an array of byte values (0 to 255), so nothing is lost. A text search’s line of a CR LF file keeps its carriage return.

An empty standard output with no diagnostic means no matches. Warnings and errors go to standard error. A query that cannot read the index, or whose output fails, exits with status 1. An unusable pattern follows cscope’s one-shot behavior: no rows, a diagnostic on standard error, and status 0. Check both streams; status 0 alone does not establish that the pattern was valid.

Sessions

In a --json session, every line Ripscope writes is one JSON value:

Parse frames as JSON objects; do not rely on key order, and ignore keys you do not know.

$ printf '1greet\nq\n' | ripscope --json -dl -f project.db
{"type":"ready"}
{"type":"result","count":1}
["greet.c","greet",6,"void greet(const char *name)"]
{"type":"ready"}

Commands are the same as in line-format sessions, one line of at most a field digit and 4096 bytes each. A client should treat a missing ready frame as a failure.

A JSON session refreshes before a query after a change as a line session does. A refresh that fails still yields the query’s result from the last published revision, followed by a warning that its freshness is unconfirmed. A refresh that succeeds adds no frame. The rebuilt frame belongs only to explicit r.

Path rules

• Paths may contain spaces and any Unicode characters except NUL.
• Paths are stored as the index build named them (on Windows with / as the separator), not case-folded.
• A path that is not valid UTF-8 (possible on Linux) is written as an array of byte values, as text is.

Editor integration

The Neovim adapter uses the JSON interface directly. Other integrations can launch Ripscope and decode these responses with their language’s JSON support.

Checking and repairing an index

An index is one SQLite file (with SQLite’s -wal and -shm files beside it while it is in use). Every update is one SQLite transaction: it either completes, or the previous revision stays as it was, even if the process is killed or the machine loses power. There is no separate journal to recover.

Checking

ripscope --verify [-d] [-f INDEX]

--verify runs SQLite’s full integrity and foreign-key checks, then (unless -d) brings the index up to date reading and hashing every file, and finally decodes every stored analysis and checks the name postings against them. It prints index verified: revision N, M files, or lists what is wrong and exits with status 1. A query that meets a damaged index says so in a warning starting damaged index:, and still answers from what it can read. An update that needs a name’s postings it cannot read, or the block size the index splits a new analysis by, fails with such a message and keeps what the index had, and so does a query without -d, which updates first.

Repairing

ripscope -bu [the options you built the index with]

-u builds the index unconditionally: every file is read and analysed again and nothing the index held is kept, so a damaged analysis is replaced. When SQLite can no longer read the index file at all, -u makes it afresh. Give the options you built the index with (the sources, -i, -R, -I, -k), since a damaged index may not be able to tell which they were.

Older indexes

An index built by an earlier version of Ripscope, whose analyzer read C differently, analyses every file again at its next update. Until then, -d answers from it as it was built. Where this version cannot read a file’s stored analysis at all, fields 0 to 3, 8 and 9 leave the file out and say how many they left out. Field 7 still lists it, and text searches read it. An index with another schema version is read by neither queries nor updates, which ask for an index build: -b makes it afresh.

Other installation methods

For the standard installation, use the install script. This page covers PATH setup, system packages, manual downloads, source builds and installer options.

Add Ripscope to PATH

PATH is the list of directories your terminal searches for commands. The install scripts put Ripscope in ~/.local/bin on Linux and %USERPROFILE%\.local\bin on Windows.

Linux

For Fish, run this once, then try ripscope --version again.

fish_add_path ~/.local/bin

For Bash, add this line to ~/.bashrc. For Zsh, add it to ~/.zshrc. Then open a new terminal.

export PATH="$HOME/.local/bin:$PATH"

Windows

In Start, open Edit environment variables for your account. Under user variables, edit Path, choose New and add %USERPROFILE%\.local\bin. Open a new terminal, then run ripscope --version.

Debian/Ubuntu and RHEL-family packages

Select the version from GitHub Releases. Debian/Ubuntu .deb and RHEL-family .rpm packages contain the inspected Linux x86-64 executable, with glibc 2.28 or newer and the system GCC runtime required. Verify the selected package’s .sha256 sidecar, then install it:

sha256sum -c ripscope_0.1.1_amd64.deb.sha256
sudo apt install ./ripscope_0.1.1_amd64.deb

sha256sum -c ripscope-0.1.1-1.x86_64.rpm.sha256
sudo dnf install ./ripscope-0.1.1-1.x86_64.rpm

Notices and editor sources are installed in /usr/share/ripscope.

Archives and system packages

Select the version from GitHub Releases:

The archives include their executable, licences, editor sources and build manifest. Compare the archive against its individual .sha256 sidecar before extracting it. Keep the complete extracted directory:

sha256sum -c ripscope-0.1.1-x86_64-linux-gnu.tar.gz.sha256
tar -xzf ripscope-0.1.1-x86_64-linux-gnu.tar.gz
./ripscope-0.1.1-x86_64-linux-gnu/bin/ripscope --help

Get-FileHash .\ripscope-0.1.1-x86_64-windows-msvc.zip -Algorithm SHA256
Get-Content .\ripscope-0.1.1-x86_64-windows-msvc.zip.sha256
Expand-Archive .\ripscope-0.1.1-x86_64-windows-msvc.zip -DestinationPath .\ripscope-install
.\ripscope-install\ripscope-0.1.1-x86_64-windows-msvc\bin\ripscope.exe --help

Checksums identify the downloaded bytes. For repository and workflow provenance, use the exact-tag/source attestation verification instructions.

Building from source

You need a recent stable Rust toolchain and a C compiler for bundled SQLite: GCC or Clang on Linux; Microsoft’s MSVC Build Tools and the Windows SDK on Windows. Use an x64 developer shell for an MSVC build.

git clone https://github.com/pederbe/ripscope.git
cd ripscope
cargo build --release --locked

Or install directly from the repository:

cargo install --locked --git https://github.com/pederbe/ripscope.git

A binary built on a newer Linux distribution can require that distribution’s newer glibc. The pinned archive recipes and their inspection limits are documented in Linux preparation and Windows preparation. A separate Rust toolchain or SQLite installation is unnecessary for archive users.

Installer options

The install scripts select the latest release and install into your user account. Set these environment variables before running a script to change that behavior.

In PowerShell, set them through $env:.

Editor integrations

Besides the executable, the scripts put the editor integrations where the editors find them:

Vim and Neovim load packages from these directories by themselves. Vim uses ~/.config/vim instead when that is where its vimrc is. For Emacs, the script prints the line to add to your init file. Neovim set up with lazy.nvim loads only the plugins in lazy.nvim’s list, so where the script finds lazy.nvim it prints the line to add there as well. Running the script again updates them with the executable.

With a system package or an archive, the same files are in its contrib directory: copy contrib/vim to the Vim or Neovim directory above, and load contrib/emacs/ripscope.el from Emacs as the Emacs guide shows.

Notices

The scripts retain a hidden .ripscope-notices-* directory beside the executable. It contains licences, build information and a copy of the editor integrations. The Emacs integration includes xcscope’s source and its own COPYING file.

To find the directories on Linux, run

ls -d ~/.local/bin/.ripscope-notices-*

On Windows, list them in PowerShell with

Get-ChildItem "$HOME\.local\bin" -Force -Directory -Filter '.ripscope-notices-*'

Running the installer again updates the executable and retains earlier support directories. On Windows, close active Ripscope sessions before replacing the executable if it is locked.

To remove an installation, see uninstalling Ripscope.

Uninstalling Ripscope

Installed with a script

The install script removes what it installed: the executable, its notices directories and the editor integrations. On Linux, run

curl -fsSL https://ripscope.com/install.sh | sh -s -- --uninstall

In PowerShell, run

& ([scriptblock]::Create((irm https://ripscope.com/install.ps1))) -Uninstall

Set RIPSCOPE_INSTALL_DIR as you did when installing if you chose another directory. Remove the line you added to your Emacs init file yourself. On Windows, close the editors running Ripscope first: Windows keeps an executable in use, so the uninstaller says so, removes everything else, and removes the executable when run again.

The indexes the editors made stay in your cache directory, ~/.cache/ripscope on Linux and %LOCALAPPDATA%\ripscope on Windows, or the folder RIPSCOPE_CACHE_DIR names when you set it. Delete them too if you no longer need them. Indexes you built in your projects stay there.

Installed with a plugin manager

Remove the plugin’s line from your editor configuration and let the plugin manager clean up, for example with :PlugClean or lazy.nvim’s :Lazy clean, or M-x package-delete in Emacs. Then run the uninstall command above to remove the executable the plugin installed.

Installed with a system package

On Debian or Ubuntu, run

sudo apt remove ripscope

On Fedora or RHEL-family systems, run

sudo dnf remove ripscope

Installed from an archive or source

For an archive installation, remove its extracted directory after closing any editor that uses it. For cargo install, run cargo uninstall ripscope.

Results, warnings and failures

Vim, Neovim and Emacs use the same query behavior, with messages delivered through each editor’s interface. A warning accompanies an answer; a failure means the requested operation could not complete. Read the diagnostic even when rows are available or the editor reports completion.

CLI one-shot queries, including --json, retain cscope’s status-0 response to an invalid pattern: check standard error as well as the exit status. Sessions tell the invalid request apart directly, through Vim’s error handshake or a JSON error frame, which Neovim and Emacs show as a failed search.

Warnings keep the available results

A live text query skips a source file it cannot read and names it in a warning. Rows from readable files remain available. Even an answer with zero rows can carry a warning: it does not establish that the text is absent from the skipped file. In manual mode, Stored queries continue to use the index’s facts after source deletion. Automatic Refresh applies the Selection rule and removes deleted files when it can complete.

If automatic Session Refresh fails or another process is updating, Vim, Neovim and Emacs keep navigable rows from the last published revision and show a warning that freshness is unconfirmed. Fix the reported problem and search again.

Vim’s built-in cscope reader shows only a short warning notice. Repeat the same query with the CLI to see the details, for example:

ripscope -dL -f /absolute/project/ripscope.db -P /absolute/project -4 text

Use the same index, field, pattern and case option as the editor. Under silent!, Vim may leave E259 in v:errmsg after E609; inspect :messages or use an ordinary try/catch to distinguish the diagnostic from a valid empty answer.

Recovery

Fix an invalid pattern and search again. Restore an unreadable source file and retry a text query; it reads the live file without an index build. Run the normal stored search after a saved edit to refresh navigation automatically. Use the editor’s index command for Selection rule changes, explicit updates or intentional manual mode. Open Sessions see newly published revisions without a reconnect, including an index built afresh at the same path.

A failed refresh leaves the previous committed revision available. A killed or timed-out index build has unconfirmed completion: its exit alone does not tell whether it committed. Inspect the diagnostic and retry the index build before relying on freshness.

Neovim publishes query rows only after the response’s final ready frame. A timeout, truncated response or broken connection fails that search; the next explicit search opens a new session. Vim and Emacs own their result readers; treat any rows already shown by a failed or interrupted search as incomplete. Reconnect Vim if its backend exited. Emacs starts a new session at the next search after one ended.

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.

Neovim

Ripscope’s Neovim plugin searches with Ripscope and shows the results in quickfix. It keeps one Ripscope session per project through the JSON interface, so paths with spaces and Unicode work. It needs no cscope executable, shell or Python.

Requirements: Neovim 0.10 or newer on Linux or Windows. Workflow checks cover Neovim 0.12.5 on Windows and a 0.13.0 development build on Linux, with lazy.nvim too.

Set up in one step

With lazy.nvim, add this to your plugin list. It installs the plugin and the ripscope executable.

{ 'pederbe/ripscope', branch = 'release', build = ':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 Neovim loads packages by itself, so there is nothing to add to your configuration. lazy.nvim, which LazyVim, kickstart, AstroNvim and NvChad use, loads only the plugins in its list, so where it finds lazy.nvim the installer prints the line to add to that list instead:

{ dir = vim.fn.stdpath('data') .. '/site/pack/ripscope/start/ripscope' },

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:

:RipscopeFind g main

The first time, Neovim says Ripscope: indexing ... for the first time and indexes the project in the background before it searches. Press Enter on a quickfix result to open its source. 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 current file that holds a cscope.files, else the nearest Git repository, else Neovim’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.

Each search goes to the current file’s project, so several projects can be open at once, each with its own session. A search from a window with no file, such as the results list, goes to the project searched last. Your home directory and a drive are never taken from the 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.

Commands

For example, :RipscopeFind c main finds the callers of main. From Lua, call require('ripscope').find(field, pattern); require('ripscope').status() returns the last result. These optional mappings search for the word under the cursor:

local ripscope = require('ripscope')
vim.keymap.set('n', '<Leader>cg', function() ripscope.find('g', vim.fn.expand('<cword>')) end)
vim.keymap.set('n', '<Leader>cc', function() ripscope.find('c', vim.fn.expand('<cword>')) end)
vim.keymap.set('n', '<Leader>cs', function() ripscope.find('s', vim.fn.expand('<cword>')) end)
vim.keymap.set('n', '<Leader>ca', function() ripscope.find('a', vim.fn.expand('<cword>')) end)

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

Settings

setup is optional. Without a root, its settings apply to every project:

require('ripscope').setup({ auto_refresh = false, include_dirs = { 'include' } })

With lazy.nvim, put them in the spec’s opts. With a root, you choose one project for every search, and its index is ripscope.db in that root unless index says otherwise. Build it with :RipscopeBuild before the first search.

require('ripscope').setup({
  exec = '/home/me/.local/bin/ripscope',
  root = '/home/me/project',
  recursive = true,
})

On Windows, use full drive paths, for example exec = [[C:\Users\me\.local\bin\ripscope.exe]]. Lua long strings accept backslashes literally, and forward slashes also work. Relative paths resolve against the project root. Paths such as C:relative or \rooted are ambiguous and refused, and so are device namespace paths and batch or cmd backends.

Good to know

• Save and search. Searches refresh changed source automatically, including external saves and header edits. Discovery follows file additions, removals and renames. Explicit sources stay fixed, and new file-list entries must be added to the list. Saves and searches never rewrite it.
• Use :RipscopeBuild for a Selection rule change or an explicit update. auto_refresh = false keeps manual updates.
• Successive searches in a project reuse one backend process, including after index builds.
• Query warnings accompany the results; an invalid query reports its error and the session stays usable. A timeout or broken connection fails that search; the next search opens a new session. Results are published only after a complete reply.
• See results, warnings and failures for the shared behavior and recovery steps.
• A failed index build or search opens the log and never shows partial results.
• One operation runs at a time. Calling setup again closes the running sessions. Exiting Neovim closes them too.

Emacs

Ripscope ships a pinned copy of xcscope with a small adapter that runs Ripscope instead of cscope and reports index build and query failures that xcscope alone would hide. xcscope’s usual keys then search any C project, with no configuration.

Requirements: GNU Emacs 27.1 or newer on Linux or Windows. Workflow checks pass with Emacs 31.1 on both platforms, the use-package and package-vc-install lines below included. Those lines need Emacs 30 and 29 or newer.

Set up in one step

On Emacs 30 or newer, add this line to your init file:

(use-package ripscope :vc (:url "https://github.com/pederbe/ripscope" :branch "release" :lisp-dir "contrib/emacs" :rev :newest) :config (ripscope-setup))

On Emacs 29, use this line instead:

(unless (package-installed-p 'ripscope) (package-vc-install '(ripscope :url "https://github.com/pederbe/ripscope" :branch "release" :lisp-dir "contrib/emacs"))) (ripscope-setup)

The release branch holds the latest release. :rev :newest takes that branch as it is: use-package’s own release lookup cannot find the package in contrib/emacs on Emacs 31.1. The next time Emacs starts, it installs the package, and ripscope-setup installs the ripscope executable of the same version in the background when it is missing, or when the one the installer put there is older. M-x ripscope-install does that too.

Or run the installer. It installs the executable and the Emacs integration and prints the one line to add to your init file, such as:

(when (load "~/.local/share/ripscope/emacs/ripscope" t) (ripscope-setup))

Load the integration before any other xcscope package. Do not byte-compile or replace the vendored xcscope.el, which the adapter verifies.

First search

Open a C file in your project and press C-c s g, then enter a function name to find its definition. The first time, Emacs says Ripscope: indexing ... for the first time while it indexes the project. Press Enter on a result to open its source. 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 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.

A database xcscope finds by itself still wins: a cscope.out index built with M-x cscope-index-files, or an entry in cscope-database-regexps. A Git repository in your home directory, 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 the usual xcscope bindings and press Enter on a result to jump to it:

These optional bindings search for the symbol at point without a prompt:

(with-eval-after-load 'xcscope
  (define-key cscope-minor-mode-keymap (kbd "M-.") #'cscope-find-global-definition-no-prompting)
  (define-key cscope-minor-mode-keymap (kbd "M-,") #'cscope-pop-mark))

Searches go to one Ripscope session per index, which stays running and refreshes changed sources incrementally before the first search after a change, including external and header-only edits. Searches between changes answer at once. Normal saves and searches never rewrite cscope.files.

Emacs finds ripscope on exec-path, else where the installer puts it (~/.local/bin, or %USERPROFILE%\.local\bin on Windows).

Settings

(setq ripscope-xcscope-include-directories '("include"))
;; Optional manual updates until cscope-index-files is run again.
(setq ripscope-xcscope-auto-refresh nil)

Include directories apply to every index Ripscope builds. Automatic Refresh is enabled by default, and its explicit backend control overrides the -d xcscope supplies. (ripscope-setup "/path/to/ripscope") names the executable instead of finding it.

Building an index in the project

xcscope’s own index command still works, for a project whose index you want beside its sources:

• M-x cscope-index-files asks for the project root and builds cscope.out, a Ripscope index in one SQLite file. Set cscope-database-file to use another name. On Windows, Ripscope discovers files directly, honoring an existing cscope.files without overwriting it. cscope-index-recursively controls recursion, and a custom cscope-index-file is passed as a required explicit list. On Linux, xcscope generates and overwrites cscope.files using its suffix and exclusion rules, and needs Bash, GNU find and sed. Keep manual lists under another name and build those with the CLI.
• Linux’s generated list stays the Selection rule. Add new or renamed files to it, or explicitly regenerate it with cscope-create-list-of-files-to-index. Windows discovery follows additions, removals and renames unless an explicit list is used. Failed builds are shown in *cscope-indexing-buffer*.

The adapter can also be set up on its own with (ripscope-xcscope-setup "/path/to/ripscope"), which uses only xcscope’s own databases.

Good to know

• Query diagnostics stay in *cscope*, and a search that could not be answered, such as one with an invalid pattern, shows Ripscope search failed. See results, warnings and failures.
• Remote (TRAMP) projects are not supported, and result paths cannot contain spaces.
• On Windows, the executable, index and option paths must fit the active Windows ANSI code page, and unsupported characters are refused. Search patterns may hold any character. The list-only generation command is unavailable there.
• On Windows a running session keeps its project directory in use: run M-x ripscope-xcscope-stop-sessions before moving or removing a project.

The vendored xcscope and the adapter are licensed GPL-2.0-or-later, separately from Ripscope. See the integration README.

Command line

Ripscope accepts what Vim, Neovim, Emacs and cscope -Rbqk-style scripts send, read as cscope reads its options: single-letter options can be grouped (-Rbqk, -dL), an option’s value may follow it directly or as the next argument (-fINDEX, -f INDEX, -0name), and -- ends the options. Options that change nothing in cscope’s line and one-shot output are accepted and ignored. Options Ripscope cannot honour faithfully are refused, never ignored.

Forms

ripscope -b [-R] [-k] [-u] [-I DIR]... [-f INDEX] [--] [SOURCE...]
ripscope -b [-R] [-k] [-u] [-I DIR]... [-f INDEX] -i LIST
ripscope -L [-d] [--auto-refresh | --no-auto-refresh] [-C] [-P PATH] [--json] [-f INDEX] -FIELD PATTERN
ripscope -l [-d] [--auto-refresh | --no-auto-refresh] [-C] [-P PATH] [--json | --vim-errors] [-f INDEX]
ripscope --verify [-d] [-f INDEX]
ripscope --project PATH
ripscope -h | --help
ripscope -V | --version

-h and -V are read where they appear, as cscope reads them: the first of them ends the command line, and what follows it is not read. Unlike cscope, both print to standard output and exit with status 0.

Options

Editor integrations

ripscope --project PATH tells an editor integration which project a file belongs to and where its index is, so that Vim, Neovim and Emacs find the same ones. It prints one line of JSON and changes nothing but making the cache directory:

$ ripscope --project src/main.c
{"index":"/home/me/.cache/ripscope/tool-1a2b3c4d5e6f7a8b.db","published":true,"root":"/home/me/src/tool","selection":["-k","-R"]}

• root is the nearest directory above PATH holding cscope.files, else the nearest Git repository, else the current directory when PATH is inside it, else PATH’s own directory (PATH itself when it is a directory). A Git repository and a current directory at the home directory or a file system root are skipped.
• index is in the cache directory, $XDG_CACHE_HOME/ripscope (else ~/.cache/ripscope) on Linux and %LOCALAPPDATA%\ripscope on Windows, or the absolute directory RIPSCOPE_CACHE_DIR names. Its name is the root’s name, with every character other than ASCII letters, digits, ., _ and - made _ and at most 40 of them, then - and the first 16 hexadecimal digits of the SHA-256 of the root’s path. On Windows that path has forward slashes and is in lower case, by Unicode’s full lowercase mapping (Rust’s str::to_lowercase, which also applies the final-sigma rule).
• selection holds the arguments an index build (-b) or a session in root takes: -k -i cscope.files, -k -R, or -k alone where the root is the home directory or a file system root.
• published says whether the index has a published revision made with that selection. An index build that stopped before publishing leaves one that has none, and adding or removing cscope.files changes the selection.

Environment

Exit status

A successful index build prints nothing, except a line on standard error for each named file it cannot find or read.

Differences from cscope

Ripscope keeps cscope’s line-oriented query protocol, with its own C scanner, per-occurrence query contexts and transactional index updates. This page explains the deliberate differences and points to the inputs that show them.

Compatibility with cscope and correctness against written C are checked separately. The evidence index names the inputs and checks behind each difference, and the limitations page lists what Ripscope does not read.

Updates and index safety

Run these checks with cargo test --locked. An unchanged stored index and a live text search can show different source states, and stored and live queries explains when to update.

Corrections: reading C where cscope misreads it

A Correction changes the reading of a specific written construct. Each keeps the reference observation and the intended reading side by side (ADR 0002). The scanner does not expand macros or resolve types, so an ambiguous construct can still lose a correct reading. The recognition limits list those cases.

Examples with source and paired captures:

Other Corrections cover atomic types, attributes, directive and macro boundaries, initializer entries, function heads and typedef decorations. Their rules and the ambiguous shapes they leave alone are in how Ripscope reads C. The evidence guide tells reference captures, intended expectations, open readings and disabled candidates apart.

Assignment search

Field 9 includes supported array initializers, direct named subscript stores and direct named prefix and postfix increments and decrements. It reports written sites, including macro bodies and unevaluated operands, whether or not they run, and does not resolve pointer aliases. The paired subscript-store source and named-mutation source have reference and intended captures beside them. ADR 0012 gives the exact recognition boundary, and tests/assignment_cli.rs checks the query interface.

Query results

cscope’s sequential and inverted-index searches can give different rows. Ripscope uses one set of query semantics: it reads names in order and gives each occurrence the context it sits in within its file (ADR 0010).

The five synthetic query-project groups keep their source files, patterns, cscope commands, sequential and inverted-index rows, diagnostics and exit statuses together. The semantics capture shows these reference differences. tests/intended/mod.rs checks the product’s intended answers, and quality and compatibility describes the separate baseline and product checks.

Patterns, bytes and displayed text

• Patterns use the documented regular-expression dialect. Ripscope anchors a definition-query alternation as a whole and refuses unsupported expressions with a diagnostic. A pattern can contain up to 4,096 bytes.
• Names are stored, matched and shown whole, including names beyond cscope’s 250-byte buffer. The long-name reference observation and ADR 0004 cover this case, where Ripscope defines its own behavior.
• Stored rows preserve UTF-8 and display control bytes visibly as \xHH. Live text-search rows keep tabs and CR LF endings, while escaping other control bytes. On a Windows console, bytes that are not UTF-8 are escaped too.
• Editor row parsers written for cscope can split paths at spaces. The JSON interface carries exact path and line bytes, and the Neovim plugin uses it.

Independent checks

Independent written-source labels check C89, C99, C11 and policy fixtures. They keep their expectations even where the product misses a name or invents a call. The zlib header fixture records its source and the product revision it was made with. Search times and answer comparisons on real projects are on the benchmarks page.

The best check is the navigation you need in your own project. Please report an unexpected difference with the source, exact commands and program versions.

Not supported

• cscope’s interactive terminal interface and field 5 text-changing features. In line mode, field 5 is a text search, as in cscope.
• Reading or writing cscope databases.
• -T and -s, which would change the answers. They are refused rather than ignored.

-c, -p N and -F FILE change nothing in line mode, so Ripscope accepts and ignores them, as it does -q, -e, -U and -v (see the command line).

Ripscope is an independent project and is not affiliated with cscope. cscope’s interface and observable behavior are credited in the cscope notice.

Limitations

This reference describes Ripscope’s supported platforms and C reading. See the roadmap for what comes next.

Language and analysis

• C only. extern "C" blocks and #ifdef __cplusplus wrappers in C headers are read as C.
• cscope’s reading, with Corrections. The analyzer reads C as cscope does, without preprocessing. Every #if branch is indexed as written, and names are recognised by their shape, not resolved by a compiler. Where cscope misreads common constructs, Corrections read them correctly. Other misreadings of cscope’s remain.
• Every readable file is indexed. Code the analyzer cannot read well costs accuracy only where it is.
• Includes. Only literal #include "..." and #include <...> directives are followed. A computed include such as #include MACRO is not followed, as in cscope.

Queries and output

• Contexts are worked out within each file from the names as written. Where alternative function heads under #if share one body, a call has only the last head as its caller. See Differences from cscope.
• Case-insensitive matching (-C) folds ASCII letters only.
• A query with -d on an index that another version of Ripscope made leaves out the files whose stored analysis it cannot read, and says how many, until the index is rebuilt with -bu. Only fields 0 to 3, 8 and 9 read stored analyses, so field 7 still lists those files and text searches read them, without a warning. Without -d a query analyses them again.
• Vim and xcscope split rows at spaces, so paths with spaces break their parsing, as with cscope. The JSON interface keeps such paths whole, and the Neovim plugin uses it.
• A query for an exact name reads the blocks of lines that hold it and, for a matching function or macro, the rest of its body. A common name can occur in many blocks. A regular expression or a -C name pattern in fields 0 to 3 and 9 first checks every distinct indexed name, then reads the blocks containing matches, so a broad pattern can cost much more work than an uncommon exact name.

Platforms and storage

• x86-64 Linux and x86-64 Windows. No macOS or ARM64 builds.
• The index must be on local storage. Network, cluster and shared-folder file systems, WSL’s view of Windows drives, FUSE mounts other than a block device’s (fuseblk, such as ntfs-3g) and Windows shares are refused. gocryptfs or mergerfs over a local disk are refused too. In the folders the OneDrive environment variables name, an index build that makes the index warns that OneDrive may lock or copy it. SharePoint and Teams libraries OneDrive synchronises outside those folders, other sync clients’ folders, and on Linux those of sync clients that are not FUSE mounts look local and get no warning, though their client may lock or copy an index there too.
• On Windows an index’s path cannot hold : after its drive (-f file:i.db), which would name a stream of another file. Such a path is refused.
• An index path that is a symbolic link stands for the file the link names, as SQLite reads it. Its log files, the check of where it lives and a rebuild of the index are that file’s, and the link stays. A link to nothing is refused.
• Queries need write access to the index’s directory, because a reader creates SQLite’s shared-memory file (INDEX-shm) beside the index. An index on read-only storage, or in a directory you cannot write, cannot be queried, even with -d, unless SQLite’s files are already there, and the message says so. Copy such an index somewhere writable and give it with -f.
• An index file you cannot write, in a directory you can, is answered from as it is. A query or session says so and skips its update, and an index build fails.
• On Unix, SQLite gives the files it makes the index file’s permissions, so a reader who cannot write the index leaves them read-only. An update by a user who may write the index and owns them makes them writable again. If another user left them, queries answer from the index as it is, with a note naming the file, and an index build fails, until that user makes them writable. A group shares an index through a setgid directory or a default ACL (see Sharing an index).
• SQLite’s log files beside an index (INDEX-wal, INDEX-shm) must be plain files. A link, a file with another name, a directory or a FIFO there refuses the index, for queries as for index builds, since SQLite would write through it. Remove it to use the index. A rollback journal (INDEX-journal), which an index never has, is removed before the index is opened.
• Use an index from one machine only. SQLite’s write-ahead log is unsafe across machines, and a query from another machine over NFS or a share is not refused.
• An index holds the text of the lines that hold symbols in the files it covers, so anyone who can read the index can read those lines.
• On Windows an update compares a file’s size, modification and creation times and identity. An edit made in place that keeps the size and restores the modification time is missed. --verify or an index build with -bu reads every file and catches it. Editors that save by replacing the file change its identity and are noticed.

Tools and integrations

• No interactive terminal interface. Use an editor integration or the command line.
• On Windows, Emacs command arguments must fit the active Windows ANSI code page, and unsupported characters are refused. Its native index build uses Ripscope’s file discovery rules. xcscope’s suffix and directory-exclusion settings apply only on Linux.
• Editor integrations are tested on specific versions, listed on each editor’s page.

Comparison with other tools

Ripscope is for C navigation through cscope-style queries: definitions, callers, callees, assignments and includes, from the editor you already use. It works on written source without a compiler, preprocessor or compile database.

Different tools serve different workflows. The links below describe each tool in its own documentation; this is not a benchmark or a complete feature matrix.

Updates and analysis in Ripscope

Ripscope reads all written #if branches and does not resolve types or arbitrary macro expansions. That can help when inspecting unfamiliar C without configuring a build, while leaving recognition limits that a compiler-based tool can approach differently.

An ordinary Refresh detects changes from size, file times and identity, and hashes recently modified files. It does not hash every source on every update. On Windows, an in-place edit that keeps its size and restores modification time can be missed; --verify or -bu reads every file. Atomic publication guarantees a complete index revision for a query, not that every stored query always reads the latest source bytes. See stored and live fields.

Legacy Vim and xcscope row parsers split paths at spaces. Ripscope’s JSON interface, used by its Neovim adapter, preserves exact path and line bytes. Choose the integration that fits your paths and editor.

The search benchmarks compare Ripscope, cscope and cscope -q on three pinned C selections, with timing and source-backed answer judgments. The proof page shows further bounded behavior evidence and its limits.

Benchmarks

The search-time tables below come from the 18 and 19 October 2026 measurement of the 0.1.0 release candidate, Ripscope revision 2fdce59. The Linux kernel selection comes first, followed by Redis and zlib. Both repetitions and both platforms are shown separately, and every time and comparison note comes from that measurement.

On Linux, with the kernel selection, symbol, definition and caller lookups take about a tenth of a millisecond, hundreds of times faster than plain cscope. Even against cscope -q, Ripscope runs text searches about 6× faster, egrep 10× and assignment searches over 70×. A win needs a clear timing difference and an equivalent or source-confirmed better answer.

After a normal startup a Ripscope Session watches its sources and refreshes on its own. On Linux that costs nothing measurable per search. On Windows each search first checks a marker file, about 0.3 to 0.5 ms, which lets cscope -q answer the three lookups of a name nobody defines faster there.

Search times

Times are milliseconds. First means a query’s first pass after Session startup, after any preceding queries. Later means a subsequent pass within that Session. Search times exclude Session startup. “Normal startup” includes each tool’s own freshness checks before the Session becomes ready. “Updates skipped” opens existing indexes without those checks.

Without JavaScript, expand the labelled tables to choose a comparison. Green marks a Ripscope win, red a cscope win, and yellow uncertain timing or a timing/quality tradeoff. Every cell also states its conclusion in words. Follow an answer-quality link for the source-backed explanation.