rust search rust grep
https://github.com/BurntSushi/ripgrep
GitHub - BurntSushi/ripgrep: ripgrep recursively searches directories for a regex pattern while respecting your gitignore
2023-01-15
BurntSushi
<div><div>
 <article><h2>ripgrep (rg)</h2>
<p>ripgrep is a line-oriented search tool that recursively searches the current
directory for a regex pattern. By default, ripgrep will respect gitignore rules
and automatically skip hidden files/directories and binary files. (To disable
all automatic filtering by default, use <code>rg -uuu</code>.) ripgrep has first class
support on Windows, macOS and Linux, with binary downloads available for <a href="https://github.com/BurntSushi/ripgrep/releases">every
release</a>. ripgrep is similar to
other popular search tools like The Silver Searcher, ack and grep.</p>
<p><a href="https://github.com/BurntSushi/ripgrep/actions"></a>
<a href="https://crates.io/crates/ripgrep"></a>
<a href="https://repology.org/project/ripgrep/badges"></a></p>
<p>Dual-licensed under MIT or the <a href="https://unlicense.org/">UNLICENSE</a>.</p>
<h3>CHANGELOG</h3>
<p>Please see the <a href="/BurntSushi/ripgrep/blob/master/CHANGELOG.md">CHANGELOG</a> for a release history.</p>
<h3>Documentation quick links</h3>
<ul>
<li><a href="#installation">Installation</a></li>
<li><a href="/BurntSushi/ripgrep/blob/master/GUIDE.md">User Guide</a></li>
<li><a href="/BurntSushi/ripgrep/blob/master/FAQ.md">Frequently Asked Questions</a></li>
<li><a href="https://docs.rs/regex/1/regex/#syntax">Regex syntax</a></li>
<li><a href="/BurntSushi/ripgrep/blob/master/GUIDE.md#configuration-file">Configuration files</a></li>
<li><a href="/BurntSushi/ripgrep/blob/master/FAQ.md#complete">Shell completions</a></li>
<li><a href="#building">Building</a></li>
<li><a href="#translations">Translations</a></li>
</ul>
<h3>Screenshot of search results</h3>
<p><a href="https://burntsushi.net/stuff/ripgrep1.png"></a></p>
<h3>Quick examples comparing tools</h3>
<p>This example searches the entire
<a href="https://github.com/BurntSushi/linux">Linux kernel source tree</a>
(after running <code>make defconfig &amp;&amp; make -j8</code>) for <code>[A-Z]+_SUSPEND</code>, where
all matches must be words. Timings were collected on a system with an Intel
i7-6900K 3.2 GHz.</p>
<p>Please remember that a single benchmark is never enough! See my
<a href="https://blog.burntsushi.net/ripgrep/">blog post on ripgrep</a>
for a very detailed comparison with more benchmarks and analysis.</p>
<table>
<thead>
<tr>
<th>Tool</th>
<th>Command</th>
<th>Line count</th>
<th>Time</th>
</tr>
</thead>
<tbody>
<tr>
<td>ripgrep (Unicode)</td>
<td><code>rg -n -w '[A-Z]+_SUSPEND'</code></td>
<td>452</td>
<td><strong>0.136s</strong></td>
</tr>
<tr>
<td><a href="https://www.kernel.org/pub/software/scm/git/docs/git-grep.html">git grep</a></td>
<td><code>git grep -P -n -w '[A-Z]+_SUSPEND'</code></td>
<td>452</td>
<td>0.348s</td>
</tr>
<tr>
<td><a href="https://github.com/Genivia/ugrep">ugrep (Unicode)</a></td>
<td><code>ugrep -r --ignore-files --no-hidden -I -w '[A-Z]+_SUSPEND'</code></td>
<td>452</td>
<td>0.506s</td>
</tr>
<tr>
<td><a href="https://github.com/ggreer/the_silver_searcher">The Silver Searcher</a></td>
<td><code>ag -w '[A-Z]+_SUSPEND'</code></td>
<td>452</td>
<td>0.654s</td>
</tr>
<tr>
<td><a href="https://www.kernel.org/pub/software/scm/git/docs/git-grep.html">git grep</a></td>
<td><code>LC_ALL=C git grep -E -n -w '[A-Z]+_SUSPEND'</code></td>
<td>452</td>
<td>1.150s</td>
</tr>
<tr>
<td><a href="https://github.com/beyondgrep/ack3">ack</a></td>
<td><code>ack -w '[A-Z]+_SUSPEND'</code></td>
<td>452</td>
<td>4.054s</td>
</tr>
<tr>
<td><a href="https://www.kernel.org/pub/software/scm/git/docs/git-grep.html">git grep (Unicode)</a></td>
<td><code>LC_ALL=en_US.UTF-8 git grep -E -n -w '[A-Z]+_SUSPEND'</code></td>
<td>452</td>
<td>4.205s</td>
</tr>
</tbody>
</table>
<p>Here's another benchmark on the same corpus as above that disregards gitignore
files and searches with a whitelist instead. The corpus is the same as in the
previous benchmark, and the flags passed to each command ensure that they are
doing equivalent work:</p>
<table>
<thead>
<tr>
<th>Tool</th>
<th>Command</th>
<th>Line count</th>
<th>Time</th>
</tr>
</thead>
<tbody>
<tr>
<td>ripgrep</td>
<td><code>rg -uuu -tc -n -w '[A-Z]+_SUSPEND'</code></td>
<td>388</td>
<td><strong>0.096s</strong></td>
</tr>
<tr>
<td><a href="https://github.com/Genivia/ugrep">ugrep</a></td>
<td><code>ugrep -r -n --include='*.c' --include='*.h' -w '[A-Z]+_SUSPEND'</code></td>
<td>388</td>
<td>0.493s</td>
</tr>
<tr>
<td><a href="https://www.gnu.org/software/grep/">GNU grep</a></td>
<td><code>egrep -r -n --include='*.c' --include='*.h' -w '[A-Z]+_SUSPEND'</code></td>
<td>388</td>
<td>0.806s</td>
</tr>
</tbody>
</table>
<p>And finally, a straight-up comparison between ripgrep, ugrep and GNU grep on a
single large file cached in memory
(~13GB, <a href="http://opus.nlpl.eu/download.php?f=OpenSubtitles/v2018/mono/OpenSubtitles.raw.en.gz"><code>OpenSubtitles.raw.en.gz</code></a>):</p>
<table>
<thead>
<tr>
<th>Tool</th>
<th>Command</th>
<th>Line count</th>
<th>Time</th>
</tr>
</thead>
<tbody>
<tr>
<td>ripgrep</td>
<td><code>rg -w 'Sherlock [A-Z]\w+'</code></td>
<td>7882</td>
<td><strong>2.769s</strong></td>
</tr>
<tr>
<td><a href="https://github.com/Genivia/ugrep">ugrep</a></td>
<td><code>ugrep -w 'Sherlock [A-Z]\w+'</code></td>
<td>7882</td>
<td>6.802s</td>
</tr>
<tr>
<td><a href="https://www.gnu.org/software/grep/">GNU grep</a></td>
<td><code>LC_ALL=en_US.UTF-8 egrep -w 'Sherlock [A-Z]\w+'</code></td>
<td>7882</td>
<td>9.027s</td>
</tr>
</tbody>
</table>
<p>In the above benchmark, passing the <code>-n</code> flag (for showing line numbers)
increases the times to <code>3.423s</code> for ripgrep and <code>13.031s</code> for GNU grep. ugrep
times are unaffected by the presence or absence of <code>-n</code>.</p>
<h3>Why should I use ripgrep?</h3>
<ul>
<li>It can replace many use cases served by other search tools
because it contains most of their features and is generally faster. (See
<a href="/BurntSushi/ripgrep/blob/master/FAQ.md#posix4ever">the FAQ</a> for more details on whether ripgrep can truly
replace grep.)</li>
<li>Like other tools specialized to code search, ripgrep defaults to
<a href="/BurntSushi/ripgrep/blob/master/GUIDE.md#recursive-search">recursive search</a> and does <a href="/BurntSushi/ripgrep/blob/master/GUIDE.md#automatic-filtering">automatic
filtering</a>. Namely, ripgrep won't search files
ignored by your <code>.gitignore</code>/<code>.ignore</code>/<code>.rgignore</code> files, it won't search
hidden files and it won't search binary files. Automatic filtering can be
disabled with <code>rg -uuu</code>.</li>
<li>ripgrep can <a href="/BurntSushi/ripgrep/blob/master/GUIDE.md#manual-filtering-file-types">search specific types of files</a>.
For example, <code>rg -tpy foo</code> limits your search to Python files and <code>rg -Tjs foo</code> excludes JavaScript files from your search. ripgrep can be taught about
new file types with custom matching rules.</li>
<li>ripgrep supports many features found in <code>grep</code>, such as showing the context
of search results, searching multiple patterns, highlighting matches with
color and full Unicode support. Unlike GNU grep, ripgrep stays fast while
supporting Unicode (which is always on).</li>
<li>ripgrep has optional support for switching its regex engine to use PCRE2.
Among other things, this makes it possible to use look-around and
backreferences in your patterns, which are not supported in ripgrep's default
regex engine. PCRE2 support can be enabled with <code>-P/--pcre2</code> (use PCRE2
always) or <code>--auto-hybrid-regex</code> (use PCRE2 only if needed). An alternative
syntax is provided via the <code>--engine (default|pcre2|auto-hybrid)</code> option.</li>
<li>ripgrep has <a href="/BurntSushi/ripgrep/blob/master/GUIDE.md#replacements">rudimentary support for replacements</a>,
which permit rewriting output based on what was matched.</li>
<li>ripgrep supports <a href="/BurntSushi/ripgrep/blob/master/GUIDE.md#file-encoding">searching files in text encodings</a>
other than UTF-8, such as UTF-16, latin-1, GBK, EUC-JP, Shift_JIS and more.
(Some support for automatically detecting UTF-16 is provided. Other text
encodings must be specifically specified with the <code>-E/--encoding</code> flag.)</li>
<li>ripgrep supports searching files compressed in a common format (brotli,
bzip2, gzip, lz4, lzma, xz, or zstandard) with the <code>-z/--search-zip</code> flag.</li>
<li>ripgrep supports
<a href="/BurntSushi/ripgrep/blob/master/GUIDE.md#preprocessor">arbitrary input preprocessing filters</a>
which could be PDF text extraction, less supported decompression, decrypting,
automatic encoding detection and so on.</li>
<li>ripgrep can be configured via a
<a href="/BurntSushi/ripgrep/blob/master/GUIDE.md#configuration-file">configuration file</a>.</li>
</ul>
<p>In other words, use ripgrep if you like speed, filtering by default, fewer
bugs and Unicode support.</p>
<h3>Why shouldn't I use ripgrep?</h3>
<p>Despite initially not wanting to add every feature under the sun to ripgrep,
over time, ripgrep has grown support for most features found in other file
searching tools. This includes searching for results spanning across multiple
lines, and opt-in support for PCRE2, which provides look-around and
backreference support.</p>
<p>At this point, the primary reasons not to use ripgrep probably consist of one
or more of the following:</p>
<ul>
<li>You need a portable and ubiquitous tool. While ripgrep works on Windows,
macOS and Linux, it is not ubiquitous and it does not conform to any
standard such as POSIX. The best tool for this job is good old grep.</li>
<li>There still exists some other feature (or bug) not listed in this README that
you rely on that's in another tool that isn't in ripgrep.</li>
<li>There is a performance edge case where ripgrep doesn't do well where another
tool does do well. (Please file a bug report!)</li>
<li>ripgrep isn't possible to install on your machine or isn't available for your
platform. (Please file a bug report!)</li>
</ul>
<h3>Is it really faster than everything else?</h3>
<p>Generally, yes. A large number of benchmarks with detailed analysis for each is
<a href="https://blog.burntsushi.net/ripgrep/">available on my blog</a>.</p>
<p>Summarizing, ripgrep is fast because:</p>
<ul>
<li>It is built on top of
<a href="https://github.com/rust-lang/regex">Rust's regex engine</a>.
Rust's regex engine uses finite automata, SIMD and aggressive literal
optimizations to make searching very fast. (PCRE2 support can be opted into
with the <code>-P/--pcre2</code> flag.)</li>
<li>Rust's regex library maintains performance with full Unicode support by
building UTF-8 decoding directly into its deterministic finite automaton
engine.</li>
<li>It supports searching with either memory maps or by searching incrementally
with an intermediate buffer. The former is better for single files and the
latter is better for large directories. ripgrep chooses the best searching
strategy for you automatically.</li>
<li>Applies your ignore patterns in <code>.gitignore</code> files using a
<a href="https://docs.rs/regex/1/regex/struct.RegexSet.html"><code>RegexSet</code></a>.
That means a single file path can be matched against multiple glob patterns
simultaneously.</li>
<li>It uses a lock-free parallel recursive directory iterator, courtesy of
<a href="https://docs.rs/crossbeam"><code>crossbeam</code></a> and
<a href="https://docs.rs/ignore"><code>ignore</code></a>.</li>
</ul>
<h3>Feature comparison</h3>
<p>Andy Lester, author of <a href="https://beyondgrep.com/">ack</a>, has published an
excellent table comparing the features of ack, ag, git-grep, GNU grep and
ripgrep: <a href="https://beyondgrep.com/feature-comparison/">https://beyondgrep.com/feature-comparison/</a></p>
<p>Note that ripgrep has grown a few significant new features recently that
are not yet present in Andy's table. This includes, but is not limited to,
configuration files, passthru, support for searching compressed files,
multiline search and opt-in fancy regex support via PCRE2.</p>
<h3>Installation</h3>
<p>The binary name for ripgrep is <code>rg</code>.</p>
<p><strong><a href="https://github.com/BurntSushi/ripgrep/releases">Archives of precompiled binaries for ripgrep are available for Windows,
macOS and Linux.</a></strong> Linux and
Windows binaries are static executables. Users of platforms not explicitly
mentioned below are advised to download one of these archives.</p>
<p>If you're a <strong>macOS Homebrew</strong> or a <strong>Linuxbrew</strong> user, then you can install
ripgrep from homebrew-core:</p>
<p>If you're a <strong>MacPorts</strong> user, then you can install ripgrep from the
<a href="https://www.macports.org/ports.php?by=name&amp;substr=ripgrep">official ports</a>:</p>
<div><pre><code>$ sudo port install ripgrep
</code></pre></div>
<p>If you're a <strong>Windows Chocolatey</strong> user, then you can install ripgrep from the
<a href="https://chocolatey.org/packages/ripgrep">official repo</a>:</p>
<p>If you're a <strong>Windows Scoop</strong> user, then you can install ripgrep from the
<a href="https://github.com/ScoopInstaller/Main/blob/master/bucket/ripgrep.json">official bucket</a>:</p>
<p>If you're an <strong>Arch Linux</strong> user, then you can install ripgrep from the official repos:</p>
<p>If you're a <strong>Gentoo</strong> user, you can install ripgrep from the
<a href="https://packages.gentoo.org/packages/sys-apps/ripgrep">official repo</a>:</p>
<div><pre><code>$ emerge sys-apps/ripgrep
</code></pre></div>
<p>If you're a <strong>Fedora</strong> user, you can install ripgrep from official
repositories.</p>
<div><pre><code>$ sudo dnf install ripgrep
</code></pre></div>
<p>If you're an <strong>openSUSE</strong> user, ripgrep is included in <strong>openSUSE Tumbleweed</strong>
and <strong>openSUSE Leap</strong> since 15.1.</p>
<div><pre><code>$ sudo zypper install ripgrep
</code></pre></div>
<p>If you're a <strong>RHEL/CentOS 7/8</strong> user, you can install ripgrep from
<a href="https://copr.fedorainfracloud.org/coprs/carlwgeorge/ripgrep/">copr</a>:</p>
<div><pre><code>$ sudo yum-config-manager --add-repo=https://copr.fedorainfracloud.org/coprs/carlwgeorge/ripgrep/repo/epel-7/carlwgeorge-ripgrep-epel-7.repo
$ sudo yum install ripgrep
</code></pre></div>
<p>If you're a <strong>Nix</strong> user, you can install ripgrep from
<a href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/text/ripgrep/default.nix">nixpkgs</a>:</p>
<div><pre><code>$ nix-env --install ripgrep
$ # (Or using the attribute name, which is also ripgrep.)
</code></pre></div>
<p>If you're a <strong>Guix</strong> user, you can install ripgrep from the official
package collection:</p>
<p>If you're a <strong>Debian</strong> user (or a user of a Debian derivative like <strong>Ubuntu</strong>),
then ripgrep can be installed using a binary <code>.deb</code> file provided in each
<a href="https://github.com/BurntSushi/ripgrep/releases">ripgrep release</a>.</p>
<div><pre><code>$ curl -LO https://github.com/BurntSushi/ripgrep/releases/download/13.0.0/ripgrep_13.0.0_amd64.deb
$ sudo dpkg -i ripgrep_13.0.0_amd64.deb
</code></pre></div>
<p>If you run Debian Buster (currently Debian stable) or Debian sid, ripgrep is
<a href="https://tracker.debian.org/pkg/rust-ripgrep">officially maintained by Debian</a>.</p>
<div><pre><code>$ sudo apt-get install ripgrep
</code></pre></div>
<p>If you're an <strong>Ubuntu Cosmic (18.10)</strong> (or newer) user, ripgrep is
<a href="https://launchpad.net/ubuntu/+source/rust-ripgrep">available</a> using the same
packaging as Debian:</p>
<div><pre><code>$ sudo apt-get install ripgrep
</code></pre></div>
<p>(N.B. Various snaps for ripgrep on Ubuntu are also available, but none of them
seem to work right and generate a number of very strange bug reports that I
don't know how to fix and don't have the time to fix. Therefore, it is no
longer a recommended installation option.)</p>
<p>If you're a <strong>FreeBSD</strong> user, then you can install ripgrep from the
<a href="https://www.freshports.org/textproc/ripgrep/">official ports</a>:</p>
<p>If you're an <strong>OpenBSD</strong> user, then you can install ripgrep from the
<a href="https://openports.se/textproc/ripgrep">official ports</a>:</p>
<p>If you're a <strong>NetBSD</strong> user, then you can install ripgrep from
<a href="https://pkgsrc.se/textproc/ripgrep">pkgsrc</a>:</p>
<p>If you're a <strong>Haiku x86_64</strong> user, then you can install ripgrep from the
<a href="https://github.com/haikuports/haikuports/tree/master/sys-apps/ripgrep">official ports</a>:</p>
<p>If you're a <strong>Haiku x86_gcc2</strong> user, then you can install ripgrep from the
same port as Haiku x86_64 using the x86 secondary architecture build:</p>
<div><pre><code>$ pkgman install ripgrep_x86
</code></pre></div>
<p>If you're a <strong>Rust programmer</strong>, ripgrep can be installed with <code>cargo</code>.</p>
<ul>
<li>Note that the minimum supported version of Rust for ripgrep is <strong>1.65.0</strong>,
although ripgrep may work with older versions.</li>
<li>Note that the binary may be bigger than expected because it contains debug
symbols. This is intentional. To remove debug symbols and therefore reduce
the file size, run <code>strip</code> on the binary.</li>
</ul>
<h3>Building</h3>
<p>ripgrep is written in Rust, so you'll need to grab a
<a href="https://www.rust-lang.org/">Rust installation</a> in order to compile it.
ripgrep compiles with Rust 1.65.0 (stable) or newer. In general, ripgrep tracks
the latest stable release of the Rust compiler.</p>
<p>To build ripgrep:</p>
<div><pre><code>$ git clone https://github.com/BurntSushi/ripgrep
$ cd ripgrep
$ cargo build --release
$ ./target/release/rg --version
0.1.3
</code></pre></div>
<p>If you have a Rust nightly compiler and a recent Intel CPU, then you can enable
additional optional SIMD acceleration like so:</p>
<div><pre><code>RUSTFLAGS="-C target-cpu=native" cargo build --release --features 'simd-accel'
</code></pre></div>
<p>The <code>simd-accel</code> feature enables SIMD support in certain ripgrep dependencies
(responsible for transcoding). They are not necessary to get SIMD optimizations
for search; those are enabled automatically. Hopefully, some day, the
<code>simd-accel</code> feature will similarly become unnecessary. <strong>WARNING:</strong> Currently,
enabling this option can increase compilation times dramatically.</p>
<p>Finally, optional PCRE2 support can be built with ripgrep by enabling the
<code>pcre2</code> feature:</p>
<div><pre><code>$ cargo build --release --features 'pcre2'
</code></pre></div>
<p>(Tip: use <code>--features 'pcre2 simd-accel'</code> to also include compile time SIMD
optimizations, which will only work with a nightly compiler.)</p>
<p>Enabling the PCRE2 feature works with a stable Rust compiler and will
attempt to automatically find and link with your system's PCRE2 library via
<code>pkg-config</code>. If one doesn't exist, then ripgrep will build PCRE2 from source
using your system's C compiler and then statically link it into the final
executable. Static linking can be forced even when there is an available PCRE2
system library by either building ripgrep with the MUSL target or by setting
<code>PCRE2_SYS_STATIC=1</code>.</p>
<p>ripgrep can be built with the MUSL target on Linux by first installing the MUSL
library on your system (consult your friendly neighborhood package manager).
Then you just need to add MUSL support to your Rust toolchain and rebuild
ripgrep, which yields a fully static executable:</p>
<div><pre><code>$ rustup target add x86_64-unknown-linux-musl
$ cargo build --release --target x86_64-unknown-linux-musl
</code></pre></div>
<p>Applying the <code>--features</code> flag from above works as expected. If you want to
build a static executable with MUSL and with PCRE2, then you will need to have
<code>musl-gcc</code> installed, which might be in a separate package from the actual
MUSL library, depending on your Linux distribution.</p>
<h3>Running tests</h3>
<p>ripgrep is relatively well-tested, including both unit tests and integration
tests. To run the full test suite, use:</p>
<p>from the repository root.</p>
<h3>Vulnerability reporting</h3>
<p>For reporting a security vulnerability, please
<a href="https://blog.burntsushi.net/about/">contact Andrew Gallant</a>,
which has my email address and PGP public key if you wish to send an encrypted
message.</p>
<h3>Translations</h3>
<p>The following is a list of known translations of ripgrep's documentation. These
are unofficially maintained and may not be up to date.</p>
<ul>
<li><a href="https://github.com/chinanf-boy/ripgrep-zh#%E6%9B%B4%E6%96%B0-">Chinese</a></li>
<li><a href="https://github.com/UltiRequiem/traducciones/tree/master/ripgrep">Spanish</a></li>
</ul>
</article>
 </div>||||I|||| Skip to content
 Toggle navigation
 Sign up
 * Product
 + Actions
 Automate any workflow
 + Packages
 Host and manage packages
 + Security
 Find and fix vulnerabilities
 + Codespaces
 Instant dev environments
 + Copilot
 Write better code with AI
 + Code review
 Manage code changes
 + Issues
 Plan and track work
 + Discussions
 Collaborate outside of code
 + Explore
 + All features
 + Documentation
 + GitHub Skills
 + Blog
 * Solutions
 + For
 + Enterprise
 + Teams
 + Startups
 + Education
 + By Solution
 + CI/CD & Automation
 + DevOps
 + DevSecOps
 + Case Studies
 + Customer Stories
 + Resources
 * Open Source
 + GitHub Sponsors
 Fund open source developers
 + The ReadME Project
 GitHub community articles
 + Repositories
 + Topics
 + Trending
 + Collections
 * Pricing
 * In this repository All GitHub ↵
 Jump to ↵
 * No suggested jump to results
 * In this repository All GitHub ↵
 Jump to ↵
 * In this user All GitHub ↵
 Jump to ↵
 * In this repository All GitHub ↵
 Jump to ↵
 Sign in
 Sign up
 {{ message }}
 BurntSushi / ripgrep Public
 * Notifications
 * Fork 1.6k
 * Star 35.7k

 ripgrep recursively searches directories for a regex pattern while respecting your gitignore

 License

 Unlicense and 2 other licenses found

 Licenses found

 Unlicense
 UNLICENSE
 Unknown
 COPYING
 MIT
 LICENSE-MIT
 35.7k stars 1.6k forks
 Star
 Notifications
 * Code
 * Issues 134
 * Pull requests 57
 * Discussions
 * Actions
 * Security
 * Insights
 More
 * Code
 * Issues
 * Pull requests
 * Discussions
 * Actions
 * Security
 * Insights

 BurntSushi/ripgrep

 This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
 master
 Switch branches/tags
 Branches Tags
 Could not load branches
 Nothing to show
 {{ refName }} default
 View all branches
 Could not load tags
 Nothing to show
 {{ refName }} default
 View all tags

 Name already in use

 A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
 Cancel Create
 14 branches 200 tags
 Code
 * Local
 * Codespaces
 * Clone
 HTTPS GitHub CLI

 Use Git or checkout with SVN using the web URL.

 Work fast with our official CLI. Learn more.

 * Open with GitHub Desktop
 * Download ZIP

 Sign In Required

 Please sign in to use Codespaces.

 Launching GitHub Desktop

 If nothing happens, download GitHub Desktop and try again.

 Launching GitHub Desktop

 If nothing happens, download GitHub Desktop and try again.

 Launching Xcode

 If nothing happens, download Xcode and try again.

 Launching Visual Studio Code

 Your codespace will open once ready.

 There was a problem preparing your codespace, please try again.

 Latest commit

 BurntSushi ignore-0.4.20
 …
 fe97c0a Jan 15, 2023
 ignore-0.4.20
 fe97c0a

 Git stats

 * 1,725 commits

 Files

 Permalink
 Failed to load latest commit information.
 Type
 Name
 Latest commit message
 Commit time
 .cargo
 cargo: statically link binary on Windows/MSVC
 May 31, 2021 21:51
 .github
 msrv: bump to Rust 1.65.0
 November 14, 2022 07:56
 benchsuite
 benchsuite/runs: add another run of the benchmarks
 December 16, 2022 11:24
 ci
 ci: fix failing nightly-arm build on ci workflow
 March 21, 2022 08:59
 complete
 cli: add --field-{context,match}-separator flags
 May 31, 2021 21:51
 crates
 ignore-0.4.20
 January 15, 2023 08:21
 doc
 cli: add -. as short option for --hidden
 May 31, 2021 21:51
 pkg/ brew
 pkg: fix version number for 13.0.0 release
 June 15, 2021 10:30
 scripts
 scripts: add copy-examples
 September 7, 2018 12:27
 tests
 ignore: fix gitignore parsing bug for trailing \/
 June 14, 2022 10:40
 .gitignore
 gitignore: add HTML files generated by cargo -Z timings
 February 12, 2021 11:09
 .ignore
 ripgrep: add /.github/ to whitelist
 August 17, 2022 08:31
 CHANGELOG.md
 ignore: fix gitignore parsing bug for trailing \/
 June 14, 2022 10:40
 COPYING
 initial commit
 February 27, 2016 11:07
 Cargo.lock
 ignore-0.4.20
 January 15, 2023 08:21
 Cargo.toml
 deps: update to grep 0.2.11
 January 5, 2023 09:13
 Cross.toml
 ci: switch build to GitHub Actions
 February 20, 2020 16:07
 FAQ.md
 doc: add missing backtick in FAQ
 November 3, 2020 10:32
 GUIDE.md
 doc: add '-.' as short flag for '--hidden'
 August 10, 2022 08:03
 HomebrewFormula
 Make the repo a Homebrew Tap
 September 30, 2016 12:51
 LICENSE-MIT
 initial commit
 February 27, 2016 11:07
 README.md
 readme: update MSRV in README
 January 5, 2023 12:09
 RELEASE-CHECKLIST.md
 release: work around GitHub Actions weirdness
 June 12, 2021 08:40
 UNLICENSE
 initial commit
 February 27, 2016 11:07
 build.rs
 doc: fix egregious markup output
 May 13, 2020 08:13
 rustfmt.toml
 style: rustfmt everything
 February 17, 2020 19:24
 View code
 ripgrep (rg) CHANGELOG Documentation quick links Screenshot of search results Quick examples comparing tools Why should I use ripgrep? Why shouldn't I use ripgrep? Is it really faster than everything else? Feature comparison Installation Building Running tests Vulnerability reporting Translations

 README.md

 ripgrep (rg)

 ripgrep is a line-oriented search tool that recursively searches the current directory for a regex pattern. By default, ripgrep will respect gitignore rules and automatically skip hidden files/directories and binary files. (To disable all automatic filtering by default, use rg -uuu.) ripgrep has first class support on Windows, macOS and Linux, with binary downloads available for every release. ripgrep is similar to other popular search tools like The Silver Searcher, ack and grep.

 Dual-licensed under MIT or the UNLICENSE.

 CHANGELOG

 Please see the CHANGELOG for a release history.

 Documentation quick links

 * Installation
 * User Guide
 * Frequently Asked Questions
 * Regex syntax
 * Configuration files
 * Shell completions
 * Building
 * Translations

 Screenshot of search results

 Quick examples comparing tools

 This example searches the entire Linux kernel source tree (after running make defconfig && make -j8) for [A-Z]+_SUSPEND, where all matches must be words. Timings were collected on a system with an Intel i7-6900K 3.2 GHz.

 Please remember that a single benchmark is never enough! See my blog post on ripgrep for a very detailed comparison with more benchmarks and analysis.

 Tool Command Line count Time 
 ripgrep (Unicode) rg -n -w '[A-Z]+_SUSPEND' 452 0.136s
 git grep git grep -P -n -w '[A-Z]+_SUSPEND' 452 0.348s
 ugrep (Unicode) ugrep -r --ignore-files --no-hidden -I -w '[A-Z]+_SUSPEND' 452 0.506s
 The Silver Searcher ag -w '[A-Z]+_SUSPEND' 452 0.654s
 git grep LC_ALL=C git grep -E -n -w '[A-Z]+_SUSPEND' 452 1.150s
 ack ack -w '[A-Z]+_SUSPEND' 452 4.054s
 git grep (Unicode) LC_ALL=en_US.UTF-8 git grep -E -n -w '[A-Z]+_SUSPEND' 452 4.205s
 

 Here's another benchmark on the same corpus as above that disregards gitignore files and searches with a whitelist instead. The corpus is the same as in the previous benchmark, and the flags passed to each command ensure that they are doing equivalent work:

 Tool Command Line count Time 
 ripgrep rg -uuu -tc -n -w '[A-Z]+_SUSPEND' 388 0.096s
 ugrep ugrep -r -n --include='*.c' --include='*.h' -w '[A-Z]+_SUSPEND' 388 0.493s
 GNU grep egrep -r -n --include='*.c' --include='*.h' -w '[A-Z]+_SUSPEND' 388 0.806s
 

 And finally, a straight-up comparison between ripgrep, ugrep and GNU grep on a single large file cached in memory (~13GB, OpenSubtitles.raw.en.gz):

 Tool Command Line count Time 
 ripgrep rg -w 'Sherlock [A-Z]\w+' 7882 2.769s
 ugrep ugrep -w 'Sherlock [A-Z]\w+' 7882 6.802s
 GNU grep LC_ALL=en_US.UTF-8 egrep -w 'Sherlock [A-Z]\w+' 7882 9.027s
 

 In the above benchmark, passing the -n flag (for showing line numbers) increases the times to 3.423s for ripgrep and 13.031s for GNU grep. ugrep times are unaffected by the presence or absence of -n.

 Why should I use ripgrep?

 * It can replace many use cases served by other search tools because it contains most of their features and is generally faster. (See the FAQ for more details on whether ripgrep can truly replace grep.)
 * Like other tools specialized to code search, ripgrep defaults to recursive search and does automatic filtering. Namely, ripgrep won't search files ignored by your .gitignore/.ignore/.rgignore files, it won't search hidden files and it won't search binary files. Automatic filtering can be disabled with rg -uuu.
 * ripgrep can search specific types of files. For example, rg -tpy foo limits your search to Python files and rg -Tjs foo excludes JavaScript files from your search. ripgrep can be taught about new file types with custom matching rules.
 * ripgrep supports many features found in grep, such as showing the context of search results, searching multiple patterns, highlighting matches with color and full Unicode support. Unlike GNU grep, ripgrep stays fast while supporting Unicode (which is always on).
 * ripgrep has optional support for switching its regex engine to use PCRE2. Among other things, this makes it possible to use look-around and backreferences in your patterns, which are not supported in ripgrep's default regex engine. PCRE2 support can be enabled with -P/--pcre2 (use PCRE2 always) or --auto-hybrid-regex (use PCRE2 only if needed). An alternative syntax is provided via the --engine (default|pcre2|auto-hybrid) option.
 * ripgrep has rudimentary support for replacements, which permit rewriting output based on what was matched.
 * ripgrep supports searching files in text encodings other than UTF-8, such as UTF-16, latin-1, GBK, EUC-JP, Shift_JIS and more. (Some support for automatically detecting UTF-16 is provided. Other text encodings must be specifically specified with the -E/--encoding flag.)
 * ripgrep supports searching files compressed in a common format (brotli, bzip2, gzip, lz4, lzma, xz, or zstandard) with the -z/--search-zip flag.
 * ripgrep supports arbitrary input preprocessing filters which could be PDF text extraction, less supported decompression, decrypting, automatic encoding detection and so on.
 * ripgrep can be configured via a configuration file.

 In other words, use ripgrep if you like speed, filtering by default, fewer bugs and Unicode support.

 Why shouldn't I use ripgrep?

 Despite initially not wanting to add every feature under the sun to ripgrep, over time, ripgrep has grown support for most features found in other file searching tools. This includes searching for results spanning across multiple lines, and opt-in support for PCRE2, which provides look-around and backreference support.

 At this point, the primary reasons not to use ripgrep probably consist of one or more of the following:

 * You need a portable and ubiquitous tool. While ripgrep works on Windows, macOS and Linux, it is not ubiquitous and it does not conform to any standard such as POSIX. The best tool for this job is good old grep.
 * There still exists some other feature (or bug) not listed in this README that you rely on that's in another tool that isn't in ripgrep.
 * There is a performance edge case where ripgrep doesn't do well where another tool does do well. (Please file a bug report!)
 * ripgrep isn't possible to install on your machine or isn't available for your platform. (Please file a bug report!)

 Is it really faster than everything else?

 Generally, yes. A large number of benchmarks with detailed analysis for each is available on my blog.

 Summarizing, ripgrep is fast because:

 * It is built on top of Rust's regex engine. Rust's regex engine uses finite automata, SIMD and aggressive literal optimizations to make searching very fast. (PCRE2 support can be opted into with the -P/--pcre2 flag.)
 * Rust's regex library maintains performance with full Unicode support by building UTF-8 decoding directly into its deterministic finite automaton engine.
 * It supports searching with either memory maps or by searching incrementally with an intermediate buffer. The former is better for single files and the latter is better for large directories. ripgrep chooses the best searching strategy for you automatically.
 * Applies your ignore patterns in .gitignore files using a RegexSet. That means a single file path can be matched against multiple glob patterns simultaneously.
 * It uses a lock-free parallel recursive directory iterator, courtesy of crossbeam and ignore.

 Feature comparison

 Andy Lester, author of ack, has published an excellent table comparing the features of ack, ag, git-grep, GNU grep and ripgrep: https://beyondgrep.com/feature-comparison/

 Note that ripgrep has grown a few significant new features recently that are not yet present in Andy's table. This includes, but is not limited to, configuration files, passthru, support for searching compressed files, multiline search and opt-in fancy regex support via PCRE2.

 Installation

 The binary name for ripgrep is rg.

 Archives of precompiled binaries for ripgrep are available for Windows, macOS and Linux. Linux and Windows binaries are static executables. Users of platforms not explicitly mentioned below are advised to download one of these archives.

 If you're a macOS Homebrew or a Linuxbrew user, then you can install ripgrep from homebrew-core:

 $ brew install ripgrep
 

 If you're a MacPorts user, then you can install ripgrep from the official ports:

 $ sudo port install ripgrep
 

 If you're a Windows Chocolatey user, then you can install ripgrep from the official repo:

 $ choco install ripgrep
 

 If you're a Windows Scoop user, then you can install ripgrep from the official bucket:

 $ scoop install ripgrep
 

 If you're an Arch Linux user, then you can install ripgrep from the official repos:

 $ pacman -S ripgrep
 

 If you're a Gentoo user, you can install ripgrep from the official repo:

 $ emerge sys-apps/ripgrep
 

 If you're a Fedora user, you can install ripgrep from official repositories.

 $ sudo dnf install ripgrep
 

 If you're an openSUSE user, ripgrep is included in openSUSE Tumbleweed and openSUSE Leap since 15.1.

 $ sudo zypper install ripgrep
 

 If you're a RHEL/CentOS 7/8 user, you can install ripgrep from copr:

 $ sudo yum-config-manager --add-repo=https://copr.fedorainfracloud.org/coprs/carlwgeorge/ripgrep/repo/epel-7/carlwgeorge-ripgrep-epel-7.repo
 $ sudo yum install ripgrep
 

 If you're a Nix user, you can install ripgrep from nixpkgs:

 $ nix-env --install ripgrep
 $ # (Or using the attribute name, which is also ripgrep.)
 

 If you're a Guix user, you can install ripgrep from the official package collection:

 $ guix install ripgrep
 

 If you're a Debian user (or a user of a Debian derivative like Ubuntu), then ripgrep can be installed using a binary .deb file provided in each ripgrep release.

 $ curl -LO https://github.com/BurntSushi/ripgrep/releases/download/13.0.0/ripgrep_13.0.0_amd64.deb
 $ sudo dpkg -i ripgrep_13.0.0_amd64.deb
 

 If you run Debian Buster (currently Debian stable) or Debian sid, ripgrep is officially maintained by Debian.

 $ sudo apt-get install ripgrep
 

 If you're an Ubuntu Cosmic (18.10) (or newer) user, ripgrep is available using the same packaging as Debian:

 $ sudo apt-get install ripgrep
 

 (N.B. Various snaps for ripgrep on Ubuntu are also available, but none of them seem to work right and generate a number of very strange bug reports that I don't know how to fix and don't have the time to fix. Therefore, it is no longer a recommended installation option.)

 If you're a FreeBSD user, then you can install ripgrep from the official ports:

 # pkg install ripgrep
 

 If you're an OpenBSD user, then you can install ripgrep from the official ports:

 $ doas pkg_add ripgrep
 

 If you're a NetBSD user, then you can install ripgrep from pkgsrc:

 # pkgin install ripgrep
 

 If you're a Haiku x86_64 user, then you can install ripgrep from the official ports:

 $ pkgman install ripgrep
 

 If you're a Haiku x86_gcc2 user, then you can install ripgrep from the same port as Haiku x86_64 using the x86 secondary architecture build:

 $ pkgman install ripgrep_x86
 

 If you're a Rust programmer, ripgrep can be installed with cargo.

 * Note that the minimum supported version of Rust for ripgrep is 1.65.0, although ripgrep may work with older versions.
 * Note that the binary may be bigger than expected because it contains debug symbols. This is intentional. To remove debug symbols and therefore reduce the file size, run strip on the binary.
 $ cargo install ripgrep
 

 Building

 ripgrep is written in Rust, so you'll need to grab a Rust installation in order to compile it. ripgrep compiles with Rust 1.65.0 (stable) or newer. In general, ripgrep tracks the latest stable release of the Rust compiler.

 To build ripgrep:

 $ git clone https://github.com/BurntSushi/ripgrep
 $ cd ripgrep
 $ cargo build --release
 $ ./target/release/rg --version
 0.1.3
 

 If you have a Rust nightly compiler and a recent Intel CPU, then you can enable additional optional SIMD acceleration like so:

 RUSTFLAGS="-C target-cpu=native" cargo build --release --features 'simd-accel'
 

 The simd-accel feature enables SIMD support in certain ripgrep dependencies (responsible for transcoding). They are not necessary to get SIMD optimizations for search; those are enabled automatically. Hopefully, some day, the simd-accel feature will similarly become unnecessary. WARNING: Currently, enabling this option can increase compilation times dramatically.

 Finally, optional PCRE2 support can be built with ripgrep by enabling the pcre2 feature:

 $ cargo build --release --features 'pcre2'
 

 (Tip: use --features 'pcre2 simd-accel' to also include compile time SIMD optimizations, which will only work with a nightly compiler.)

 Enabling the PCRE2 feature works with a stable Rust compiler and will attempt to automatically find and link with your system's PCRE2 library via pkg-config. If one doesn't exist, then ripgrep will build PCRE2 from source using your system's C compiler and then statically link it into the final executable. Static linking can be forced even when there is an available PCRE2 system library by either building ripgrep with the MUSL target or by setting PCRE2_SYS_STATIC=1.

 ripgrep can be built with the MUSL target on Linux by first installing the MUSL library on your system (consult your friendly neighborhood package manager). Then you just need to add MUSL support to your Rust toolchain and rebuild ripgrep, which yields a fully static executable:

 $ rustup target add x86_64-unknown-linux-musl
 $ cargo build --release --target x86_64-unknown-linux-musl
 

 Applying the --features flag from above works as expected. If you want to build a static executable with MUSL and with PCRE2, then you will need to have musl-gcc installed, which might be in a separate package from the actual MUSL library, depending on your Linux distribution.

 Running tests

 ripgrep is relatively well-tested, including both unit tests and integration tests. To run the full test suite, use:

 $ cargo test --all
 

 from the repository root.

 Vulnerability reporting

 For reporting a security vulnerability, please contact Andrew Gallant, which has my email address and PGP public key if you wish to send an encrypted message.

 Translations

 The following is a list of known translations of ripgrep's documentation. These are unofficially maintained and may not be up to date.

 * Chinese
 * Spanish

 About

 ripgrep recursively searches directories for a regex pattern while respecting your gitignore

 Topics

 gitignore search cli command-line regex recursively-search command-line-tool grep ripgrep

 Resources

 Readme

 License

 Unlicense and 2 other licenses found

 Licenses found

 Unlicense
 UNLICENSE
 Unknown
 COPYING
 MIT
 LICENSE-MIT

 Stars

 35.7k stars

 Watchers

 285 watching

 Forks

 1.6k forks

 Releases 66

 13.0.0 Latest
 Jun 12, 2021
 + 65 releases

 Used by 1.3k

 * 
 * 
 * 
 * 
 * 
 * 
 + 1,336

 Contributors 316

 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 + 305 contributors

 Languages

 * Rust 94.2%
 * Python 3.2%
 * Shell 2.5%
 * Other 0.1%

 Footer

 © 2023 GitHub, Inc.

 Footer navigation

 * Terms
 * Privacy
 * Security
 * Status
 * Docs
 * Contact GitHub
 * Pricing
 * API
 * Training
 * Blog
 * About
 You can’t perform that action at this time.
 You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
ripgrep (rg)
ripgrep is a line-oriented search tool that recursively searches the current
directory for a regex pattern. By default, ripgrep will respect gitignore rules
and automatically skip hidden files/directories and binary files. (To disable
all automatic filtering by default, use rg -uuu.) ripgrep has first class
support on Windows, macOS and Linux, with binary downloads available for every
release. ripgrep is similar to
other popular search tools like The Silver Searcher, ack and grep.
  
 
  
Dual-licensed under MIT or the UNLICENSE.
CHANGELOG
Please see the CHANGELOG for a release history.
Documentation quick links
 Installation 
 User Guide 
 Frequently Asked Questions 
 Regex syntax 
 Configuration files 
 Shell completions 
 Building 
 Translations 
Screenshot of search results
   
Quick examples comparing tools
This example searches the entire
Linux kernel source tree
(after running make defconfig &amp;&amp; make -j8) for [A-Z]+_SUSPEND, where
all matches must be words. Timings were collected on a system with an Intel
i7-6900K 3.2 GHz.
Please remember that a single benchmark is never enough! See my
blog post on ripgrep
for a very detailed comparison with more benchmarks and analysis.
Tool
Command
Line count
Time
ripgrep (Unicode)
 rg -n -w '[A-Z]+_SUSPEND' 
452
 0.136s 
 git grep 
 git grep -P -n -w '[A-Z]+_SUSPEND' 
452
0.348s
 ugrep (Unicode) 
 ugrep -r --ignore-files --no-hidden -I -w '[A-Z]+_SUSPEND' 
452
0.506s
 The Silver Searcher 
 ag -w '[A-Z]+_SUSPEND' 
452
0.654s
 git grep 
 LC_ALL=C git grep -E -n -w '[A-Z]+_SUSPEND' 
452
1.150s
 ack 
 ack -w '[A-Z]+_SUSPEND' 
452
4.054s
 git grep (Unicode) 
 LC_ALL=en_US.UTF-8 git grep -E -n -w '[A-Z]+_SUSPEND' 
452
4.205s
Here's another benchmark on the same corpus as above that disregards gitignore
files and searches with a whitelist instead. The corpus is the same as in the
previous benchmark, and the flags passed to each command ensure that they are
doing equivalent work:
Tool
Command
Line count
Time
ripgrep
 rg -uuu -tc -n -w '[A-Z]+_SUSPEND' 
388
 0.096s 
 ugrep 
 ugrep -r -n --include='*.c' --include='*.h' -w '[A-Z]+_SUSPEND' 
388
0.493s
 GNU grep 
 egrep -r -n --include='*.c' --include='*.h' -w '[A-Z]+_SUSPEND' 
388
0.806s
And finally, a straight-up comparison between ripgrep, ugrep and GNU grep on a
single large file cached in memory
(~13GB,  OpenSubtitles.raw.en.gz ):
Tool
Command
Line count
Time
ripgrep
 rg -w 'Sherlock [A-Z]\w+' 
7882
 2.769s 
 ugrep 
 ugrep -w 'Sherlock [A-Z]\w+' 
7882
6.802s
 GNU grep 
 LC_ALL=en_US.UTF-8 egrep -w 'Sherlock [A-Z]\w+' 
7882
9.027s
In the above benchmark, passing the -n flag (for showing line numbers)
increases the times to 3.423s for ripgrep and 13.031s for GNU grep. ugrep
times are unaffected by the presence or absence of -n.
Why should I use ripgrep?
It can replace many use cases served by other search tools
because it contains most of their features and is generally faster. (See
the FAQ for more details on whether ripgrep can truly
replace grep.)
Like other tools specialized to code search, ripgrep defaults to
recursive search and does automatic
filtering. Namely, ripgrep won't search files
ignored by your .gitignore/.ignore/.rgignore files, it won't search
hidden files and it won't search binary files. Automatic filtering can be
disabled with rg -uuu.
ripgrep can search specific types of files.
For example, rg -tpy foo limits your search to Python files and rg -Tjs foo excludes JavaScript files from your search. ripgrep can be taught about
new file types with custom matching rules.
ripgrep supports many features found in grep, such as showing the context
of search results, searching multiple patterns, highlighting matches with
color and full Unicode support. Unlike GNU grep, ripgrep stays fast while
supporting Unicode (which is always on).
ripgrep has optional support for switching its regex engine to use PCRE2.
Among other things, this makes it possible to use look-around and
backreferences in your patterns, which are not supported in ripgrep's default
regex engine. PCRE2 support can be enabled with -P/--pcre2 (use PCRE2
always) or --auto-hybrid-regex (use PCRE2 only if needed). An alternative
syntax is provided via the --engine (default|pcre2|auto-hybrid) option.
ripgrep has rudimentary support for replacements,
which permit rewriting output based on what was matched.
ripgrep supports searching files in text encodings
other than UTF-8, such as UTF-16, latin-1, GBK, EUC-JP, Shift_JIS and more.
(Some support for automatically detecting UTF-16 is provided. Other text
encodings must be specifically specified with the -E/--encoding flag.)
ripgrep supports searching files compressed in a common format (brotli,
bzip2, gzip, lz4, lzma, xz, or zstandard) with the -z/--search-zip flag.
ripgrep supports
arbitrary input preprocessing filters
which could be PDF text extraction, less supported decompression, decrypting,
automatic encoding detection and so on.
ripgrep can be configured via a
configuration file.
In other words, use ripgrep if you like speed, filtering by default, fewer
bugs and Unicode support.
Why shouldn't I use ripgrep?
Despite initially not wanting to add every feature under the sun to ripgrep,
over time, ripgrep has grown support for most features found in other file
searching tools. This includes searching for results spanning across multiple
lines, and opt-in support for PCRE2, which provides look-around and
backreference support.
At this point, the primary reasons not to use ripgrep probably consist of one
or more of the following:
You need a portable and ubiquitous tool. While ripgrep works on Windows,
macOS and Linux, it is not ubiquitous and it does not conform to any
standard such as POSIX. The best tool for this job is good old grep.
There still exists some other feature (or bug) not listed in this README that
you rely on that's in another tool that isn't in ripgrep.
There is a performance edge case where ripgrep doesn't do well where another
tool does do well. (Please file a bug report!)
ripgrep isn't possible to install on your machine or isn't available for your
platform. (Please file a bug report!)
Is it really faster than everything else?
Generally, yes. A large number of benchmarks with detailed analysis for each is
available on my blog.
Summarizing, ripgrep is fast because:
It is built on top of
Rust's regex engine.
Rust's regex engine uses finite automata, SIMD and aggressive literal
optimizations to make searching very fast. (PCRE2 support can be opted into
with the -P/--pcre2 flag.)
Rust's regex library maintains performance with full Unicode support by
building UTF-8 decoding directly into its deterministic finite automaton
engine.
It supports searching with either memory maps or by searching incrementally
with an intermediate buffer. The former is better for single files and the
latter is better for large directories. ripgrep chooses the best searching
strategy for you automatically.
Applies your ignore patterns in .gitignore files using a
 RegexSet .
That means a single file path can be matched against multiple glob patterns
simultaneously.
It uses a lock-free parallel recursive directory iterator, courtesy of
 crossbeam  and
 ignore .
Feature comparison
Andy Lester, author of ack, has published an
excellent table comparing the features of ack, ag, git-grep, GNU grep and
ripgrep: https://beyondgrep.com/feature-comparison/ 
Note that ripgrep has grown a few significant new features recently that
are not yet present in Andy's table. This includes, but is not limited to,
configuration files, passthru, support for searching compressed files,
multiline search and opt-in fancy regex support via PCRE2.
Installation
The binary name for ripgrep is rg.
  Archives of precompiled binaries for ripgrep are available for Windows,
macOS and Linux.  Linux and
Windows binaries are static executables. Users of platforms not explicitly
mentioned below are advised to download one of these archives.
If you're a macOS Homebrew or a Linuxbrew user, then you can install
ripgrep from homebrew-core:
If you're a MacPorts user, then you can install ripgrep from the
official ports:
  $ sudo port install ripgrep
  
If you're a Windows Chocolatey user, then you can install ripgrep from the
official repo:
If you're a Windows Scoop user, then you can install ripgrep from the
official bucket:
If you're an Arch Linux user, then you can install ripgrep from the official repos:
If you're a Gentoo user, you can install ripgrep from the
official repo:
  $ emerge sys-apps/ripgrep
  
If you're a Fedora user, you can install ripgrep from official
repositories.
  $ sudo dnf install ripgrep
  
If you're an openSUSE user, ripgrep is included in openSUSE Tumbleweed
and openSUSE Leap since 15.1.
  $ sudo zypper install ripgrep
  
If you're a RHEL/CentOS 7/8 user, you can install ripgrep from
copr:
  $ sudo yum-config-manager --add-repo=https://copr.fedorainfracloud.org/coprs/carlwgeorge/ripgrep/repo/epel-7/carlwgeorge-ripgrep-epel-7.repo
$ sudo yum install ripgrep
  
If you're a Nix user, you can install ripgrep from
nixpkgs:
  $ nix-env --install ripgrep
$ # (Or using the attribute name, which is also ripgrep.)
  
If you're a Guix user, you can install ripgrep from the official
package collection:
If you're a Debian user (or a user of a Debian derivative like Ubuntu),
then ripgrep can be installed using a binary .deb file provided in each
ripgrep release.
  $ curl -LO https://github.com/BurntSushi/ripgrep/releases/download/13.0.0/ripgrep_13.0.0_amd64.deb
$ sudo dpkg -i ripgrep_13.0.0_amd64.deb
  
If you run Debian Buster (currently Debian stable) or Debian sid, ripgrep is
officially maintained by Debian.
  $ sudo apt-get install ripgrep
  
If you're an Ubuntu Cosmic (18.10) (or newer) user, ripgrep is
available using the same
packaging as Debian:
  $ sudo apt-get install ripgrep
  
(N.B. Various snaps for ripgrep on Ubuntu are also available, but none of them
seem to work right and generate a number of very strange bug reports that I
don't know how to fix and don't have the time to fix. Therefore, it is no
longer a recommended installation option.)
If you're a FreeBSD user, then you can install ripgrep from the
official ports:
If you're an OpenBSD user, then you can install ripgrep from the
official ports:
If you're a NetBSD user, then you can install ripgrep from
pkgsrc:
If you're a Haiku x86_64 user, then you can install ripgrep from the
official ports:
If you're a Haiku x86_gcc2 user, then you can install ripgrep from the
same port as Haiku x86_64 using the x86 secondary architecture build:
  $ pkgman install ripgrep_x86
  
If you're a Rust programmer, ripgrep can be installed with cargo.
Note that the minimum supported version of Rust for ripgrep is 1.65.0,
although ripgrep may work with older versions.
Note that the binary may be bigger than expected because it contains debug
symbols. This is intentional. To remove debug symbols and therefore reduce
the file size, run strip on the binary.
Building
ripgrep is written in Rust, so you'll need to grab a
Rust installation in order to compile it.
ripgrep compiles with Rust 1.65.0 (stable) or newer. In general, ripgrep tracks
the latest stable release of the Rust compiler.
To build ripgrep:
  $ git clone https://github.com/BurntSushi/ripgrep
$ cd ripgrep
$ cargo build --release
$ ./target/release/rg --version
0.1.3
  
If you have a Rust nightly compiler and a recent Intel CPU, then you can enable
additional optional SIMD acceleration like so:
  RUSTFLAGS="-C target-cpu=native" cargo build --release --features 'simd-accel'
  
The simd-accel feature enables SIMD support in certain ripgrep dependencies
(responsible for transcoding). They are not necessary to get SIMD optimizations
for search; those are enabled automatically. Hopefully, some day, the
simd-accel feature will similarly become unnecessary. WARNING: Currently,
enabling this option can increase compilation times dramatically.
Finally, optional PCRE2 support can be built with ripgrep by enabling the
pcre2 feature:
  $ cargo build --release --features 'pcre2'
  
(Tip: use --features 'pcre2 simd-accel' to also include compile time SIMD
optimizations, which will only work with a nightly compiler.)
Enabling the PCRE2 feature works with a stable Rust compiler and will
attempt to automatically find and link with your system's PCRE2 library via
pkg-config. If one doesn't exist, then ripgrep will build PCRE2 from source
using your system's C compiler and then statically link it into the final
executable. Static linking can be forced even when there is an available PCRE2
system library by either building ripgrep with the MUSL target or by setting
PCRE2_SYS_STATIC=1.
ripgrep can be built with the MUSL target on Linux by first installing the MUSL
library on your system (consult your friendly neighborhood package manager).
Then you just need to add MUSL support to your Rust toolchain and rebuild
ripgrep, which yields a fully static executable:
  $ rustup target add x86_64-unknown-linux-musl
$ cargo build --release --target x86_64-unknown-linux-musl
  
Applying the --features flag from above works as expected. If you want to
build a static executable with MUSL and with PCRE2, then you will need to have
musl-gcc installed, which might be in a separate package from the actual
MUSL library, depending on your Linux distribution.
Running tests
ripgrep is relatively well-tested, including both unit tests and integration
tests. To run the full test suite, use:
from the repository root.
Vulnerability reporting
For reporting a security vulnerability, please
contact Andrew Gallant,
which has my email address and PGP public key if you wish to send an encrypted
message.
Translations
The following is a list of known translations of ripgrep's documentation. These
are unofficially maintained and may not be up to date.
 Chinese 
 Spanish
GitHub - BurntSushi/ripgrep: ripgrep recursively searches directories for a regex pattern while respecting your gitignore
https://github.com/BurntSushi/ripgrep
https://crates.io/crates/grep-searcher
searcher - crates.io: Rust Package Registry
2023-11-28
None
<div><div>
<nav>
<ul>
<li>
<a href="https://crates.io/crates/grep-searcher">
 
 Readme
 
 </a>
</li>
<li>
<a href="https://crates.io/crates/grep-searcher/versions">
 
 15 Versions
 
 </a>
</li>
<li>
<a href="https://crates.io/crates/grep-searcher/dependencies">
 
 Dependencies
 
 </a>
</li>
<li>
<a href="https://crates.io/crates/grep-searcher/reverse_dependencies">
 
 Dependents
 
 </a>
</li>
</ul>
</nav>
<div>
<article>
<div>
<h2><a href="#grep-searcher"></a>grep-searcher</h2>
<p>A high level library for executing fast line oriented searches. This handles
things like reporting contextual lines, counting lines, inverting a search,
detecting binary data, automatic UTF-16 transcoding and deciding whether or not
to use memory maps.</p>
<p><a href="https://github.com/BurntSushi/ripgrep/actions"></a>
<a href="https://crates.io/crates/grep-searcher"></a></p>
<p>Dual-licensed under MIT or the <a href="https://unlicense.org/">UNLICENSE</a>.</p>
<h3><a href="#documentation"></a>Documentation</h3>
<p><a href="https://docs.rs/grep-searcher">https://docs.rs/grep-searcher</a></p>
<p><strong>NOTE:</strong> You probably don't want to use this crate directly. Instead, you
should prefer the facade defined in the
<a href="https://docs.rs/grep"><code>grep</code></a>
crate.</p>
<h3><a href="#usage"></a>Usage</h3>
<p>Add this to your <code>Cargo.toml</code>:</p>
<pre><code>
 = 
</code></pre>
</div>
</article>
</div>
<div>
<div>
<h3>Stats Overview</h3>
<p>
</p>
<p>
</p>
</div>
<div>
<h4>Downloads over the last 90 days</h4>
</div>
</div>
</div></div>||||I||||For full functionality of this site it is necessary to enable JavaScript.

 crates.io

 The Rust community’s crate registry

 Submit
 Browse All Crates | Log in with GitHub
 Menu
 * Browse All Crates
 * Log in with GitHub

 grep-searcher v0.1.13

 Fast line oriented regex searching as a library.
 * # pattern
 * # regex
 * # egrep
 * # grep
 * # search
 * Readme
 * 15 Versions
 * Dependencies
 * Dependents

 grep-searcher

 A high level library for executing fast line oriented searches. This handles things like reporting contextual lines, counting lines, inverting a search, detecting binary data, automatic UTF-16 transcoding and deciding whether or not to use memory maps.

 Dual-licensed under MIT or the UNLICENSE.

 Documentation

 https://docs.rs/grep-searcher

 NOTE: You probably don't want to use this crate directly. Instead, you should prefer the facade defined in the grep crate.

 Usage

 Add this to your Cargo.toml:

 [dependencies]
 grep-searcher = "0.1"
 

 Metadata

 5 months ago
 Unlicense OR MIT
 44.2 KiB

 Install

 Run the following Cargo command in your project directory:

 cargo add grep-searcher

 Or add the following line to your Cargo.toml:

 grep-searcher = "0.1.13"

 Documentation

 docs.rs/grep-searcher/0.1.13

 Repository

 github.com/BurntSushi/ripgrep/tree/master/crates/searcher

 Owners

 * Andrew Gallant

 Stats Overview

 1,886,440 Downloads all time
 15 Versions published

 Downloads over the last 90 days

 Display as
 Stacked
 * Stacked
 * Unstacked

 Rust

 * rust-lang.org
 * Rust Foundation
 * The crates.io team

 Get Help

 * The Cargo Book
 * Email Support
 * System Status
 * Report a bug

 Policies

 * Usage Policy
 * Security
 * Privacy Policy
 * Code of Conduct
 * Data Access

 Social

 * rust-lang/crates.io
 * @cratesiostatus
 * #t-crates-io
Readme
 
 
 
 15 Versions
 
 
 
 Dependencies
 
 
 
 Dependents
 
 
  grep-searcher
A high level library for executing fast line oriented searches. This handles
things like reporting contextual lines, counting lines, inverting a search,
detecting binary data, automatic UTF-16 transcoding and deciding whether or not
to use memory maps.
  
  
Dual-licensed under MIT or the UNLICENSE.
  Documentation
 https://docs.rs/grep-searcher 
 NOTE: You probably don't want to use this crate directly. Instead, you
should prefer the facade defined in the
 grep 
crate.
  Usage
Add this to your Cargo.toml:
 
 = 
 
Stats Overview
Downloads over the last 90 days
searcher - crates.io: Rust Package Registry
https://crates.io/crates/grep-searcher
https://simonwillison.net/tags/rust/
Simon Willison’s Weblog
2022-06-20
None
<div><div>
<h2>42 items tagged “rust”</h2>
 
<h3>2023</h3>
<p><a href="https://github.com/asg017/sqlite-jsonschema">sqlite-jsonschema</a>. “A SQLite extension for validating JSON objects with JSON Schema”, building on the jsonschema Rust crate. SQLite and JSON are already a great combination—Alex suggests using this extension to implement check constraints to validate JSON columns before inserting into a table, or just to run queries finding existing data that doesn’t match a given schema. <a href="/2023/Jan/28/sqlite-jsonschema/">#</a> <a href="/2023/Jan/28/">28th January 2023</a>, 3:50 am</p>
<p><a href="https://github.com/asg017/sqlite-ulid">sqlite-ulid</a>. Alex Garcia’s sqlite-ulid adds lightning-fast SQL functions for generating ULIDs—Universally Unique Lexicographically Sortable Identifiers. These work like UUIDs but are smaller and faster to generate, and can be canonically encoded as a URL-safe 26 character string (UUIDs are 36 characters). Again, this builds on a Rust crate—ulid-rs—and can generate 1 million byte-represented ULIDs with the ulid_bytes() function in just 88.4ms. <a href="/2023/Jan/28/sqlite-ulid/">#</a> <a href="/2023/Jan/28/">28th January 2023</a>, 3:45 am</p>
<p><a href="https://github.com/asg017/sqlite-fastrand">sqlite-fastrand</a>. Alex Garcia just dropped three new SQLite extensions, and I’m going to link to all of them. The first is sqlite-fastrand, which adds new functions for generating random numbers (and alphanumeric characters too). Impressively, these out-perform the default SQLite random() and randomblob() functions by about 1.6-2.6x, thanks to being built on the Rust fastrand crate which builds on wyhash, an extremely fast (though not cryptographically secure) hashing function. <a href="/2023/Jan/28/sqlite-fastrand/">#</a> <a href="/2023/Jan/28/">28th January 2023</a>, 3:41 am</p>
<p><a href="https://github.com/simonw/datasette-granian">datasette-granian</a> (<a href="https://github.com/emmett-framework/granian/issues/35#issuecomment-1397829516">via</a>) Granian is a new Python web server—similar to Gunicorn—written in Rust. I built a small plugin that adds a “datasette granian” command starting a Granian server that serves Datasette’s ASGI application, using the same pattern as my existing datasette-gunicorn plugin. <a href="/2023/Jan/20/datasette-granian/">#</a> <a href="/2023/Jan/20/">20th January 2023</a>, 2:12 am</p>
<p><a href="https://servo.org/blog/2023/01/16/servo-2023/">Servo to Advance in 2023</a> (<a href="https://news.ycombinator.com/item?id=34400214">via</a>) This is excellent news: Serve, the browser-in-Rust project started by Mozilla in 2012 that produced the Rust programming language, is getting re-activated with four new full-time developers provided by Igalia.
Igalia are a fascinating organization—I hadn’t realized quite how influential they’ve been until I read their Wikipedia page just now
They’ve been around since 2001, and “in 2019 they were the #2 committers to both the WebKit and Chromium codebases and in the top 10 contributors to Gecko/Servo”—including implementing and maintaining CSS Grid Layout! <a href="/2023/Jan/16/servo-to-advance-in-2023/">#</a> <a href="/2023/Jan/16/">16th January 2023</a>, 5:08 pm</p>
<p><a href="https://observablehq.com/@asg017/introducing-sqlite-xsv">Introducing sqlite-xsv: The Fastest CSV Parser for SQLite</a>. Alex Garcia continues to push the boundaries of SQLite extensions. This new extension in Rust wraps the lightning fast Rust csv crate and provides a new csv_reader() virtual table that can handle regular, gzipped and zstd compressed files. <a href="/2023/Jan/14/sqlite-xsv/">#</a> <a href="/2023/Jan/14/">14th January 2023</a>, 9:54 pm</p>
<h3>2022</h3>
<div><p><a href="https://medium.com/source-and-buggy/data-driven-performance-optimization-with-rust-and-miri-70cb6dde0d35">Data-driven performance optimization with Rust and Miri</a> (<a href="https://news.ycombinator.com/item?id=33921731">via</a>) Useful guide to some Rust performance optimization tools. Miri can be used to dump out a detailed JSON profile of a program which can then be opened and explored using the Chrome browser’s performance tool. <a href="/2022/Dec/9/data-driven-performance-optimization-with-rust-and-miri/">#</a> <a href="/2022/Dec/9/">9th December 2022</a>, 5:19 pm</p>
</div>
<p><a href="https://observablehq.com/@asg017/introducing-sqlite-loadable-rs">Introducing sqlite-loadable-rs: A framework for building SQLite Extensions in Rust</a>. Alex Garcia has built a new Rust library for creating SQLite extensions—initially supporting custom scalar functions, virtual tables and table functions and with more types of extension coming soon. This looks very easy to use, partly because the documentation and examples are already delightfully thorough, especially for an initial release. <a href="/2022/Dec/7/sqlite-loadable-rs/">#</a> <a href="/2022/Dec/7/">7th December 2022</a>, 11:08 pm</p>
 
<p><a href="https://jzhao.xyz/posts/bft-json-crdt/">Building a BFT JSON CRDT</a> (<a href="https://news.ycombinator.com/item?id=33694568">via</a>) Jacky Zhao describes their project to build a CRDT library for JSON data in Rust, and includes a thorough explanation of what CRDTs are and how they work. “I write this blog post mostly as a note to my past self, distilling a lot of what I’ve learned since into a blog post I wish I had read before going in”—the best kind of blog post! <a href="/2022/Nov/21/building-a-bft-json-crdt/">#</a> <a href="/2022/Nov/21/">21st November 2022</a>, 7:56 pm</p>
<p><a href="https://blessed.rs/crates">Blessed.rs Crate List</a> (<a href="https://news.ycombinator.com/item?id=33506132">via</a>) Rust doesn’t have a very large standard library, so part of learning Rust is figuring out which of the third-party crates are the best for tackling common problems. This here is an opinionated guide to crates, which looks like it could be really useful. <a href="/2022/Nov/7/blessedrs/">#</a> <a href="/2022/Nov/7/">7th November 2022</a>, 7:25 pm</p>
<p><a href="https://github.com/mitsuhiko/insta">mitsuhiko/insta</a> (<a href="https://twitter.com/david_raznick/status/1586885078457753602">via</a>) I asked for recommendations on Twitter for testing libraries in other languages that would give me the same level of delight that I get from pytest. Two people pointed me to insta by Armin Ronacher, a Rust testing framework for “snapshot testing” which automatically records reference values to your repository, so future tests can spot if they change. <a href="/2022/Oct/31/insta/">#</a> <a href="/2022/Oct/31/">31st October 2022</a>, 1:06 am</p>
<p><a href="https://github.com/rochacbruno/py2rs">py2rs</a>. Extremely useful document providing resources for learning Rust followed by an extensive collection of common Python tasks (building a list, opening a file, spawning a thread, running a simple web server) and their Rust equivalents. <a href="/2022/Oct/7/py2rs/">#</a> <a href="/2022/Oct/7/">7th October 2022</a>, 5:44 pm</p>
<p><a href="https://github.com/libsql/libsql">libsql</a> (<a href="https://glaubercosta-11125.medium.com/sqlite-qemu-all-over-again-aedad19c9a1c">via</a>) A brand new Apache 2 licensed fork of SQLite. The README explains the rationale behind the project: SQLite itself is open source but not open contribution, and this fork aims to try out new ideas. The most interesting to me so far is a plan to support user defined functions implemented in WebAssembly. The project also intends to use Rust for new feature development. <a href="/2022/Oct/4/libsql/">#</a> <a href="/2022/Oct/4/">4th October 2022</a>, 4:13 pm</p>
<p><a href="https://univalence.me/posts/mvsqlite">Turning SQLite into a distributed database</a> (<a href="https://news.ycombinator.com/item?id=32539360">via</a>) Heyang Zhou introduces mvSQLite, his brand new open source “SQLite-compatible distributed database” built in Rust on top of Apple’s FoundationDB. This is a very promising looking new entry into the distributed/replicated SQLite space: FoundationDB was designed to provide low-level primitives that tools like this could build on top of. <a href="/2022/Aug/21/mvsqlite/">#</a> <a href="/2022/Aug/21/">21st August 2022</a>, 5:40 pm</p>
<p><a href="https://phiresky.github.io/blog/2022/sqlite-zstd/">sqlite-zstd: Transparent dictionary-based row-level compression for SQLite</a>. Interesting SQLite extension from phiresky, the author of that amazing SQLite WASM hack from a while ago which could fetch subsets of a large SQLite database using the HTTP range header. This extension, written in Rust, implements row-level compression for a SQLite table by creating compression dictionaries for larger chunks of the table, providing better results than just running compression against each row value individually. <a href="/2022/Aug/9/sqlite-zstd/">#</a> <a href="/2022/Aug/9/">9th August 2022</a>, 9:23 pm</p>
<p><a href="https://blog.scottlogic.com/2022/06/20/state-of-wasm-2022.html">The State of WebAssembly 2022</a>. Colin Eberhardt talks through the results of the State of WebAssembly 2022 survey. Rust continues to dominate as the most popular language for working to WebAssembly, but Python has a notable increase of interest. <a href="/2022/Jun/20/the-state-of-webassembly-2022/">#</a> <a href="/2022/Jun/20/">20th June 2022</a>, 6:07 pm</p>
<p><a href="https://blog.ceejbot.com/posts/postfix-await/">Why Rust’s postfix await syntax is good</a> (<a href="https://twitter.com/ceejbot/status/1525260424731455489">via</a>) C J Silverio explains postfix await in Rust—where you can write a line like this, with the ? causing any errors to be caught and turned into an error return from your function:
let count = fetch_all_animals().await?.filter_for_hedgehogs().len(); <a href="/2022/May/15/why-rusts-postfix-await-syntax-is-good/">#</a> <a href="/2022/May/15/">15th May 2022</a>, 2:27 pm</p>
<p><a href="https://pauljuliusmartinez.github.io/">jless</a> (<a href="https://news.ycombinator.com/item?id=30273940">via</a>) A really nice new command-line JSON viewer, written in Rust, created by Paul Julius Martinez. It provides a terminal interface for navigating through large JSON files, including expanding and contracting nested objects and searching for strings or a modified form of regular expressions. <a href="/2022/Feb/12/jless/">#</a> <a href="/2022/Feb/12/">12th February 2022</a>, 3:17 am</p>
<div><p><a href="https://parceljs.org/blog/parcel-css/">Announcing Parcel CSS: A new CSS parser, compiler, and minifier written in Rust!</a> An interesting thing about tools like this being written in Rust is that since the Rust-to-WASM pipeline is well trodden at this point, the live demo that this announcement links to runs entirely in the browser. <a href="/2022/Jan/13/announcing-parcel-css/">#</a> <a href="/2022/Jan/13/">13th January 2022</a>, 8:40 pm</p>
</div>
<h3>2021</h3>
<p><a href="https://github.blog/2021-12-09-introducing-stack-graphs/">Introducing stack graphs</a> (<a href="https://github.blog/2021-12-09-precise-code-navigation-python-code-navigation-pull-requests/">via</a>) GitHub launched “precise code navigation” for Python today—the first language to get support for this feature. Click on any Python symbol in GitHub’s code browsing views and a box will show you exactly where that symbol was defined—all based on static analysis by a custom parser written in Rust as opposed to executing any Python code directly. The underlying computer science uses a technique called stack graphs, based on scope graphs research from Eelco Visser’s research group at TU Delft. <a href="/2021/Dec/9/introducing-stack-graphs/">#</a> <a href="/2021/Dec/9/">9th December 2021</a>, 11:07 pm</p>
<p><a href="https://github.com/Orange-OpenSource/hurl">Hurl</a> (<a href="https://twitter.com/humphd/status/1462594205629493254">via</a>) Hurl is “a command line tool that runs HTTP requests defined in a simple plain text format”—written in Rust on top of curl, it lets you run HTTP requests and then execute assertions against the response, defined using JSONPath or XPath for HTML. It can even assert that responses were returned within a specified duration. <a href="/2021/Nov/22/hurl/">#</a> <a href="/2021/Nov/22/">22nd November 2021</a>, 3:32 am</p>
<p><a href="https://fasterthanli.me/articles/a-half-hour-to-learn-rust">A half-hour to learn Rust</a>. I haven’t tried to write any Rust yet but I occasionally find myself wanting to read it, and I find some of the syntax really difficult to get my head around. This article helped a lot: it provides a quick but thorough introduction to most of Rust’s syntax, with clearly explained snippet examples for each one. <a href="/2021/Nov/5/a-half-hour-to-learn-rust/">#</a> <a href="/2021/Nov/5/">5th November 2021</a>, 5:21 am</p>
<p><a href="https://github.com/aws-samples/aws-lambda-adapter">aws-lambda-adapter</a>. AWS Lambda added support for Docker containers last year, but with a very weird shape: you can run anything on Lambda that fits in a Docker container, but unlike Google Cloud Run your application doesn’t get to speak HTTP: it needs to run code that listens for proprietary AWS lambda events instead. The obvious way to fix this is to run some kind of custom proxy inside the container which turns AWS runtime events into HTTP calls to a regular web application. Serverlessish and re:Web are two open source projects that implemented this, and now AWS have their own implementation of that pattern, written in Rust. <a href="/2021/Oct/28/aws-lambda-adapter/">#</a> <a href="/2021/Oct/28/">28th October 2021</a>, 5:04 am</p>
<p><a href="https://github.com/erikgrinaker/toydb/blob/master/docs/references.md">toyDB: references</a>. toyDB is a “distributed SQL database in Rust, written as a learning project”, with its own implementations of SQL, raft, ACID transactions, B+trees and more. toyDB author Erik Grinaker has assembled a detailed set of references that he used to learn how to build a database—I’d love to see more projects do this, it’s really useful. <a href="/2021/Jul/19/toydb-references/">#</a> <a href="/2021/Jul/19/">19th July 2021</a>, 12:18 am</p>
<p><a href="https://avi.im/blag/2021/fast-sqlite-inserts/">Inserting One Billion Rows in SQLite Under a Minute</a> (<a href="https://news.ycombinator.com/item?id=27872575">via</a>) Avinash Sajjanshetty experiments with accelerating writes to a test table in SQLite, using various SQLite pragmas to accelerate inserts followed by a rewrite of Python code to Rust. Also of note: running the exact same code in PyPy saw a 3.5x speed-up! <a href="/2021/Jul/19/one-billion-rows/">#</a> <a href="/2021/Jul/19/">19th July 2021</a>, 12:13 am</p>
<h3>2020</h3>
<p><a href="https://archive.org/details/softwarelibrary_flash">Internet Archive Software Library: Flash</a> (<a href="https://twitter.com/textfiles/status/1329525300846276608">via</a>) A fantastic new initiative from the Internet Archive: they’re now archiving Flash (.swf) files and serving them for modern browsers using Ruffle, a Flash Player emulator written in Rust and compiled to WebAssembly. They are fully interactive and audio works too. Considering the enormous quantity of creative material released in Flash over the decades this helps fill a big hole in the Internet’s cultural memory. <a href="/2020/Nov/19/internet-archive-flash/">#</a> <a href="/2020/Nov/19/">19th November 2020</a>, 9:19 pm</p>
<p><a href="https://materialize.io/docs/get-started/">Get Started—Materialize</a>. Materialize is a really interesting new database—“a streaming SQL materialized view engine”. It builds materialized views on top of streaming data sources (such as Kafka)—you define the view using a SQL query, then it figures out how to keep that view up-to-date automatically as new data streams in. It speaks the PostgreSQL protocol so you can talk to it using the psql tool or any PostgreSQL client library. The “get started” guide is particularly impressive: it uses a curl stream of the Wikipedia recent changes API, parsed using a regular expression. And it’s written in Rust, so installing it is as easy as downloading and executing a single binary (though I used Homebrew). <a href="/2020/Jun/1/get-started-materialize/">#</a> <a href="/2020/Jun/1/">1st June 2020</a>, 10:11 pm</p>
<p><a href="https://deno.land/v1">Deno 1.0</a>. Deno is a new take on server-side JavaScript from a team lead by Ryan Dahl, who originally created Node.js. It’s built using Rust and crammed with fascinating ideas—like the ability to import code directly from a URL. <a href="/2020/May/13/deno-10/">#</a> <a href="/2020/May/13/">13th May 2020</a>, 11:38 pm</p>
 
</div>||||I|||| Simon Willison’s Weblog

 42 items tagged “rust”

 2023

 sqlite-jsonschema. “A SQLite extension for validating JSON objects with JSON Schema”, building on the jsonschema Rust crate. SQLite and JSON are already a great combination—Alex suggests using this extension to implement check constraints to validate JSON columns before inserting into a table, or just to run queries finding existing data that doesn’t match a given schema. # 28th January 2023, 3:50 am

 sqlite-ulid. Alex Garcia’s sqlite-ulid adds lightning-fast SQL functions for generating ULIDs—Universally Unique Lexicographically Sortable Identifiers. These work like UUIDs but are smaller and faster to generate, and can be canonically encoded as a URL-safe 26 character string (UUIDs are 36 characters). Again, this builds on a Rust crate—ulid-rs—and can generate 1 million byte-represented ULIDs with the ulid_bytes() function in just 88.4ms. # 28th January 2023, 3:45 am

 sqlite-fastrand. Alex Garcia just dropped three new SQLite extensions, and I’m going to link to all of them. The first is sqlite-fastrand, which adds new functions for generating random numbers (and alphanumeric characters too). Impressively, these out-perform the default SQLite random() and randomblob() functions by about 1.6-2.6x, thanks to being built on the Rust fastrand crate which builds on wyhash, an extremely fast (though not cryptographically secure) hashing function. # 28th January 2023, 3:41 am

 datasette-granian (via) Granian is a new Python web server—similar to Gunicorn—written in Rust. I built a small plugin that adds a “datasette granian” command starting a Granian server that serves Datasette’s ASGI application, using the same pattern as my existing datasette-gunicorn plugin. # 20th January 2023, 2:12 am

 Servo to Advance in 2023 (via) This is excellent news: Serve, the browser-in-Rust project started by Mozilla in 2012 that produced the Rust programming language, is getting re-activated with four new full-time developers provided by Igalia. Igalia are a fascinating organization—I hadn’t realized quite how influential they’ve been until I read their Wikipedia page just now They’ve been around since 2001, and “in 2019 they were the #2 committers to both the WebKit and Chromium codebases and in the top 10 contributors to Gecko/Servo”—including implementing and maintaining CSS Grid Layout! # 16th January 2023, 5:08 pm

 Introducing sqlite-xsv: The Fastest CSV Parser for SQLite. Alex Garcia continues to push the boundaries of SQLite extensions. This new extension in Rust wraps the lightning fast Rust csv crate and provides a new csv_reader() virtual table that can handle regular, gzipped and zstd compressed files. # 14th January 2023, 9:54 pm

 2022

 Data-driven performance optimization with Rust and Miri (via) Useful guide to some Rust performance optimization tools. Miri can be used to dump out a detailed JSON profile of a program which can then be opened and explored using the Chrome browser’s performance tool. # 9th December 2022, 5:19 pm

 Introducing sqlite-loadable-rs: A framework for building SQLite Extensions in Rust. Alex Garcia has built a new Rust library for creating SQLite extensions—initially supporting custom scalar functions, virtual tables and table functions and with more types of extension coming soon. This looks very easy to use, partly because the documentation and examples are already delightfully thorough, especially for an initial release. # 7th December 2022, 11:08 pm

 AI assisted learning: Learning Rust with ChatGPT, Copilot and Advent of Code

 I’m using this year’s Advent of Code to learn Rust—with the assistance of GitHub Copilot and OpenAI’s new ChatGPT.

 [... 2661 words ]
 9:11 pm / 5th December 2022 / rust, gpt3, projects, openai, education, github, chatgpt, copilot

 Building a BFT JSON CRDT (via) Jacky Zhao describes their project to build a CRDT library for JSON data in Rust, and includes a thorough explanation of what CRDTs are and how they work. “I write this blog post mostly as a note to my past self, distilling a lot of what I’ve learned since into a blog post I wish I had read before going in”—the best kind of blog post! # 21st November 2022, 7:56 pm

 Blessed.rs Crate List (via) Rust doesn’t have a very large standard library, so part of learning Rust is figuring out which of the third-party crates are the best for tackling common problems. This here is an opinionated guide to crates, which looks like it could be really useful. # 7th November 2022, 7:25 pm

 mitsuhiko/insta (via) I asked for recommendations on Twitter for testing libraries in other languages that would give me the same level of delight that I get from pytest. Two people pointed me to insta by Armin Ronacher, a Rust testing framework for “snapshot testing” which automatically records reference values to your repository, so future tests can spot if they change. # 31st October 2022, 1:06 am

 py2rs. Extremely useful document providing resources for learning Rust followed by an extensive collection of common Python tasks (building a list, opening a file, spawning a thread, running a simple web server) and their Rust equivalents. # 7th October 2022, 5:44 pm

 libsql (via) A brand new Apache 2 licensed fork of SQLite. The README explains the rationale behind the project: SQLite itself is open source but not open contribution, and this fork aims to try out new ideas. The most interesting to me so far is a plan to support user defined functions implemented in WebAssembly. The project also intends to use Rust for new feature development. # 4th October 2022, 4:13 pm

 Turning SQLite into a distributed database (via) Heyang Zhou introduces mvSQLite, his brand new open source “SQLite-compatible distributed database” built in Rust on top of Apple’s FoundationDB. This is a very promising looking new entry into the distributed/replicated SQLite space: FoundationDB was designed to provide low-level primitives that tools like this could build on top of. # 21st August 2022, 5:40 pm

 sqlite-zstd: Transparent dictionary-based row-level compression for SQLite. Interesting SQLite extension from phiresky, the author of that amazing SQLite WASM hack from a while ago which could fetch subsets of a large SQLite database using the HTTP range header. This extension, written in Rust, implements row-level compression for a SQLite table by creating compression dictionaries for larger chunks of the table, providing better results than just running compression against each row value individually. # 9th August 2022, 9:23 pm

 The State of WebAssembly 2022. Colin Eberhardt talks through the results of the State of WebAssembly 2022 survey. Rust continues to dominate as the most popular language for working to WebAssembly, but Python has a notable increase of interest. # 20th June 2022, 6:07 pm

 Why Rust’s postfix await syntax is good (via) C J Silverio explains postfix await in Rust—where you can write a line like this, with the ? causing any errors to be caught and turned into an error return from your function: let count = fetch_all_animals().await?.filter_for_hedgehogs().len(); # 15th May 2022, 2:27 pm

 jless (via) A really nice new command-line JSON viewer, written in Rust, created by Paul Julius Martinez. It provides a terminal interface for navigating through large JSON files, including expanding and contracting nested objects and searching for strings or a modified form of regular expressions. # 12th February 2022, 3:17 am

 Writing a minimal Lua implementation with a virtual machine from scratch in Rust. Phil Eaton implements a subset of Lua in a Rust in this detailed tutorial. # 15th January 2022, 6:29 pm

 Announcing Parcel CSS: A new CSS parser, compiler, and minifier written in Rust! An interesting thing about tools like this being written in Rust is that since the Rust-to-WASM pipeline is well trodden at this point, the live demo that this announcement links to runs entirely in the browser. # 13th January 2022, 8:40 pm

 2021

 Introducing stack graphs (via) GitHub launched “precise code navigation” for Python today—the first language to get support for this feature. Click on any Python symbol in GitHub’s code browsing views and a box will show you exactly where that symbol was defined—all based on static analysis by a custom parser written in Rust as opposed to executing any Python code directly. The underlying computer science uses a technique called stack graphs, based on scope graphs research from Eelco Visser’s research group at TU Delft. # 9th December 2021, 11:07 pm

 Hurl (via) Hurl is “a command line tool that runs HTTP requests defined in a simple plain text format”—written in Rust on top of curl, it lets you run HTTP requests and then execute assertions against the response, defined using JSONPath or XPath for HTML. It can even assert that responses were returned within a specified duration. # 22nd November 2021, 3:32 am

 A half-hour to learn Rust. I haven’t tried to write any Rust yet but I occasionally find myself wanting to read it, and I find some of the syntax really difficult to get my head around. This article helped a lot: it provides a quick but thorough introduction to most of Rust’s syntax, with clearly explained snippet examples for each one. # 5th November 2021, 5:21 am

 aws-lambda-adapter. AWS Lambda added support for Docker containers last year, but with a very weird shape: you can run anything on Lambda that fits in a Docker container, but unlike Google Cloud Run your application doesn’t get to speak HTTP: it needs to run code that listens for proprietary AWS lambda events instead. The obvious way to fix this is to run some kind of custom proxy inside the container which turns AWS runtime events into HTTP calls to a regular web application. Serverlessish and re:Web are two open source projects that implemented this, and now AWS have their own implementation of that pattern, written in Rust. # 28th October 2021, 5:04 am

 toyDB: references. toyDB is a “distributed SQL database in Rust, written as a learning project”, with its own implementations of SQL, raft, ACID transactions, B+trees and more. toyDB author Erik Grinaker has assembled a detailed set of references that he used to learn how to build a database—I’d love to see more projects do this, it’s really useful. # 19th July 2021, 12:18 am

 Inserting One Billion Rows in SQLite Under a Minute (via) Avinash Sajjanshetty experiments with accelerating writes to a test table in SQLite, using various SQLite pragmas to accelerate inserts followed by a rewrite of Python code to Rust. Also of note: running the exact same code in PyPy saw a 3.5x speed-up! # 19th July 2021, 12:13 am

 2020

 Internet Archive Software Library: Flash (via) A fantastic new initiative from the Internet Archive: they’re now archiving Flash (.swf) files and serving them for modern browsers using Ruffle, a Flash Player emulator written in Rust and compiled to WebAssembly. They are fully interactive and audio works too. Considering the enormous quantity of creative material released in Flash over the decades this helps fill a big hole in the Internet’s cultural memory. # 19th November 2020, 9:19 pm

 Get Started—Materialize. Materialize is a really interesting new database—“a streaming SQL materialized view engine”. It builds materialized views on top of streaming data sources (such as Kafka)—you define the view using a SQL query, then it figures out how to keep that view up-to-date automatically as new data streams in. It speaks the PostgreSQL protocol so you can talk to it using the psql tool or any PostgreSQL client library. The “get started” guide is particularly impressive: it uses a curl stream of the Wikipedia recent changes API, parsed using a regular expression. And it’s written in Rust, so installing it is as easy as downloading and executing a single binary (though I used Homebrew). # 1st June 2020, 10:11 pm

 Deno 1.0. Deno is a new take on server-side JavaScript from a team lead by Ryan Dahl, who originally created Node.js. It’s built using Rust and crammed with fascinating ideas—like the ability to import code directly from a URL. # 13th May 2020, 11:38 pm

 page 1 / 2 next »

 Related

 sqlite 191 webassembly 36 alexgarcia 9 json 121 servo 3 python 826 databases 85 github 106 crdt 4 async 36
 * Source code
 * ©
 * 2002
 * 2003
 * 2004
 * 2005
 * 2006
 * 2007
 * 2008
 * 2009
 * 2010
 * 2011
 * 2012
 * 2013
 * 2014
 * 2015
 * 2016
 * 2017
 * 2018
 * 2019
 * 2020
 * 2021
 * 2022
 * 2023
42 items tagged “rust”
 
2023
 sqlite-jsonschema. “A SQLite extension for validating JSON objects with JSON Schema”, building on the jsonschema Rust crate. SQLite and JSON are already a great combination—Alex suggests using this extension to implement check constraints to validate JSON columns before inserting into a table, or just to run queries finding existing data that doesn’t match a given schema. # 28th January 2023, 3:50 am
 sqlite-ulid. Alex Garcia’s sqlite-ulid adds lightning-fast SQL functions for generating ULIDs—Universally Unique Lexicographically Sortable Identifiers. These work like UUIDs but are smaller and faster to generate, and can be canonically encoded as a URL-safe 26 character string (UUIDs are 36 characters). Again, this builds on a Rust crate—ulid-rs—and can generate 1 million byte-represented ULIDs with the ulid_bytes() function in just 88.4ms. # 28th January 2023, 3:45 am
 sqlite-fastrand. Alex Garcia just dropped three new SQLite extensions, and I’m going to link to all of them. The first is sqlite-fastrand, which adds new functions for generating random numbers (and alphanumeric characters too). Impressively, these out-perform the default SQLite random() and randomblob() functions by about 1.6-2.6x, thanks to being built on the Rust fastrand crate which builds on wyhash, an extremely fast (though not cryptographically secure) hashing function. # 28th January 2023, 3:41 am
 datasette-granian (via) Granian is a new Python web server—similar to Gunicorn—written in Rust. I built a small plugin that adds a “datasette granian” command starting a Granian server that serves Datasette’s ASGI application, using the same pattern as my existing datasette-gunicorn plugin. # 20th January 2023, 2:12 am
 Servo to Advance in 2023 (via) This is excellent news: Serve, the browser-in-Rust project started by Mozilla in 2012 that produced the Rust programming language, is getting re-activated with four new full-time developers provided by Igalia.
Igalia are a fascinating organization—I hadn’t realized quite how influential they’ve been until I read their Wikipedia page just now
They’ve been around since 2001, and “in 2019 they were the #2 committers to both the WebKit and Chromium codebases and in the top 10 contributors to Gecko/Servo”—including implementing and maintaining CSS Grid Layout! # 16th January 2023, 5:08 pm
 Introducing sqlite-xsv: The Fastest CSV Parser for SQLite. Alex Garcia continues to push the boundaries of SQLite extensions. This new extension in Rust wraps the lightning fast Rust csv crate and provides a new csv_reader() virtual table that can handle regular, gzipped and zstd compressed files. # 14th January 2023, 9:54 pm
2022
  Data-driven performance optimization with Rust and Miri (via) Useful guide to some Rust performance optimization tools. Miri can be used to dump out a detailed JSON profile of a program which can then be opened and explored using the Chrome browser’s performance tool. # 9th December 2022, 5:19 pm
 Introducing sqlite-loadable-rs: A framework for building SQLite Extensions in Rust. Alex Garcia has built a new Rust library for creating SQLite extensions—initially supporting custom scalar functions, virtual tables and table functions and with more types of extension coming soon. This looks very easy to use, partly because the documentation and examples are already delightfully thorough, especially for an initial release. # 7th December 2022, 11:08 pm
 
 Building a BFT JSON CRDT (via) Jacky Zhao describes their project to build a CRDT library for JSON data in Rust, and includes a thorough explanation of what CRDTs are and how they work. “I write this blog post mostly as a note to my past self, distilling a lot of what I’ve learned since into a blog post I wish I had read before going in”—the best kind of blog post! # 21st November 2022, 7:56 pm
 Blessed.rs Crate List (via) Rust doesn’t have a very large standard library, so part of learning Rust is figuring out which of the third-party crates are the best for tackling common problems. This here is an opinionated guide to crates, which looks like it could be really useful. # 7th November 2022, 7:25 pm
 mitsuhiko/insta (via) I asked for recommendations on Twitter for testing libraries in other languages that would give me the same level of delight that I get from pytest. Two people pointed me to insta by Armin Ronacher, a Rust testing framework for “snapshot testing” which automatically records reference values to your repository, so future tests can spot if they change. # 31st October 2022, 1:06 am
 py2rs. Extremely useful document providing resources for learning Rust followed by an extensive collection of common Python tasks (building a list, opening a file, spawning a thread, running a simple web server) and their Rust equivalents. # 7th October 2022, 5:44 pm
 libsql (via) A brand new Apache 2 licensed fork of SQLite. The README explains the rationale behind the project: SQLite itself is open source but not open contribution, and this fork aims to try out new ideas. The most interesting to me so far is a plan to support user defined functions implemented in WebAssembly. The project also intends to use Rust for new feature development. # 4th October 2022, 4:13 pm
 Turning SQLite into a distributed database (via) Heyang Zhou introduces mvSQLite, his brand new open source “SQLite-compatible distributed database” built in Rust on top of Apple’s FoundationDB. This is a very promising looking new entry into the distributed/replicated SQLite space: FoundationDB was designed to provide low-level primitives that tools like this could build on top of. # 21st August 2022, 5:40 pm
 sqlite-zstd: Transparent dictionary-based row-level compression for SQLite. Interesting SQLite extension from phiresky, the author of that amazing SQLite WASM hack from a while ago which could fetch subsets of a large SQLite database using the HTTP range header. This extension, written in Rust, implements row-level compression for a SQLite table by creating compression dictionaries for larger chunks of the table, providing better results than just running compression against each row value individually. # 9th August 2022, 9:23 pm
 The State of WebAssembly 2022. Colin Eberhardt talks through the results of the State of WebAssembly 2022 survey. Rust continues to dominate as the most popular language for working to WebAssembly, but Python has a notable increase of interest. # 20th June 2022, 6:07 pm
 Why Rust’s postfix await syntax is good (via) C J Silverio explains postfix await in Rust—where you can write a line like this, with the ? causing any errors to be caught and turned into an error return from your function:
let count = fetch_all_animals().await?.filter_for_hedgehogs().len(); # 15th May 2022, 2:27 pm
 jless (via) A really nice new command-line JSON viewer, written in Rust, created by Paul Julius Martinez. It provides a terminal interface for navigating through large JSON files, including expanding and contracting nested objects and searching for strings or a modified form of regular expressions. # 12th February 2022, 3:17 am
  Announcing Parcel CSS: A new CSS parser, compiler, and minifier written in Rust! An interesting thing about tools like this being written in Rust is that since the Rust-to-WASM pipeline is well trodden at this point, the live demo that this announcement links to runs entirely in the browser. # 13th January 2022, 8:40 pm
2021
 Introducing stack graphs (via) GitHub launched “precise code navigation” for Python today—the first language to get support for this feature. Click on any Python symbol in GitHub’s code browsing views and a box will show you exactly where that symbol was defined—all based on static analysis by a custom parser written in Rust as opposed to executing any Python code directly. The underlying computer science uses a technique called stack graphs, based on scope graphs research from Eelco Visser’s research group at TU Delft. # 9th December 2021, 11:07 pm
 Hurl (via) Hurl is “a command line tool that runs HTTP requests defined in a simple plain text format”—written in Rust on top of curl, it lets you run HTTP requests and then execute assertions against the response, defined using JSONPath or XPath for HTML. It can even assert that responses were returned within a specified duration. # 22nd November 2021, 3:32 am
 A half-hour to learn Rust. I haven’t tried to write any Rust yet but I occasionally find myself wanting to read it, and I find some of the syntax really difficult to get my head around. This article helped a lot: it provides a quick but thorough introduction to most of Rust’s syntax, with clearly explained snippet examples for each one. # 5th November 2021, 5:21 am
 aws-lambda-adapter. AWS Lambda added support for Docker containers last year, but with a very weird shape: you can run anything on Lambda that fits in a Docker container, but unlike Google Cloud Run your application doesn’t get to speak HTTP: it needs to run code that listens for proprietary AWS lambda events instead. The obvious way to fix this is to run some kind of custom proxy inside the container which turns AWS runtime events into HTTP calls to a regular web application. Serverlessish and re:Web are two open source projects that implemented this, and now AWS have their own implementation of that pattern, written in Rust. # 28th October 2021, 5:04 am
 toyDB: references. toyDB is a “distributed SQL database in Rust, written as a learning project”, with its own implementations of SQL, raft, ACID transactions, B+trees and more. toyDB author Erik Grinaker has assembled a detailed set of references that he used to learn how to build a database—I’d love to see more projects do this, it’s really useful. # 19th July 2021, 12:18 am
 Inserting One Billion Rows in SQLite Under a Minute (via) Avinash Sajjanshetty experiments with accelerating writes to a test table in SQLite, using various SQLite pragmas to accelerate inserts followed by a rewrite of Python code to Rust. Also of note: running the exact same code in PyPy saw a 3.5x speed-up! # 19th July 2021, 12:13 am
2020
 Internet Archive Software Library: Flash (via) A fantastic new initiative from the Internet Archive: they’re now archiving Flash (.swf) files and serving them for modern browsers using Ruffle, a Flash Player emulator written in Rust and compiled to WebAssembly. They are fully interactive and audio works too. Considering the enormous quantity of creative material released in Flash over the decades this helps fill a big hole in the Internet’s cultural memory. # 19th November 2020, 9:19 pm
 Get Started—Materialize. Materialize is a really interesting new database—“a streaming SQL materialized view engine”. It builds materialized views on top of streaming data sources (such as Kafka)—you define the view using a SQL query, then it figures out how to keep that view up-to-date automatically as new data streams in. It speaks the PostgreSQL protocol so you can talk to it using the psql tool or any PostgreSQL client library. The “get started” guide is particularly impressive: it uses a curl stream of the Wikipedia recent changes API, parsed using a regular expression. And it’s written in Rust, so installing it is as easy as downloading and executing a single binary (though I used Homebrew). # 1st June 2020, 10:11 pm
 Deno 1.0. Deno is a new take on server-side JavaScript from a team lead by Ryan Dahl, who originally created Node.js. It’s built using Rust and crammed with fascinating ideas—like the ability to import code directly from a URL. # 13th May 2020, 11:38 pm
Simon Willison’s Weblog
https://simonwillison.net/tags/rust/
https://eli.thegreenplace.net/2022/rust-extension-traits-greppability-and-ides
Rust extension traits, greppability and IDEs
2022-01-29
None
<div><div>
 
 <p>Traits are a central feature of Rust, critical for its implementation of
polymorphism; traits are used for both static (by serving as bounds for generic
parameters) and dynamic (by having trait objects to serve as interfaces)
polymorphism.</p>
<p>This post assumes some familiarity with traits and discusses only a specific
aspect of them - how <em>extension traits</em> affect code readability. To learn the
basics of traits in Rust, the <a href="https://doc.rust-lang.org/book/ch10-02-traits.html">official book</a> is a good starting point.</p>
<div>
<p><a href="https://rust-lang.github.io/rfcs/0445-extension-trait-conventions.html">This Rust RFC</a>
provides a good, short definition of extension traits:</p>
<blockquote>
Extension traits are a programming pattern that makes it possible to add
methods to an existing type outside of the crate defining that type.</blockquote>
<p>For example, here's a trait with a single method:</p>
<div><pre>trait Magic {
 fn magic_num(&amp;self) -&gt; usize;
}
</pre></div>
<p>We can now implement the Magic trait for our types:</p>
<div><pre>struct Foobar {
 name: String,
}
impl Magic for Foobar {
 fn magic_num(&amp;self) -&gt; usize {
 if self.name.is_empty() {
 2
 } else {
 33
 }
 }
}
</pre></div>
<p>Now a FooBar can be passed wherever a Magic is expected. FooBar is a
custom type, but what's really interesting is that we can also implement
Magic for any other type, including types that we did not define. Let's
implement it for bool:</p>
<div><pre>impl Magic for bool {
 fn magic_num(&amp;self) -&gt; usize {
 if *self {
 3
 } else {
 54
 }
 }
}
</pre></div>
<p>We can now write code like true.magic_num() and it will work! We've added
a method to a built-in Rust type. Obviously, we can also implement this trait
for types in the standard library; e.g.:</p>
<div><pre>impl&lt;T&gt; Magic for Vec&lt;T&gt; {
 fn magic_num(&amp;self) -&gt; usize {
 if self.is_empty() {
 10
 } else {
 5
 }
 }
}
</pre></div>
</div>
<div>
<h2>Extension traits in the wild</h2>
<p>Extension traits aren't just a fringe feature; they are widely used in the Rust
ecosystem.</p>
<p>One example is the popular serde crate, which includes code that serializes
and deserializes data structures in multiple formats. One of the traits
serde provides is serde::Serialize; once we import this trait and one of
the concrete serializers serde provides, we can do stuff like <a href="#footnote-1">[1]</a>:</p>
<div><pre>let mut serializer = serde_json::Serializer::new(std::io::stdout());
185.serialize(&amp;mut serializer).unwrap();
</pre></div>
<p>Importing serde::Serialize is critical for this code to work, even though we
don't refer to Serialize anywhere in our code explicitly. Rust requires
traits to be explicitly imported to imbue their methods onto existing types;
otherwise it's hard to avoid naming collisions in case multiple traits from
different crates provide the same methods.</p>
<p>Another example is the byteorder crate, which helps encode numbers into
buffers with explicit length and endianness. To write some numbers into a vector
byte-by-byte, we have to import the relevant trait and enum first, and then
we can call the newly-added methods directly on a vector:</p>
<div><pre>use byteorder::{LittleEndian, WriteBytesExt};
// ...
let mut wv = vec![];
wv.write_u16::&lt;LittleEndian&gt;(259).unwrap();
wv.write_u16::&lt;LittleEndian&gt;(517).unwrap();
</pre></div>
<p>The write_u16 method is part of the WriteBytesExt trait, and it's
implemented on a Vec by the byteorder crate. To be more precise, it's
automatically implemented on any type that implements the Write trait.</p>
<p>Finally, let's look at rayon - a library for simplified data-parallelism. It
provides magical iterators that have the same functionality as iter but
compute their results in parallel, leveraging multiple CPU cores. The rayon
documentation recommends to import the traits the crate injects as follows:</p>
<blockquote>
It is recommended that you import all of these traits at once by adding
use rayon::prelude::* at the top of each module that uses Rayon methods.</blockquote>
<p>Having imported it thus, we can proceed to use Rayon as follows:</p>
<div><pre>let exps = vec![2, 4, 6, 12, 24];
let pows_of_two: Vec&lt;_&gt; = exps.par_iter().map(|n| 2_u64.pow(*n)).collect();
</pre></div>
<p>Note the par_iter, which replaces a regular iter. It's been magically
implemented on a vector, as well as a bunch of other types that support
iteration.</p>
</div>
<div>
<h2>On greppability and code readability</h2>
<p>All these uses of extension traits are pretty cool and useful, no doubt. But
that's not the main point of my post. What I really want to discuss is how the
general approach relates to <em>code readability</em>, which is in my mind one of the
most important aspects of programming we should all be thinking about.</p>
<p>This Rust technique fails the <em>greppability</em> test; it's not a word I made up -
google it! If it's not immediately apparent, greppability means the ability to
explore a code base using textual search tools like grep, git grep,
ripgrep, <a href="https://github.com/eliben/pss/">pss</a> or what have you.</p>
<p>Suppose you encounter this piece of code in a project you're exploring:</p>
<div><pre>let mut wv = vec![];
wv.write_u16::&lt;LittleEndian&gt;(259).unwrap();
</pre></div>
<p>"Interesting", you think, "I didn't know that Vec has a write_u16
method". You quickly check the documentation - indeed, it doesn't! So where is
it coming from? You grep the project... nothing. It's nowhere in the
imports. You examine the imports one by one, and notice the:</p>
<div><pre>use byteorder::{LittleEndian, WriteBytesExt};
</pre></div>
<p>"Aha!", you say, "this imports LittleEndian, so maybe this has to do with
the byteorder crate". You check the documentation of that crate and indeed,
you find the write_u16 method there; phew.</p>
<p>With par_iter you're less lucky. Nothing in imports will catch your eye,
unless you're already familiar with the rayon crate. If you're not, then
use rayon::prelude::* won't ring much of a bell in relation to par_iter.</p>
<p>Of course, you can just google this symbol <a href="https://www.google.com/search?q=rust+par_iter">like this</a> and you'll find it. Or maybe
you don't even understand what the problem is, because your IDE is perfectly
familiar with these symbols and will gladly pop up their documentation when you
hover over them.</p>
</div>
<div>
<h2>IDEs and language servers</h2>
<p>These days we have free, powerful and fast IDEs that make all of this a
non-issue (looking at Visual Studio Code, of course). Coupled with smart
<em>language servers</em>, these IDEs are as familiar with your code as the compiler;
the language servers typically run a full front-end sequence on the code, ending
up with type-checked ASTs cross-referenced with symbol tables that let them
understand where each symbol is coming from, its type and so on. For Rust the
language server is RLS, for Go its gopls; all popular languages have them these
days <a href="#footnote-2">[2]</a>.</p>
<p>It's entirely possible that using a language like Rust without a sophisticated
IDE is madness, and I'm somewhat stuck in the past. But I have to say, I do
lament the loss of greppability. There's something very universal about being
able to understand a project using only grep and the official documentation.</p>
<p>In fact, for some languages it's likely that this has been the case for a long
while already. Who in their right mind has the courage to tackle a Java project
without an IDE? It's just that this wasn't always the case for systems
programming languages, and Rust going this way makes me slightly sad. Or maybe
I'm just too indoctrinated in Go at this point, where all symbol access happens
as package.Symbol, packages are imported explicitly and there is no magic
name injection anywhere (almost certainly by design).</p>
<p>I can't exactly put my finger on why this is bothering me; perhaps I'm just
<a href="https://knowyourmeme.com/memes/old-man-yells-at-cloud">yelling at clouds</a>
here. While I'm at it, I should finally write that post about printf-based
debugging...</p>
<hr />
<table>
<colgroup><col></col><col></col></colgroup>
<tbody>
<tr><td><a href="#footnote-reference-1">[1]</a></td><td>Note that it could be simpler to use serde's to_json function
here, but I opted for the explicit serializer because I wanted to show
how we invoke a new method on an integer literal.</td></tr>
</tbody>
</table>
<table>
<colgroup><col></col><col></col></colgroup>
<tbody>
<tr><td><a href="#footnote-reference-2">[2]</a></td><td>Apparently, not all tooling has access to sophisticated language servers;
for example, as far as I can tell GitHub source analysis won't be able to
find where write_u16 is coming from, and the same is true of
<a href="https://sourcegraph.com/">Sourcegraph</a>'s default configuration (though
I've been told this is in the works).</td></tr>
</tbody>
</table>
</div>
 </div>||||I|||| Toggle navigation Eli Bendersky's website
 * About
 * Archives

 Rust extension traits, greppability and IDEs

 January 29, 2022 at 06:16 Tags Rust , Software & Tools

 Traits are a central feature of Rust, critical for its implementation of polymorphism; traits are used for both static (by serving as bounds for generic parameters) and dynamic (by having trait objects to serve as interfaces) polymorphism.

 This post assumes some familiarity with traits and discusses only a specific aspect of them - how extension traits affect code readability. To learn the basics of traits in Rust, the official book is a good starting point.

 Extension traits

 This Rust RFC provides a good, short definition of extension traits:

 Extension traits are a programming pattern that makes it possible to add methods to an existing type outside of the crate defining that type.

 For example, here's a trait with a single method:

 trait Magic {
 fn magic_num(&self) -> usize;
 }
 

 We can now implement the Magic trait for our types:

 struct Foobar {
 name: String,
 }
 
 impl Magic for Foobar {
 fn magic_num(&self) -> usize {
 if self.name.is_empty() {
 2
 } else {
 33
 }
 }
 }
 

 Now a FooBar can be passed wherever a Magic is expected. FooBar is a custom type, but what's really interesting is that we can also implement Magic for any other type, including types that we did not define. Let's implement it for bool:

 impl Magic for bool {
 fn magic_num(&self) -> usize {
 if *self {
 3
 } else {
 54
 }
 }
 }
 

 We can now write code like true.magic_num() and it will work! We've added a method to a built-in Rust type. Obviously, we can also implement this trait for types in the standard library; e.g.:

 impl<T> Magic for Vec<T> {
 fn magic_num(&self) -> usize {
 if self.is_empty() {
 10
 } else {
 5
 }
 }
 }
 

 Extension traits in the wild

 Extension traits aren't just a fringe feature; they are widely used in the Rust ecosystem.

 One example is the popular serde crate, which includes code that serializes and deserializes data structures in multiple formats. One of the traits serde provides is serde::Serialize ; once we import this trait and one of the concrete serializers serde provides, we can do stuff like [1]:

 let mut serializer = serde_json::Serializer::new(std::io::stdout());
 185.serialize(&mut serializer).unwrap();
 

 Importing serde::Serialize is critical for this code to work, even though we don't refer to Serialize anywhere in our code explicitly. Rust requires traits to be explicitly imported to imbue their methods onto existing types; otherwise it's hard to avoid naming collisions in case multiple traits from different crates provide the same methods.

 Another example is the byteorder crate, which helps encode numbers into buffers with explicit length and endianness. To write some numbers into a vector byte-by-byte, we have to import the relevant trait and enum first, and then we can call the newly-added methods directly on a vector:

 use byteorder::{LittleEndian, WriteBytesExt};
 
 // ...
 
 let mut wv = vec![];
 wv.write_u16::<LittleEndian>(259).unwrap();
 wv.write_u16::<LittleEndian>(517).unwrap();
 

 The write_u16 method is part of the WriteBytesExt trait, and it's implemented on a Vec by the byteorder crate. To be more precise, it's automatically implemented on any type that implements the Write trait.

 Finally, let's look at rayon - a library for simplified data-parallelism. It provides magical iterators that have the same functionality as iter but compute their results in parallel, leveraging multiple CPU cores. The rayon documentation recommends to import the traits the crate injects as follows:

 It is recommended that you import all of these traits at once by adding use rayon::prelude::* at the top of each module that uses Rayon methods.

 Having imported it thus, we can proceed to use Rayon as follows:

 let exps = vec![2, 4, 6, 12, 24];
 let pows_of_two: Vec<_> = exps.par_iter().map(|n| 2_u64.pow(*n)).collect();
 

 Note the par_iter, which replaces a regular iter. It's been magically implemented on a vector, as well as a bunch of other types that support iteration.

 On greppability and code readability

 All these uses of extension traits are pretty cool and useful, no doubt. But that's not the main point of my post. What I really want to discuss is how the general approach relates to code readability, which is in my mind one of the most important aspects of programming we should all be thinking about.

 This Rust technique fails the greppability test; it's not a word I made up - google it! If it's not immediately apparent, greppability means the ability to explore a code base using textual search tools like grep, git grep, ripgrep, pss or what have you.

 Suppose you encounter this piece of code in a project you're exploring:

 let mut wv = vec![];
 wv.write_u16::<LittleEndian>(259).unwrap();
 

 "Interesting", you think, "I didn't know that Vec has a write_u16 method". You quickly check the documentation - indeed, it doesn't! So where is it coming from? You grep the project... nothing. It's nowhere in the imports. You examine the imports one by one, and notice the:

 use byteorder::{LittleEndian, WriteBytesExt};
 

 "Aha!", you say, "this imports LittleEndian, so maybe this has to do with the byteorder crate". You check the documentation of that crate and indeed, you find the write_u16 method there; phew.

 With par_iter you're less lucky. Nothing in imports will catch your eye, unless you're already familiar with the rayon crate. If you're not, then use rayon::prelude::* won't ring much of a bell in relation to par_iter.

 Of course, you can just google this symbol like this and you'll find it. Or maybe you don't even understand what the problem is, because your IDE is perfectly familiar with these symbols and will gladly pop up their documentation when you hover over them.

 IDEs and language servers

 These days we have free, powerful and fast IDEs that make all of this a non-issue (looking at Visual Studio Code, of course). Coupled with smart language servers, these IDEs are as familiar with your code as the compiler; the language servers typically run a full front-end sequence on the code, ending up with type-checked ASTs cross-referenced with symbol tables that let them understand where each symbol is coming from, its type and so on. For Rust the language server is RLS, for Go its gopls; all popular languages have them these days [2].

 It's entirely possible that using a language like Rust without a sophisticated IDE is madness, and I'm somewhat stuck in the past. But I have to say, I do lament the loss of greppability. There's something very universal about being able to understand a project using only grep and the official documentation.

 In fact, for some languages it's likely that this has been the case for a long while already. Who in their right mind has the courage to tackle a Java project without an IDE? It's just that this wasn't always the case for systems programming languages, and Rust going this way makes me slightly sad. Or maybe I'm just too indoctrinated in Go at this point, where all symbol access happens as package.Symbol, packages are imported explicitly and there is no magic name injection anywhere (almost certainly by design).

 I can't exactly put my finger on why this is bothering me; perhaps I'm just yelling at clouds here. While I'm at it, I should finally write that post about printf-based debugging...

 [1] Note that it could be simpler to use serde's to_json function here, but I opted for the explicit serializer because I wanted to show how we invoke a new method on an integer literal.
 
 [2] Apparently, not all tooling has access to sophisticated language servers; for example, as far as I can tell GitHub source analysis won't be able to find where write_u16 is coming from, and the same is true of Sourcegraph's default configuration (though I've been told this is in the works).
 

 For comments, please send me an email.

 © 2003-2023 Eli Bendersky

 Back to top

Traits are a central feature of Rust, critical for its implementation of
polymorphism; traits are used for both static (by serving as bounds for generic
parameters) and dynamic (by having trait objects to serve as interfaces)
polymorphism.
This post assumes some familiarity with traits and discusses only a specific
aspect of them - how extension traits affect code readability. To learn the
basics of traits in Rust, the official book is a good starting point.
 This Rust RFC
provides a good, short definition of extension traits:
Extension traits are a programming pattern that makes it possible to add
methods to an existing type outside of the crate defining that type.
For example, here's a trait with a single method:
 trait Magic {
 fn magic_num(&amp;self) -&gt; usize;
}
 
We can now implement the Magic trait for our types:
 struct Foobar {
 name: String,
}
impl Magic for Foobar {
 fn magic_num(&amp;self) -&gt; usize {
 if self.name.is_empty() {
 2
 } else {
 33
 }
 }
}
 
Now a FooBar can be passed wherever a Magic is expected. FooBar is a
custom type, but what's really interesting is that we can also implement
Magic for any other type, including types that we did not define. Let's
implement it for bool:
 impl Magic for bool {
 fn magic_num(&amp;self) -&gt; usize {
 if *self {
 3
 } else {
 54
 }
 }
}
 
We can now write code like true.magic_num() and it will work! We've added
a method to a built-in Rust type. Obviously, we can also implement this trait
for types in the standard library; e.g.:
 impl&lt;T&gt; Magic for Vec&lt;T&gt; {
 fn magic_num(&amp;self) -&gt; usize {
 if self.is_empty() {
 10
 } else {
 5
 }
 }
}
 
Extension traits in the wild
Extension traits aren't just a fringe feature; they are widely used in the Rust
ecosystem.
One example is the popular serde crate, which includes code that serializes
and deserializes data structures in multiple formats. One of the traits
serde provides is serde::Serialize; once we import this trait and one of
the concrete serializers serde provides, we can do stuff like [1]:
 let mut serializer = serde_json::Serializer::new(std::io::stdout());
185.serialize(&amp;mut serializer).unwrap();
 
Importing serde::Serialize is critical for this code to work, even though we
don't refer to Serialize anywhere in our code explicitly. Rust requires
traits to be explicitly imported to imbue their methods onto existing types;
otherwise it's hard to avoid naming collisions in case multiple traits from
different crates provide the same methods.
Another example is the byteorder crate, which helps encode numbers into
buffers with explicit length and endianness. To write some numbers into a vector
byte-by-byte, we have to import the relevant trait and enum first, and then
we can call the newly-added methods directly on a vector:
 use byteorder::{LittleEndian, WriteBytesExt};
// ...
let mut wv = vec![];
wv.write_u16::&lt;LittleEndian&gt;(259).unwrap();
wv.write_u16::&lt;LittleEndian&gt;(517).unwrap();
 
The write_u16 method is part of the WriteBytesExt trait, and it's
implemented on a Vec by the byteorder crate. To be more precise, it's
automatically implemented on any type that implements the Write trait.
Finally, let's look at rayon - a library for simplified data-parallelism. It
provides magical iterators that have the same functionality as iter but
compute their results in parallel, leveraging multiple CPU cores. The rayon
documentation recommends to import the traits the crate injects as follows:
It is recommended that you import all of these traits at once by adding
use rayon::prelude::* at the top of each module that uses Rayon methods.
Having imported it thus, we can proceed to use Rayon as follows:
 let exps = vec![2, 4, 6, 12, 24];
let pows_of_two: Vec&lt;_&gt; = exps.par_iter().map(|n| 2_u64.pow(*n)).collect();
 
Note the par_iter, which replaces a regular iter. It's been magically
implemented on a vector, as well as a bunch of other types that support
iteration.
On greppability and code readability
All these uses of extension traits are pretty cool and useful, no doubt. But
that's not the main point of my post. What I really want to discuss is how the
general approach relates to code readability, which is in my mind one of the
most important aspects of programming we should all be thinking about.
This Rust technique fails the greppability test; it's not a word I made up -
google it! If it's not immediately apparent, greppability means the ability to
explore a code base using textual search tools like grep, git grep,
ripgrep, pss or what have you.
Suppose you encounter this piece of code in a project you're exploring:
 let mut wv = vec![];
wv.write_u16::&lt;LittleEndian&gt;(259).unwrap();
 
"Interesting", you think, "I didn't know that Vec has a write_u16
method". You quickly check the documentation - indeed, it doesn't! So where is
it coming from? You grep the project... nothing. It's nowhere in the
imports. You examine the imports one by one, and notice the:
 use byteorder::{LittleEndian, WriteBytesExt};
 
"Aha!", you say, "this imports LittleEndian, so maybe this has to do with
the byteorder crate". You check the documentation of that crate and indeed,
you find the write_u16 method there; phew.
With par_iter you're less lucky. Nothing in imports will catch your eye,
unless you're already familiar with the rayon crate. If you're not, then
use rayon::prelude::* won't ring much of a bell in relation to par_iter.
Of course, you can just google this symbol like this and you'll find it. Or maybe
you don't even understand what the problem is, because your IDE is perfectly
familiar with these symbols and will gladly pop up their documentation when you
hover over them.
IDEs and language servers
These days we have free, powerful and fast IDEs that make all of this a
non-issue (looking at Visual Studio Code, of course). Coupled with smart
language servers, these IDEs are as familiar with your code as the compiler;
the language servers typically run a full front-end sequence on the code, ending
up with type-checked ASTs cross-referenced with symbol tables that let them
understand where each symbol is coming from, its type and so on. For Rust the
language server is RLS, for Go its gopls; all popular languages have them these
days [2].
It's entirely possible that using a language like Rust without a sophisticated
IDE is madness, and I'm somewhat stuck in the past. But I have to say, I do
lament the loss of greppability. There's something very universal about being
able to understand a project using only grep and the official documentation.
In fact, for some languages it's likely that this has been the case for a long
while already. Who in their right mind has the courage to tackle a Java project
without an IDE? It's just that this wasn't always the case for systems
programming languages, and Rust going this way makes me slightly sad. Or maybe
I'm just too indoctrinated in Go at this point, where all symbol access happens
as package.Symbol, packages are imported explicitly and there is no magic
name injection anywhere (almost certainly by design).
I can't exactly put my finger on why this is bothering me; perhaps I'm just
yelling at clouds
here. While I'm at it, I should finally write that post about printf-based
debugging...
     
  [1]  Note that it could be simpler to use serde's to_json function
here, but I opted for the explicit serializer because I wanted to show
how we invoke a new method on an integer literal. 
     
  [2]  Apparently, not all tooling has access to sophisticated language servers;
for example, as far as I can tell GitHub source analysis won't be able to
find where write_u16 is coming from, and the same is true of
Sourcegraph's default configuration (though
I've been told this is in the works).
Rust extension traits, greppability and IDEs
https://eli.thegreenplace.net/2022/rust-extension-traits-greppability-and-ides/
https://man7.org/linux/man-pages/man1/grep.1.html
grep(1) — Linux manual page
2022-12-18
None
<div>
 
<hr />
<pre>GREP(1) User Commands GREP(1)
</pre>
<h2><a href="#NAME"></a>NAME         <a href="#top_of_page">top</a></h2><pre> grep - print lines that match patterns
</pre>
<h2><a href="#SYNOPSIS"></a>SYNOPSIS         <a href="#top_of_page">top</a></h2><pre> <b>grep </b>[<i>OPTION</i>...] <i>PATTERNS</i> [<i>FILE</i>...]
 <b>grep </b>[<i>OPTION</i>...] <b>-e </b><i>PATTERNS</i> ... [<i>FILE</i>...]
 <b>grep </b>[<i>OPTION</i>...] <b>-f </b><i>PATTERN_FILE</i> ... [<i>FILE</i>...]
</pre>
<h2><a href="#DESCRIPTION"></a>DESCRIPTION         <a href="#top_of_page">top</a></h2><pre> <b>grep </b>searches for <i>PATTERNS</i> in each <i>FILE</i>. <i>PATTERNS</i> is one or more
 patterns separated by newline characters, and <b>grep </b>prints each
 line that matches a pattern. Typically <i>PATTERNS</i> should be quoted
 when <b>grep </b>is used in a shell command.
 A <i>FILE</i> of â<b>-</b>â stands for standard input. If no <i>FILE</i> is given,
 recursive searches examine the working directory, and
 nonrecursive searches read standard input.
</pre>
<h2><a href="#OPTIONS"></a>OPTIONS         <a href="#top_of_page">top</a></h2><pre> <b>Generic Program Information</b>
 <b>--help </b>Output a usage message and exit.
 <b>-V</b>, <b>--version</b>
 Output the version number of <b>grep </b>and exit.
 <b>Pattern Syntax</b>
 <b>-E</b>, <b>--extended-regexp</b>
 Interpret <i>PATTERNS</i> as extended regular expressions (EREs,
 see below).
 <b>-F</b>, <b>--fixed-strings</b>
 Interpret <i>PATTERNS</i> as fixed strings, not regular
 expressions.
 <b>-G</b>, <b>--basic-regexp</b>
 Interpret <i>PATTERNS</i> as basic regular expressions (BREs, see
 below). This is the default.
 <b>-P</b>, <b>--perl-regexp</b>
 Interpret <i>PATTERNS</i> as Perl-compatible regular expressions
 (PCREs). This option is experimental when combined with
 the <b>-z </b>(<b>--null-data</b>) option, and <b>grep -P </b>may warn of
 unimplemented features.
 <b>Matching Control</b>
 <b>-e </b><i>PATTERNS</i>, <b>--regexp=</b><i>PATTERNS</i>
 Use <i>PATTERNS</i> as the patterns. If this option is used
 multiple times or is combined with the <b>-f </b>(<b>--file</b>) option,
 search for all patterns given. This option can be used to
 protect a pattern beginning with â-â.
 <b>-f </b><i>FILE</i>, <b>--file=</b><i>FILE</i>
 Obtain patterns from <i>FILE</i>, one per line. If this option
 is used multiple times or is combined with the <b>-e</b>
 (<b>--regexp</b>) option, search for all patterns given. The
 empty file contains zero patterns, and therefore matches
 nothing.
 <b>-i</b>, <b>--ignore-case</b>
 Ignore case distinctions in patterns and input data, so
 that characters that differ only in case match each other.
 <b>--no-ignore-case</b>
 Do not ignore case distinctions in patterns and input
 data. This is the default. This option is useful for
 passing to shell scripts that already use <b>-i</b>, to cancel
 its effects because the two options override each other.
 <b>-v</b>, <b>--invert-match</b>
 Invert the sense of matching, to select non-matching
 lines.
 <b>-w</b>, <b>--word-regexp</b>
 Select only those lines containing matches that form whole
 words. The test is that the matching substring must
 either be at the beginning of the line, or preceded by a
 non-word constituent character. Similarly, it must be
 either at the end of the line or followed by a non-word
 constituent character. Word-constituent characters are
 letters, digits, and the underscore. This option has no
 effect if <b>-x </b>is also specified.
 <b>-x</b>, <b>--line-regexp</b>
 Select only those matches that exactly match the whole
 line. For a regular expression pattern, this is like
 parenthesizing the pattern and then surrounding it with <b>^</b>
 and <b>$</b>.
 <b>General Output Control</b>
 <b>-c</b>, <b>--count</b>
 Suppress normal output; instead print a count of matching
 lines for each input file. With the <b>-v</b>, <b>--invert-match</b>
 option (see above), count non-matching lines.
 <b>--color</b>[<b>=</b><i>WHEN</i>], <b>--colour</b>[<b>=</b><i>WHEN</i>]
 Surround the matched (non-empty) strings, matching lines,
 context lines, file names, line numbers, byte offsets, and
 separators (for fields and groups of context lines) with
 escape sequences to display them in color on the terminal.
 The colors are defined by the environment variable
 <b>GREP_COLORS</b>. <i>WHEN</i> is <b>never</b>, <b>always</b>, or <b>auto</b>.
 <b>-L</b>, <b>--files-without-match</b>
 Suppress normal output; instead print the name of each
 input file from which no output would normally have been
 printed.
 <b>-l</b>, <b>--files-with-matches</b>
 Suppress normal output; instead print the name of each
 input file from which output would normally have been
 printed. Scanning each input file stops upon first match.
 <b>-m </b><i>NUM</i>, <b>--max-count=</b><i>NUM</i>
 Stop reading a file after <i>NUM</i> matching lines. If <i>NUM</i> is
 zero, <b>grep </b>stops right away without reading input. A <i>NUM</i>
 of -1 is treated as infinity and <b>grep </b>does not stop; this
 is the default. If the input is standard input from a
 regular file, and <i>NUM</i> matching lines are output, <b>grep</b>
 ensures that the standard input is positioned to just
 after the last matching line before exiting, regardless of
 the presence of trailing context lines. This enables a
 calling process to resume a search. When <b>grep </b>stops after
 <i>NUM</i> matching lines, it outputs any trailing context lines.
 When the <b>-c </b>or <b>--count </b>option is also used, <b>grep </b>does not
 output a count greater than <i>NUM</i>. When the <b>-v </b>or
 <b>--invert-match </b>option is also used, <b>grep </b>stops after
 outputting <i>NUM</i> non-matching lines.
 <b>-o</b>, <b>--only-matching</b>
 Print only the matched (non-empty) parts of a matching
 line, with each such part on a separate output line.
 <b>-q</b>, <b>--quiet</b>, <b>--silent</b>
 Quiet; do not write anything to standard output. Exit
 immediately with zero status if any match is found, even
 if an error was detected. Also see the <b>-s </b>or
 <b>--no-messages </b>option.
 <b>-s</b>, <b>--no-messages</b>
 Suppress error messages about nonexistent or unreadable
 files.
 <b>Output Line Prefix Control</b>
 <b>-b</b>, <b>--byte-offset</b>
 Print the 0-based byte offset within the input file before
 each line of output. If <b>-o </b>(<b>--only-matching</b>) is
 specified, print the offset of the matching part itself.
 <b>-H</b>, <b>--with-filename</b>
 Print the file name for each match. This is the default
 when there is more than one file to search. This is a GNU
 extension.
 <b>-h</b>, <b>--no-filename</b>
 Suppress the prefixing of file names on output. This is
 the default when there is only one file (or only standard
 input) to search.
 <b>--label=</b><i>LABEL</i>
 Display input actually coming from standard input as input
 coming from file <i>LABEL</i>. This can be useful for commands
 that transform a file's contents before searching, e.g.,
 <b>gzip -cd foo.gz | grep --label=foo -H 'some pattern'</b>. See
 also the <b>-H </b>option.
 <b>-n</b>, <b>--line-number</b>
 Prefix each line of output with the 1-based line number
 within its input file.
 <b>-T</b>, <b>--initial-tab</b>
 Make sure that the first character of actual line content
 lies on a tab stop, so that the alignment of tabs looks
 normal. This is useful with options that prefix their
 output to the actual content: <b>-H</b>,<b>-n</b>, and <b>-b</b>. In order to
 improve the probability that lines from a single file will
 all start at the same column, this also causes the line
 number and byte offset (if present) to be printed in a
 minimum size field width.
 <b>-Z</b>, <b>--null</b>
 Output a zero byte (the ASCII <b>NUL </b>character) instead of
 the character that normally follows a file name. For
 example, <b>grep -lZ </b>outputs a zero byte after each file name
 instead of the usual newline. This option makes the
 output unambiguous, even in the presence of file names
 containing unusual characters like newlines. This option
 can be used with commands like <b>find -print0</b>, <b>perl -0</b>, <b>sort</b>
 <b>-z</b>, and <b>xargs -0 </b>to process arbitrary file names, even
 those that contain newline characters.
 <b>Context Line Control</b>
 <b>-A </b><i>NUM</i>, <b>--after-context=</b><i>NUM</i>
 Print <i>NUM</i> lines of trailing context after matching lines.
 Places a line containing a group separator (<b>--</b>) between
 contiguous groups of matches. With the <b>-o </b>or
 <b>--only-matching </b>option, this has no effect and a warning
 is given.
 <b>-B </b><i>NUM</i>, <b>--before-context=</b><i>NUM</i>
 Print <i>NUM</i> lines of leading context before matching lines.
 Places a line containing a group separator (<b>--</b>) between
 contiguous groups of matches. With the <b>-o </b>or
 <b>--only-matching </b>option, this has no effect and a warning
 is given.
 <b>-C </b><i>NUM</i>, <b>-</b><i>NUM</i>, <b>--context=</b><i>NUM</i>
 Print <i>NUM</i> lines of output context. Places a line
 containing a group separator (<b>--</b>) between contiguous
 groups of matches. With the <b>-o </b>or <b>--only-matching </b>option,
 this has no effect and a warning is given.
 <b>--group-separator=</b><i>SEP</i>
 When <b>-A</b>, <b>-B</b>, or <b>-C </b>are in use, print <i>SEP</i> instead of <b>--</b>
 between groups of lines.
 <b>--no-group-separator</b>
 When <b>-A</b>, <b>-B</b>, or <b>-C </b>are in use, do not print a separator
 between groups of lines.
 <b>File and Directory Selection</b>
 <b>-a</b>, <b>--text</b>
 Process a binary file as if it were text; this is
 equivalent to the <b>--binary-files=text </b>option.
 <b>--binary-files=</b><i>TYPE</i>
 If a file's data or metadata indicate that the file
 contains binary data, assume that the file is of type
 <i>TYPE</i>. Non-text bytes indicate binary data; these are
 either output bytes that are improperly encoded for the
 current locale, or null input bytes when the <b>-z </b>option is
 not given.
 By default, <i>TYPE</i> is <b>binary</b>, and <b>grep </b>suppresses output
 after null input binary data is discovered, and suppresses
 output lines that contain improperly encoded data. When
 some output is suppressed, <b>grep </b>follows any output with a
 message to standard error saying that a binary file
 matches.
 If <i>TYPE</i> is <b>without-match</b>, when <b>grep </b>discovers null input
 binary data it assumes that the rest of the file does not
 match; this is equivalent to the <b>-I </b>option.
 If <i>TYPE</i> is <b>text</b>, <b>grep </b>processes a binary file as if it
 were text; this is equivalent to the <b>-a </b>option.
 When <i>type</i> is <b>binary</b>, <b>grep </b>may treat non-text bytes as line
 terminators even without the <b>-z </b>option. This means
 choosing <b>binary </b>versus <b>text </b>can affect whether a pattern
 matches a file. For example, when <i>type</i> is <b>binary </b>the
 pattern <b>q$ might </b>match <b>q </b>immediately followed by a null
 byte, even though this is not matched when <i>type</i> is <b>text</b>.
 Conversely, when <i>type</i> is <b>binary </b>the pattern <b>. </b>(period)
 might not match a null byte.
 <i>Warning:</i> The <b>-a </b>option might output binary garbage, which
 can have nasty side effects if the output is a terminal
 and if the terminal driver interprets some of it as
 commands. On the other hand, when reading files whose
 text encodings are unknown, it can be helpful to use <b>-a </b>or
 to set <b>LC_ALL='C' </b>in the environment, in order to find
 more matches even if the matches are unsafe for direct
 display.
 <b>-D </b><i>ACTION</i>, <b>--devices=</b><i>ACTION</i>
 If an input file is a device, FIFO or socket, use <i>ACTION</i>
 to process it. By default, <i>ACTION</i> is <b>read</b>, which means
 that devices are read just as if they were ordinary files.
 If <i>ACTION</i> is <b>skip</b>, devices are silently skipped.
 <b>-d </b><i>ACTION</i>, <b>--directories=</b><i>ACTION</i>
 If an input file is a directory, use <i>ACTION</i> to process it.
 By default, <i>ACTION</i> is <b>read</b>, i.e., read directories just as
 if they were ordinary files. If <i>ACTION</i> is <b>skip</b>, silently
 skip directories. If <i>ACTION</i> is <b>recurse</b>, read all files
 under each directory, recursively, following symbolic
 links only if they are on the command line. This is
 equivalent to the <b>-r </b>option.
 <b>--exclude=</b><i>GLOB</i>
 Skip any command-line file with a name suffix that matches
 the pattern <i>GLOB</i>, using wildcard matching; a name suffix
 is either the whole name, or a trailing part that starts
 with a non-slash character immediately after a slash (<b>/</b>)
 in the name. When searching recursively, skip any subfile
 whose base name matches <i>GLOB</i>; the base name is the part
 after the last slash. A pattern can use <b>*</b>, <b>?</b>, and <b>[</b>...<b>]</b>
 as wildcards, and <b>\ </b>to quote a wildcard or backslash
 character literally.
 <b>--exclude-from=</b><i>FILE</i>
 Skip files whose base name matches any of the file-name
 globs read from <i>FILE</i> (using wildcard matching as described
 under <b>--exclude</b>).
 <b>--exclude-dir=</b><i>GLOB</i>
 Skip any command-line directory with a name suffix that
 matches the pattern <i>GLOB</i>. When searching recursively,
 skip any subdirectory whose base name matches <i>GLOB</i>.
 Ignore any redundant trailing slashes in <i>GLOB</i>.
 <b>-I </b>Process a binary file as if it did not contain matching
 data; this is equivalent to the
 <b>--binary-files=without-match </b>option.
 <b>--include=</b><i>GLOB</i>
 Search only files whose base name matches <i>GLOB</i> (using
 wildcard matching as described under <b>--exclude</b>). If
 contradictory <b>--include </b>and <b>--exclude </b>options are given,
 the last matching one wins. If no <b>--include </b>or <b>--exclude</b>
 options match, a file is included unless the first such
 option is <b>--include</b>.
 <b>-r</b>, <b>--recursive</b>
 Read all files under each directory, recursively,
 following symbolic links only if they are on the command
 line. Note that if no file operand is given, <b>grep</b>
 searches the working directory. This is equivalent to the
 <b>-d recurse </b>option.
 <b>-R</b>, <b>--dereference-recursive</b>
 Read all files under each directory, recursively. Follow
 all symbolic links, unlike <b>-r</b>.
 <b>Other Options</b>
 <b>--line-buffered</b>
 Use line buffering on output. This can cause a
 performance penalty.
 <b>-U</b>, <b>--binary</b>
 Treat the file(s) as binary. By default, under MS-DOS and
 MS-Windows, <b>grep </b>guesses whether a file is text or binary
 as described for the <b>--binary-files </b>option. If <b>grep</b>
 decides the file is a text file, it strips the CR
 characters from the original file contents (to make
 regular expressions with <b>^ </b>and <b>$ </b>work correctly).
 Specifying <b>-U </b>overrules this guesswork, causing all files
 to be read and passed to the matching mechanism verbatim;
 if the file is a text file with CR/LF pairs at the end of
 each line, this will cause some regular expressions to
 fail. This option has no effect on platforms other than
 MS-DOS and MS-Windows.
 <b>-z</b>, <b>--null-data</b>
 Treat input and output data as sequences of lines, each
 terminated by a zero byte (the ASCII NUL character)
 instead of a newline. Like the <b>-Z </b>or <b>--null </b>option, this
 option can be used with commands like <b>sort -z </b>to process
 arbitrary file names.
</pre>
<h2><a href="#REGULAR_EXPRESSIONS"></a>REGULAR EXPRESSIONS         <a href="#top_of_page">top</a></h2><pre> A regular expression is a pattern that describes a set of
 strings. Regular expressions are constructed analogously to
 arithmetic expressions, by using various operators to combine
 smaller expressions.
 <b>grep </b>understands three different versions of regular expression
 syntax: âbasicâ (BRE), âextendedâ (ERE) and âperlâ (PCRE). In
 GNU <b>grep </b>there is no difference in available functionality
 between basic and extended syntax. In other implementations,
 basic regular expressions are less powerful. The following
 description applies to extended regular expressions; differences
 for basic regular expressions are summarized afterwards. Perl-
 compatible regular expressions give additional functionality, and
 are documented in <a href="../man3/pcre2syntax.3.html">pcre2syntax(3)</a> and <a href="../man3/pcre2pattern.3.html">pcre2pattern(3)</a>, but work
 only if PCRE support is enabled.
 The fundamental building blocks are the regular expressions that
 match a single character. Most characters, including all letters
 and digits, are regular expressions that match themselves. Any
 meta-character with special meaning may be quoted by preceding it
 with a backslash.
 The period <b>. </b>matches any single character. It is unspecified
 whether it matches an encoding error.
 <b>Character Classes and Bracket Expressions</b>
 A <i>bracket expression</i> is a list of characters enclosed by <b>[ </b>and <b>]</b>.
 It matches any single character in that list. If the first
 character of the list is the caret <b>^ </b>then it matches any
 character <i>not</i> in the list; it is unspecified whether it matches
 an encoding error. For example, the regular expression
 <b>[0123456789] </b>matches any single digit.
 Within a bracket expression, a <i>range expression</i> consists of two
 characters separated by a hyphen. It matches any single
 character that sorts between the two characters, inclusive, using
 the locale's collating sequence and character set. For example,
 in the default C locale, <b>[a-d] </b>is equivalent to <b>[abcd]</b>. Many
 locales sort characters in dictionary order, and in these locales
 <b>[a-d] </b>is typically not equivalent to <b>[abcd]</b>; it might be
 equivalent to <b>[aBbCcDd]</b>, for example. To obtain the traditional
 interpretation of bracket expressions, you can use the C locale
 by setting the <b>LC_ALL </b>environment variable to the value <b>C</b>.
 Finally, certain named classes of characters are predefined
 within bracket expressions, as follows. Their names are self
 explanatory, and they are <b>[:alnum:]</b>, <b>[:alpha:]</b>, <b>[:blank:]</b>,
 <b>[:cntrl:]</b>, <b>[:digit:]</b>, <b>[:graph:]</b>, <b>[:lower:]</b>, <b>[:print:]</b>, <b>[:punct:]</b>,
 <b>[:space:]</b>, <b>[:upper:]</b>, and <b>[:xdigit:]</b>. For example, <b>[[:alnum:]]</b>
 means the character class of numbers and letters in the current
 locale. In the C locale and ASCII character set encoding, this
 is the same as <b>[0-9A-Za-z]</b>. (Note that the brackets in these
 class names are part of the symbolic names, and must be included
 in addition to the brackets delimiting the bracket expression.)
 Most meta-characters lose their special meaning inside bracket
 expressions. To include a literal <b>] </b>place it first in the list.
 Similarly, to include a literal <b>^ </b>place it anywhere but first.
 Finally, to include a literal <b>- </b>place it last.
 <b>Anchoring</b>
 The caret <b>^ </b>and the dollar sign <b>$ </b>are meta-characters that
 respectively match the empty string at the beginning and end of a
 line.
 <b>The Backslash Character and Special Expressions</b>
 The symbols <b>\&lt; </b>and <b>\&gt; </b>respectively match the empty string at the
 beginning and end of a word. The symbol <b>\b </b>matches the empty
 string at the edge of a word, and <b>\B </b>matches the empty string
 provided it's <i>not</i> at the edge of a word. The symbol <b>\w </b>is a
 synonym for <b>[_[:alnum:]] </b>and <b>\W </b>is a synonym for <b>[^_[:alnum:]]</b>.
 <b>Repetition</b>
 A regular expression may be followed by one of several repetition
 operators:
 <b>? </b>The preceding item is optional and matched at most once.
 <b>* </b>The preceding item will be matched zero or more times.
 <b>+ </b>The preceding item will be matched one or more times.
 <b>{</b><i>n</i><b>} </b>The preceding item is matched exactly <i>n</i> times.
 <b>{</b><i>n</i><b>,} </b>The preceding item is matched <i>n</i> or more times.
 <b>{,</b><i>m</i><b>} </b>The preceding item is matched at most <i>m</i> times. This is a
 GNU extension.
 <b>{</b><i>n</i><b>,</b><i>m</i><b>} </b>The preceding item is matched at least <i>n</i> times, but not
 more than <i>m</i> times.
 <b>Concatenation</b>
 Two regular expressions may be concatenated; the resulting
 regular expression matches any string formed by concatenating two
 substrings that respectively match the concatenated expressions.
 <b>Alternation</b>
 Two regular expressions may be joined by the infix operator <b>|</b>;
 the resulting regular expression matches any string matching
 either alternate expression.
 <b>Precedence</b>
 Repetition takes precedence over concatenation, which in turn
 takes precedence over alternation. A whole expression may be
 enclosed in parentheses to override these precedence rules and
 form a subexpression.
 <b>Back-references and Subexpressions</b>
 The back-reference <b>\</b><i>n</i>, where <i>n</i> is a single digit, matches the
 substring previously matched by the <i>n</i>th parenthesized
 subexpression of the regular expression.
 <b>Basic vs Extended Regular Expressions</b>
 In basic regular expressions the meta-characters <b>?</b>, <b>+</b>, <b>{</b>, <b>|</b>, <b>(</b>,
 and <b>) </b>lose their special meaning; instead use the backslashed
 versions <b>\?</b>, <b>\+</b>, <b>\{</b>, <b>\|</b>, <b>\(</b>, and <b>\)</b>.
</pre>
<h2><a href="#EXIT_STATUS"></a>EXIT STATUS         <a href="#top_of_page">top</a></h2><pre> Normally the exit status is 0 if a line is selected, 1 if no
 lines were selected, and 2 if an error occurred. However, if the
 <b>-q </b>or <b>--quiet </b>or <b>--silent </b>is used and a line is selected, the
 exit status is 0 even if an error occurred.
</pre>
<h2><a href="#ENVIRONMENT"></a>ENVIRONMENT         <a href="#top_of_page">top</a></h2><pre> The behavior of <b>grep </b>is affected by the following environment
 variables.
 The locale for category <b>LC_</b><i>foo</i> is specified by examining the
 three environment variables <b>LC_ALL</b>, <b>LC_</b><i>foo</i>, <b>LANG</b>, in that order.
 The first of these variables that is set specifies the locale.
 For example, if <b>LC_ALL </b>is not set, but <b>LC_MESSAGES </b>is set to
 <b>pt_BR</b>, then the Brazilian Portuguese locale is used for the
 <b>LC_MESSAGES </b>category. The C locale is used if none of these
 environment variables are set, if the locale catalog is not
 installed, or if <b>grep </b>was not compiled with national language
 support (NLS). The shell command <b>locale -a </b>lists locales that
 are currently available.
 <b>GREP_COLORS</b>
 Controls how the <b>--color </b>option highlights output. Its
 value is a colon-separated list of capabilities that
 defaults to
 <b>ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36 </b>with the
 <b>rv </b>and <b>ne </b>boolean capabilities omitted (i.e., false).
 Supported capabilities are as follows.
 <b>sl= </b>SGR substring for whole selected lines (i.e.,
 matching lines when the <b>-v </b>command-line option is
 omitted, or non-matching lines when <b>-v </b>is
 specified). If however the boolean <b>rv </b>capability
 and the <b>-v </b>command-line option are both specified,
 it applies to context matching lines instead. The
 default is empty (i.e., the terminal's default
 color pair).
 <b>cx= </b>SGR substring for whole context lines (i.e., non-
 matching lines when the <b>-v </b>command-line option is
 omitted, or matching lines when <b>-v </b>is specified).
 If however the boolean <b>rv </b>capability and the <b>-v</b>
 command-line option are both specified, it applies
 to selected non-matching lines instead. The
 default is empty (i.e., the terminal's default
 color pair).
 <b>rv </b>Boolean value that reverses (swaps) the meanings of
 the <b>sl= </b>and <b>cx= </b>capabilities when the <b>-v </b>command-
 line option is specified. The default is false
 (i.e., the capability is omitted).
 <b>mt=01;31</b>
 SGR substring for matching non-empty text in any
 matching line (i.e., a selected line when the <b>-v</b>
 command-line option is omitted, or a context line
 when <b>-v </b>is specified). Setting this is equivalent
 to setting both <b>ms= </b>and <b>mc= </b>at once to the same
 value. The default is a bold red text foreground
 over the current line background.
 <b>ms=01;31</b>
 SGR substring for matching non-empty text in a
 selected line. (This is only used when the <b>-v</b>
 command-line option is omitted.) The effect of the
 <b>sl= </b>(or <b>cx= </b>if <b>rv</b>) capability remains active when
 this kicks in. The default is a bold red text
 foreground over the current line background.
 <b>mc=01;31</b>
 SGR substring for matching non-empty text in a
 context line. (This is only used when the <b>-v</b>
 command-line option is specified.) The effect of
 the <b>cx= </b>(or <b>sl= </b>if <b>rv</b>) capability remains active
 when this kicks in. The default is a bold red text
 foreground over the current line background.
 <b>fn=35 </b>SGR substring for file names prefixing any content
 line. The default is a magenta text foreground
 over the terminal's default background.
 <b>ln=32 </b>SGR substring for line numbers prefixing any
 content line. The default is a green text
 foreground over the terminal's default background.
 <b>bn=32 </b>SGR substring for byte offsets prefixing any
 content line. The default is a green text
 foreground over the terminal's default background.
 <b>se=36 </b>SGR substring for separators that are inserted
 between selected line fields (<b>:</b>), between context
 line fields, (<b>-</b>), and between groups of adjacent
 lines when nonzero context is specified (<b>--</b>). The
 default is a cyan text foreground over the
 terminal's default background.
 <b>ne </b>Boolean value that prevents clearing to the end of
 line using Erase in Line (EL) to Right (<b>\33[K</b>) each
 time a colorized item ends. This is needed on
 terminals on which EL is not supported. It is
 otherwise useful on terminals for which the
 <b>back_color_erase </b>(<b>bce</b>) boolean terminfo capability
 does not apply, when the chosen highlight colors do
 not affect the background, or when EL is too slow
 or causes too much flicker. The default is false
 (i.e., the capability is omitted).
 Note that boolean capabilities have no <b>=</b>... part. They
 are omitted (i.e., false) by default and become true when
 specified.
 See the Select Graphic Rendition (SGR) section in the
 documentation of the text terminal that is used for
 permitted values and their meaning as character
 attributes. These substring values are integers in
 decimal representation and can be concatenated with
 semicolons. <b>grep </b>takes care of assembling the result into
 a complete SGR sequence (<b>\33[</b>...<b>m</b>). Common values to
 concatenate include <b>1 </b>for bold, <b>4 </b>for underline, <b>5 </b>for
 blink, <b>7 </b>for inverse, <b>39 </b>for default foreground color, <b>30</b>
 to <b>37 </b>for foreground colors, <b>90 </b>to <b>97 </b>for 16-color mode
 foreground colors, <b>38;5;0 </b>to <b>38;5;255 </b>for 88-color and
 256-color modes foreground colors, <b>49 </b>for default
 background color, <b>40 </b>to <b>47 </b>for background colors, <b>100 </b>to
 <b>107 </b>for 16-color mode background colors, and <b>48;5;0 </b>to
 <b>48;5;255 </b>for 88-color and 256-color modes background
 colors.
 <b>LC_ALL</b>, <b>LC_COLLATE</b>, <b>LANG</b>
 These variables specify the locale for the <b>LC_COLLATE</b>
 category, which determines the collating sequence used to
 interpret range expressions like <b>[a-z]</b>.
 <b>LC_ALL</b>, <b>LC_CTYPE</b>, <b>LANG</b>
 These variables specify the locale for the <b>LC_CTYPE</b>
 category, which determines the type of characters, e.g.,
 which characters are whitespace. This category also
 determines the character encoding, that is, whether text
 is encoded in UTF-8, ASCII, or some other encoding. In
 the C or POSIX locale, all characters are encoded as a
 single byte and every byte is a valid character.
 <b>LC_ALL</b>, <b>LC_MESSAGES</b>, <b>LANG</b>
 These variables specify the locale for the <b>LC_MESSAGES</b>
 category, which determines the language that <b>grep </b>uses for
 messages. The default C locale uses American English
 messages.
 <b>POSIXLY_CORRECT</b>
 If set, <b>grep </b>behaves as POSIX requires; otherwise, <b>grep</b>
 behaves more like other GNU programs. POSIX requires that
 options that follow file names must be treated as file
 names; by default, such options are permuted to the front
 of the operand list and are treated as options. Also,
 POSIX requires that unrecognized options be diagnosed as
 âillegalâ, but since they are not really against the law
 the default is to diagnose them as âinvalidâ.
 <b>POSIXLY_CORRECT </b>also disables
 <b>_</b><i>N</i><b>_GNU_nonoption_argv_flags_</b>, described below.
 <b>_</b><i>N</i><b>_GNU_nonoption_argv_flags_</b>
 (Here <i>N</i> is <b>grep</b>'s numeric process ID.) If the <i>i</i>th
 character of this environment variable's value is <b>1</b>, do
 not consider the <i>i</i>th operand of <b>grep </b>to be an option, even
 if it appears to be one. A shell can put this variable in
 the environment for each command it runs, specifying which
 operands are the results of file name wildcard expansion
 and therefore should not be treated as options. This
 behavior is available only with the GNU C library, and
 only when <b>POSIXLY_CORRECT </b>is not set.
</pre>
<h2><a href="#NOTES"></a>NOTES         <a href="#top_of_page">top</a></h2><pre> This man page is maintained only fitfully; the full documentation
 is often more up-to-date.
</pre>
<h2><a href="#COPYRIGHT"></a>COPYRIGHT         <a href="#top_of_page">top</a></h2><pre> Copyright 1998-2000, 2002, 2005-2022 Free Software Foundation,
 Inc.
 This is free software; see the source for copying conditions.
 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR
 A PARTICULAR PURPOSE.
</pre>
<h2><a href="#BUGS"></a>BUGS         <a href="#top_of_page">top</a></h2><pre> <b>Reporting Bugs</b>
 Email bug reports to the bug-reporting address â¨bug-
 grep@gnu.orgâ©. An email archive 
 â¨<a href="https://lists.gnu.org/mailman/listinfo/bug-grep">https://lists.gnu.org/mailman/listinfo/bug-grep</a>â© and a bug
 tracker â¨<a href="https://debbugs.gnu.org/cgi/pkgreport.cgi?package=grep">https://debbugs.gnu.org/cgi/pkgreport.cgi?package=grep</a>â©
 are available.
 <b>Known Bugs</b>
 Large repetition counts in the <b>{</b><i>n</i><b>,</b><i>m</i><b>} </b>construct may cause <b>grep </b>to
 use lots of memory. In addition, certain other obscure regular
 expressions require exponential time and space, and may cause
 <b>grep </b>to run out of memory.
 Back-references are very slow, and may require exponential time.
</pre>
<h2><a href="#EXAMPLE"></a>EXAMPLE         <a href="#top_of_page">top</a></h2><pre> The following example outputs the location and contents of any
 line containing âfâ and ending in â.câ, within all files in the
 current directory whose names contain âgâ and end in â.hâ. The
 <b>-n </b>option outputs line numbers, the <b>-- </b>argument treats expansions
 of â*g*.hâ starting with â-â as file names not options, and the
 empty file /dev/null causes file names to be output even if only
 one file name happens to be of the form â*g*.hâ.
 $ <b>grep </b>-n -- 'f.*\.c$' *g*.h /dev/null
 argmatch.h:1:/* definitions and prototypes for argmatch.c
 The only line that matches is line 1 of argmatch.h. Note that
 the regular expression syntax used in the pattern differs from
 the globbing syntax that the shell uses to match file names.
</pre>
<h2><a href="#SEE_ALSO"></a>SEE ALSO         <a href="#top_of_page">top</a></h2><pre> <b>Regular Manual Pages</b>
 <b>awk</b>(1), <a href="../man1/cmp.1.html">cmp(1)</a>, <a href="../man1/diff.1.html">diff(1)</a>, <a href="../man1/find.1.html">find(1)</a>, <b>perl</b>(1), <a href="../man1/sed.1.html">sed(1)</a>, <a href="../man1/sort.1.html">sort(1)</a>,
 <a href="../man1/xargs.1.html">xargs(1)</a>, <a href="../man2/read.2.html">read(2)</a>, <a href="../man3/pcre2.3.html">pcre2(3)</a>, <a href="../man3/pcre2syntax.3.html">pcre2syntax(3)</a>, <a href="../man3/pcre2pattern.3.html">pcre2pattern(3)</a>,
 <a href="../man5/terminfo.5.html">terminfo(5)</a>, <a href="../man7/glob.7.html">glob(7)</a>, <a href="../man7/regex.7.html">regex(7)</a>
 <b>Full Documentation</b>
 A complete manual â¨<a href="https://www.gnu.org/software/grep/manual/">https://www.gnu.org/software/grep/manual/</a>â© is
 available. If the <b>info </b>and <b>grep </b>programs are properly installed
 at your site, the command
 <b>info grep</b>
 should give you access to the complete manual.
</pre>
<h2><a href="#COLOPHON"></a>COLOPHON         <a href="#top_of_page">top</a></h2><pre> This page is part of the <i>GNU grep</i> (regular expression file search
 tool) project. Information about the project can be found at 
 â¨<a href="https://www.gnu.org/software/grep/">https://www.gnu.org/software/grep/</a>â©. If you have a bug report
 for this manual page, send it to bug-grep@gnu.org. This page was
 obtained from the project's upstream Git repository
 â¨git://git.savannah.gnu.org/grep.gitâ© on 2022-12-17. (At that
 time, the date of the most recent commit that was found in the
 repository was 2022-12-10.) If you discover any rendering
 problems in this HTML version of the page, or you believe there
 is a better or more up-to-date source for the page, or you have
 corrections or improvements to the information in this COLOPHON
 (which is <i>not</i> part of the original manual page), send a mail to
 man-pages@man7.org
GNU grep 3.8-dirty 2019-12-29 GREP(1)
</pre>
<hr />
<p>Pages that refer to this page: 
 <a href="../man1/look.1.html">look(1)</a>,  
 <a href="../man1/pmrep.1.html">pmrep(1)</a>,  
 <a href="../man1/sed.1.html">sed(1)</a>,  
 <a href="../man3/regex.3.html">regex(3)</a>,  
 <a href="../man7/regex.7.html">regex(7)</a>,  
 <a href="../man8/bridge.8.html">bridge(8)</a>,  
 <a href="../man8/ip.8.html">ip(8)</a>,  
 <a href="../man8/tc.8.html">tc(8)</a>
</p>
<hr />
 
||||I|||| man7.org > Linux > man-pages Linux/UNIX system programming training
  
 

 grep(1) — Linux manual page

 NAME | SYNOPSIS | DESCRIPTION | OPTIONS | REGULAR EXPRESSIONS | EXIT STATUS | ENVIRONMENT | NOTES | COPYRIGHT | BUGS | EXAMPLE | SEE ALSO | COLOPHON
   
   
 
 
 GREP(1) User Commands GREP(1)
 

 NAME top

 
 grep - print lines that match patterns
 

 SYNOPSIS top

 
 grep [OPTION...] PATTERNS [FILE...]
 grep [OPTION...] -e PATTERNS ... [FILE...]
 grep [OPTION...] -f PATTERN_FILE ... [FILE...]
 

 DESCRIPTION top

 
 grep searches for PATTERNS in each FILE. PATTERNS is one or more
 patterns separated by newline characters, and grep prints each
 line that matches a pattern. Typically PATTERNS should be quoted
 when grep is used in a shell command.
 
 A FILE of â-â stands for standard input. If no FILE is given,
 recursive searches examine the working directory, and
 nonrecursive searches read standard input.
 

 OPTIONS top

 
 Generic Program Information
 --help Output a usage message and exit.
 
 -V, --version
 Output the version number of grep and exit.
 
 Pattern Syntax
 -E, --extended-regexp
 Interpret PATTERNS as extended regular expressions (EREs,
 see below).
 
 -F, --fixed-strings
 Interpret PATTERNS as fixed strings, not regular
 expressions.
 
 -G, --basic-regexp
 Interpret PATTERNS as basic regular expressions (BREs, see
 below). This is the default.
 
 -P, --perl-regexp
 Interpret PATTERNS as Perl-compatible regular expressions
 (PCREs). This option is experimental when combined with
 the -z (--null-data) option, and grep -P may warn of
 unimplemented features.
 
 Matching Control
 -e PATTERNS, --regexp=PATTERNS
 Use PATTERNS as the patterns. If this option is used
 multiple times or is combined with the -f (--file) option,
 search for all patterns given. This option can be used to
 protect a pattern beginning with â-â.
 
 -f FILE, --file=FILE
 Obtain patterns from FILE, one per line. If this option
 is used multiple times or is combined with the -e
 (--regexp) option, search for all patterns given. The
 empty file contains zero patterns, and therefore matches
 nothing.
 
 -i, --ignore-case
 Ignore case distinctions in patterns and input data, so
 that characters that differ only in case match each other.
 
 --no-ignore-case
 Do not ignore case distinctions in patterns and input
 data. This is the default. This option is useful for
 passing to shell scripts that already use -i, to cancel
 its effects because the two options override each other.
 
 -v, --invert-match
 Invert the sense of matching, to select non-matching
 lines.
 
 -w, --word-regexp
 Select only those lines containing matches that form whole
 words. The test is that the matching substring must
 either be at the beginning of the line, or preceded by a
 non-word constituent character. Similarly, it must be
 either at the end of the line or followed by a non-word
 constituent character. Word-constituent characters are
 letters, digits, and the underscore. This option has no
 effect if -x is also specified.
 
 -x, --line-regexp
 Select only those matches that exactly match the whole
 line. For a regular expression pattern, this is like
 parenthesizing the pattern and then surrounding it with ^
 and $.
 
 General Output Control
 -c, --count
 Suppress normal output; instead print a count of matching
 lines for each input file. With the -v, --invert-match
 option (see above), count non-matching lines.
 
 --color[=WHEN], --colour[=WHEN]
 Surround the matched (non-empty) strings, matching lines,
 context lines, file names, line numbers, byte offsets, and
 separators (for fields and groups of context lines) with
 escape sequences to display them in color on the terminal.
 The colors are defined by the environment variable
 GREP_COLORS. WHEN is never, always, or auto.
 
 -L, --files-without-match
 Suppress normal output; instead print the name of each
 input file from which no output would normally have been
 printed.
 
 -l, --files-with-matches
 Suppress normal output; instead print the name of each
 input file from which output would normally have been
 printed. Scanning each input file stops upon first match.
 
 -m NUM, --max-count=NUM
 Stop reading a file after NUM matching lines. If NUM is
 zero, grep stops right away without reading input. A NUM
 of -1 is treated as infinity and grep does not stop; this
 is the default. If the input is standard input from a
 regular file, and NUM matching lines are output, grep
 ensures that the standard input is positioned to just
 after the last matching line before exiting, regardless of
 the presence of trailing context lines. This enables a
 calling process to resume a search. When grep stops after
 NUM matching lines, it outputs any trailing context lines.
 When the -c or --count option is also used, grep does not
 output a count greater than NUM. When the -v or
 --invert-match option is also used, grep stops after
 outputting NUM non-matching lines.
 
 -o, --only-matching
 Print only the matched (non-empty) parts of a matching
 line, with each such part on a separate output line.
 
 -q, --quiet, --silent
 Quiet; do not write anything to standard output. Exit
 immediately with zero status if any match is found, even
 if an error was detected. Also see the -s or
 --no-messages option.
 
 -s, --no-messages
 Suppress error messages about nonexistent or unreadable
 files.
 
 Output Line Prefix Control
 -b, --byte-offset
 Print the 0-based byte offset within the input file before
 each line of output. If -o (--only-matching) is
 specified, print the offset of the matching part itself.
 
 -H, --with-filename
 Print the file name for each match. This is the default
 when there is more than one file to search. This is a GNU
 extension.
 
 -h, --no-filename
 Suppress the prefixing of file names on output. This is
 the default when there is only one file (or only standard
 input) to search.
 
 --label=LABEL
 Display input actually coming from standard input as input
 coming from file LABEL. This can be useful for commands
 that transform a file's contents before searching, e.g.,
 gzip -cd foo.gz | grep --label=foo -H 'some pattern'. See
 also the -H option.
 
 -n, --line-number
 Prefix each line of output with the 1-based line number
 within its input file.
 
 -T, --initial-tab
 Make sure that the first character of actual line content
 lies on a tab stop, so that the alignment of tabs looks
 normal. This is useful with options that prefix their
 output to the actual content: -H,-n, and -b. In order to
 improve the probability that lines from a single file will
 all start at the same column, this also causes the line
 number and byte offset (if present) to be printed in a
 minimum size field width.
 
 -Z, --null
 Output a zero byte (the ASCII NUL character) instead of
 the character that normally follows a file name. For
 example, grep -lZ outputs a zero byte after each file name
 instead of the usual newline. This option makes the
 output unambiguous, even in the presence of file names
 containing unusual characters like newlines. This option
 can be used with commands like find -print0, perl -0, sort
 -z, and xargs -0 to process arbitrary file names, even
 those that contain newline characters.
 
 Context Line Control
 -A NUM, --after-context=NUM
 Print NUM lines of trailing context after matching lines.
 Places a line containing a group separator (--) between
 contiguous groups of matches. With the -o or
 --only-matching option, this has no effect and a warning
 is given.
 
 -B NUM, --before-context=NUM
 Print NUM lines of leading context before matching lines.
 Places a line containing a group separator (--) between
 contiguous groups of matches. With the -o or
 --only-matching option, this has no effect and a warning
 is given.
 
 -C NUM, -NUM, --context=NUM
 Print NUM lines of output context. Places a line
 containing a group separator (--) between contiguous
 groups of matches. With the -o or --only-matching option,
 this has no effect and a warning is given.
 
 --group-separator=SEP
 When -A, -B, or -C are in use, print SEP instead of --
 between groups of lines.
 
 --no-group-separator
 When -A, -B, or -C are in use, do not print a separator
 between groups of lines.
 
 File and Directory Selection
 -a, --text
 Process a binary file as if it were text; this is
 equivalent to the --binary-files=text option.
 
 --binary-files=TYPE
 If a file's data or metadata indicate that the file
 contains binary data, assume that the file is of type
 TYPE. Non-text bytes indicate binary data; these are
 either output bytes that are improperly encoded for the
 current locale, or null input bytes when the -z option is
 not given.
 
 By default, TYPE is binary, and grep suppresses output
 after null input binary data is discovered, and suppresses
 output lines that contain improperly encoded data. When
 some output is suppressed, grep follows any output with a
 message to standard error saying that a binary file
 matches.
 
 If TYPE is without-match, when grep discovers null input
 binary data it assumes that the rest of the file does not
 match; this is equivalent to the -I option.
 
 If TYPE is text, grep processes a binary file as if it
 were text; this is equivalent to the -a option.
 
 When type is binary, grep may treat non-text bytes as line
 terminators even without the -z option. This means
 choosing binary versus text can affect whether a pattern
 matches a file. For example, when type is binary the
 pattern q$ might match q immediately followed by a null
 byte, even though this is not matched when type is text.
 Conversely, when type is binary the pattern . (period)
 might not match a null byte.
 
 Warning: The -a option might output binary garbage, which
 can have nasty side effects if the output is a terminal
 and if the terminal driver interprets some of it as
 commands. On the other hand, when reading files whose
 text encodings are unknown, it can be helpful to use -a or
 to set LC_ALL='C' in the environment, in order to find
 more matches even if the matches are unsafe for direct
 display.
 
 -D ACTION, --devices=ACTION
 If an input file is a device, FIFO or socket, use ACTION
 to process it. By default, ACTION is read, which means
 that devices are read just as if they were ordinary files.
 If ACTION is skip, devices are silently skipped.
 
 -d ACTION, --directories=ACTION
 If an input file is a directory, use ACTION to process it.
 By default, ACTION is read, i.e., read directories just as
 if they were ordinary files. If ACTION is skip, silently
 skip directories. If ACTION is recurse, read all files
 under each directory, recursively, following symbolic
 links only if they are on the command line. This is
 equivalent to the -r option.
 
 --exclude=GLOB
 Skip any command-line file with a name suffix that matches
 the pattern GLOB, using wildcard matching; a name suffix
 is either the whole name, or a trailing part that starts
 with a non-slash character immediately after a slash (/)
 in the name. When searching recursively, skip any subfile
 whose base name matches GLOB; the base name is the part
 after the last slash. A pattern can use *, ?, and [...]
 as wildcards, and \ to quote a wildcard or backslash
 character literally.
 
 --exclude-from=FILE
 Skip files whose base name matches any of the file-name
 globs read from FILE (using wildcard matching as described
 under --exclude).
 
 --exclude-dir=GLOB
 Skip any command-line directory with a name suffix that
 matches the pattern GLOB. When searching recursively,
 skip any subdirectory whose base name matches GLOB.
 Ignore any redundant trailing slashes in GLOB.
 
 -I Process a binary file as if it did not contain matching
 data; this is equivalent to the
 --binary-files=without-match option.
 
 --include=GLOB
 Search only files whose base name matches GLOB (using
 wildcard matching as described under --exclude). If
 contradictory --include and --exclude options are given,
 the last matching one wins. If no --include or --exclude
 options match, a file is included unless the first such
 option is --include.
 
 -r, --recursive
 Read all files under each directory, recursively,
 following symbolic links only if they are on the command
 line. Note that if no file operand is given, grep
 searches the working directory. This is equivalent to the
 -d recurse option.
 
 -R, --dereference-recursive
 Read all files under each directory, recursively. Follow
 all symbolic links, unlike -r.
 
 Other Options
 --line-buffered
 Use line buffering on output. This can cause a
 performance penalty.
 
 -U, --binary
 Treat the file(s) as binary. By default, under MS-DOS and
 MS-Windows, grep guesses whether a file is text or binary
 as described for the --binary-files option. If grep
 decides the file is a text file, it strips the CR
 characters from the original file contents (to make
 regular expressions with ^ and $ work correctly).
 Specifying -U overrules this guesswork, causing all files
 to be read and passed to the matching mechanism verbatim;
 if the file is a text file with CR/LF pairs at the end of
 each line, this will cause some regular expressions to
 fail. This option has no effect on platforms other than
 MS-DOS and MS-Windows.
 
 -z, --null-data
 Treat input and output data as sequences of lines, each
 terminated by a zero byte (the ASCII NUL character)
 instead of a newline. Like the -Z or --null option, this
 option can be used with commands like sort -z to process
 arbitrary file names.
 

 REGULAR EXPRESSIONS top

 
 A regular expression is a pattern that describes a set of
 strings. Regular expressions are constructed analogously to
 arithmetic expressions, by using various operators to combine
 smaller expressions.
 
 grep understands three different versions of regular expression
 syntax: âbasicâ (BRE), âextendedâ (ERE) and âperlâ (PCRE). In
 GNU grep there is no difference in available functionality
 between basic and extended syntax. In other implementations,
 basic regular expressions are less powerful. The following
 description applies to extended regular expressions; differences
 for basic regular expressions are summarized afterwards. Perl-
 compatible regular expressions give additional functionality, and
 are documented in pcre2syntax(3) and pcre2pattern(3), but work
 only if PCRE support is enabled.
 
 The fundamental building blocks are the regular expressions that
 match a single character. Most characters, including all letters
 and digits, are regular expressions that match themselves. Any
 meta-character with special meaning may be quoted by preceding it
 with a backslash.
 
 The period . matches any single character. It is unspecified
 whether it matches an encoding error.
 
 Character Classes and Bracket Expressions
 A bracket expression is a list of characters enclosed by [ and ].
 It matches any single character in that list. If the first
 character of the list is the caret ^ then it matches any
 character not in the list; it is unspecified whether it matches
 an encoding error. For example, the regular expression
 [0123456789] matches any single digit.
 
 Within a bracket expression, a range expression consists of two
 characters separated by a hyphen. It matches any single
 character that sorts between the two characters, inclusive, using
 the locale's collating sequence and character set. For example,
 in the default C locale, [a-d] is equivalent to [abcd]. Many
 locales sort characters in dictionary order, and in these locales
 [a-d] is typically not equivalent to [abcd]; it might be
 equivalent to [aBbCcDd], for example. To obtain the traditional
 interpretation of bracket expressions, you can use the C locale
 by setting the LC_ALL environment variable to the value C.
 
 Finally, certain named classes of characters are predefined
 within bracket expressions, as follows. Their names are self
 explanatory, and they are [:alnum:], [:alpha:], [:blank:],
 [:cntrl:], [:digit:], [:graph:], [:lower:], [:print:], [:punct:],
 [:space:], [:upper:], and [:xdigit:]. For example, [[:alnum:]]
 means the character class of numbers and letters in the current
 locale. In the C locale and ASCII character set encoding, this
 is the same as [0-9A-Za-z]. (Note that the brackets in these
 class names are part of the symbolic names, and must be included
 in addition to the brackets delimiting the bracket expression.)
 Most meta-characters lose their special meaning inside bracket
 expressions. To include a literal ] place it first in the list.
 Similarly, to include a literal ^ place it anywhere but first.
 Finally, to include a literal - place it last.
 
 Anchoring
 The caret ^ and the dollar sign $ are meta-characters that
 respectively match the empty string at the beginning and end of a
 line.
 
 The Backslash Character and Special Expressions
 The symbols \< and \> respectively match the empty string at the
 beginning and end of a word. The symbol \b matches the empty
 string at the edge of a word, and \B matches the empty string
 provided it's not at the edge of a word. The symbol \w is a
 synonym for [_[:alnum:]] and \W is a synonym for [^_[:alnum:]].
 
 Repetition
 A regular expression may be followed by one of several repetition
 operators:
 ? The preceding item is optional and matched at most once.
 * The preceding item will be matched zero or more times.
 + The preceding item will be matched one or more times.
 {n} The preceding item is matched exactly n times.
 {n,} The preceding item is matched n or more times.
 {,m} The preceding item is matched at most m times. This is a
 GNU extension.
 {n,m} The preceding item is matched at least n times, but not
 more than m times.
 
 Concatenation
 Two regular expressions may be concatenated; the resulting
 regular expression matches any string formed by concatenating two
 substrings that respectively match the concatenated expressions.
 
 Alternation
 Two regular expressions may be joined by the infix operator |;
 the resulting regular expression matches any string matching
 either alternate expression.
 
 Precedence
 Repetition takes precedence over concatenation, which in turn
 takes precedence over alternation. A whole expression may be
 enclosed in parentheses to override these precedence rules and
 form a subexpression.
 
 Back-references and Subexpressions
 The back-reference \n, where n is a single digit, matches the
 substring previously matched by the nth parenthesized
 subexpression of the regular expression.
 
 Basic vs Extended Regular Expressions
 In basic regular expressions the meta-characters ?, +, {, |, (,
 and ) lose their special meaning; instead use the backslashed
 versions \?, \+, \{, \|, \(, and \).
 

 EXIT STATUS top

 
 Normally the exit status is 0 if a line is selected, 1 if no
 lines were selected, and 2 if an error occurred. However, if the
 -q or --quiet or --silent is used and a line is selected, the
 exit status is 0 even if an error occurred.
 

 ENVIRONMENT top

 
 The behavior of grep is affected by the following environment
 variables.
 
 The locale for category LC_foo is specified by examining the
 three environment variables LC_ALL, LC_foo, LANG, in that order.
 The first of these variables that is set specifies the locale.
 For example, if LC_ALL is not set, but LC_MESSAGES is set to
 pt_BR, then the Brazilian Portuguese locale is used for the
 LC_MESSAGES category. The C locale is used if none of these
 environment variables are set, if the locale catalog is not
 installed, or if grep was not compiled with national language
 support (NLS). The shell command locale -a lists locales that
 are currently available.
 
 GREP_COLORS
 Controls how the --color option highlights output. Its
 value is a colon-separated list of capabilities that
 defaults to
 ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36 with the
 rv and ne boolean capabilities omitted (i.e., false).
 Supported capabilities are as follows.
 
 sl= SGR substring for whole selected lines (i.e.,
 matching lines when the -v command-line option is
 omitted, or non-matching lines when -v is
 specified). If however the boolean rv capability
 and the -v command-line option are both specified,
 it applies to context matching lines instead. The
 default is empty (i.e., the terminal's default
 color pair).
 
 cx= SGR substring for whole context lines (i.e., non-
 matching lines when the -v command-line option is
 omitted, or matching lines when -v is specified).
 If however the boolean rv capability and the -v
 command-line option are both specified, it applies
 to selected non-matching lines instead. The
 default is empty (i.e., the terminal's default
 color pair).
 
 rv Boolean value that reverses (swaps) the meanings of
 the sl= and cx= capabilities when the -v command-
 line option is specified. The default is false
 (i.e., the capability is omitted).
 
 mt=01;31
 SGR substring for matching non-empty text in any
 matching line (i.e., a selected line when the -v
 command-line option is omitted, or a context line
 when -v is specified). Setting this is equivalent
 to setting both ms= and mc= at once to the same
 value. The default is a bold red text foreground
 over the current line background.
 
 ms=01;31
 SGR substring for matching non-empty text in a
 selected line. (This is only used when the -v
 command-line option is omitted.) The effect of the
 sl= (or cx= if rv) capability remains active when
 this kicks in. The default is a bold red text
 foreground over the current line background.
 
 mc=01;31
 SGR substring for matching non-empty text in a
 context line. (This is only used when the -v
 command-line option is specified.) The effect of
 the cx= (or sl= if rv) capability remains active
 when this kicks in. The default is a bold red text
 foreground over the current line background.
 
 fn=35 SGR substring for file names prefixing any content
 line. The default is a magenta text foreground
 over the terminal's default background.
 
 ln=32 SGR substring for line numbers prefixing any
 content line. The default is a green text
 foreground over the terminal's default background.
 
 bn=32 SGR substring for byte offsets prefixing any
 content line. The default is a green text
 foreground over the terminal's default background.
 
 se=36 SGR substring for separators that are inserted
 between selected line fields (:), between context
 line fields, (-), and between groups of adjacent
 lines when nonzero context is specified (--). The
 default is a cyan text foreground over the
 terminal's default background.
 
 ne Boolean value that prevents clearing to the end of
 line using Erase in Line (EL) to Right (\33[K) each
 time a colorized item ends. This is needed on
 terminals on which EL is not supported. It is
 otherwise useful on terminals for which the
 back_color_erase (bce) boolean terminfo capability
 does not apply, when the chosen highlight colors do
 not affect the background, or when EL is too slow
 or causes too much flicker. The default is false
 (i.e., the capability is omitted).
 
 Note that boolean capabilities have no =... part. They
 are omitted (i.e., false) by default and become true when
 specified.
 
 See the Select Graphic Rendition (SGR) section in the
 documentation of the text terminal that is used for
 permitted values and their meaning as character
 attributes. These substring values are integers in
 decimal representation and can be concatenated with
 semicolons. grep takes care of assembling the result into
 a complete SGR sequence (\33[...m). Common values to
 concatenate include 1 for bold, 4 for underline, 5 for
 blink, 7 for inverse, 39 for default foreground color, 30
 to 37 for foreground colors, 90 to 97 for 16-color mode
 foreground colors, 38;5;0 to 38;5;255 for 88-color and
 256-color modes foreground colors, 49 for default
 background color, 40 to 47 for background colors, 100 to
 107 for 16-color mode background colors, and 48;5;0 to
 48;5;255 for 88-color and 256-color modes background
 colors.
 
 LC_ALL, LC_COLLATE, LANG
 These variables specify the locale for the LC_COLLATE
 category, which determines the collating sequence used to
 interpret range expressions like [a-z].
 
 LC_ALL, LC_CTYPE, LANG
 These variables specify the locale for the LC_CTYPE
 category, which determines the type of characters, e.g.,
 which characters are whitespace. This category also
 determines the character encoding, that is, whether text
 is encoded in UTF-8, ASCII, or some other encoding. In
 the C or POSIX locale, all characters are encoded as a
 single byte and every byte is a valid character.
 
 LC_ALL, LC_MESSAGES, LANG
 These variables specify the locale for the LC_MESSAGES
 category, which determines the language that grep uses for
 messages. The default C locale uses American English
 messages.
 
 POSIXLY_CORRECT
 If set, grep behaves as POSIX requires; otherwise, grep
 behaves more like other GNU programs. POSIX requires that
 options that follow file names must be treated as file
 names; by default, such options are permuted to the front
 of the operand list and are treated as options. Also,
 POSIX requires that unrecognized options be diagnosed as
 âillegalâ, but since they are not really against the law
 the default is to diagnose them as âinvalidâ.
 POSIXLY_CORRECT also disables
 _N_GNU_nonoption_argv_flags_, described below.
 
 _N_GNU_nonoption_argv_flags_
 (Here N is grep's numeric process ID.) If the ith
 character of this environment variable's value is 1, do
 not consider the ith operand of grep to be an option, even
 if it appears to be one. A shell can put this variable in
 the environment for each command it runs, specifying which
 operands are the results of file name wildcard expansion
 and therefore should not be treated as options. This
 behavior is available only with the GNU C library, and
 only when POSIXLY_CORRECT is not set.
 

 NOTES top

 
 This man page is maintained only fitfully; the full documentation
 is often more up-to-date.
 

 COPYRIGHT top

 
 Copyright 1998-2000, 2002, 2005-2022 Free Software Foundation,
 Inc.
 
 This is free software; see the source for copying conditions.
 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR
 A PARTICULAR PURPOSE.
 

 BUGS top

 
 Reporting Bugs
 Email bug reports to the bug-reporting address â¨bug-
 grep@gnu.orgâ©. An email archive 
 â¨https://lists.gnu.org/mailman/listinfo/bug-grepâ© and a bug
 tracker â¨https://debbugs.gnu.org/cgi/pkgreport.cgi?package=grepâ©
 are available.
 
 Known Bugs
 Large repetition counts in the {n,m} construct may cause grep to
 use lots of memory. In addition, certain other obscure regular
 expressions require exponential time and space, and may cause
 grep to run out of memory.
 
 Back-references are very slow, and may require exponential time.
 

 EXAMPLE top

 
 The following example outputs the location and contents of any
 line containing âfâ and ending in â.câ, within all files in the
 current directory whose names contain âgâ and end in â.hâ. The
 -n option outputs line numbers, the -- argument treats expansions
 of â*g*.hâ starting with â-â as file names not options, and the
 empty file /dev/null causes file names to be output even if only
 one file name happens to be of the form â*g*.hâ.
 
 $ grep -n -- 'f.*\.c$' *g*.h /dev/null
 argmatch.h:1:/* definitions and prototypes for argmatch.c
 
 The only line that matches is line 1 of argmatch.h. Note that
 the regular expression syntax used in the pattern differs from
 the globbing syntax that the shell uses to match file names.
 

 SEE ALSO top

 
 Regular Manual Pages
 awk(1), cmp(1), diff(1), find(1), perl(1), sed(1), sort(1),
 xargs(1), read(2), pcre2(3), pcre2syntax(3), pcre2pattern(3),
 terminfo(5), glob(7), regex(7)
 
 Full Documentation
 A complete manual â¨https://www.gnu.org/software/grep/manual/â© is
 available. If the info and grep programs are properly installed
 at your site, the command
 
 info grep
 
 should give you access to the complete manual.
 

 COLOPHON top

 
 This page is part of the GNU grep (regular expression file search
 tool) project. Information about the project can be found at 
 â¨https://www.gnu.org/software/grep/â©. If you have a bug report
 for this manual page, send it to bug-grep@gnu.org. This page was
 obtained from the project's upstream Git repository
 â¨git://git.savannah.gnu.org/grep.gitâ© on 2022-12-17. (At that
 time, the date of the most recent commit that was found in the
 repository was 2022-12-10.) If you discover any rendering
 problems in this HTML version of the page, or you believe there
 is a better or more up-to-date source for the page, or you have
 corrections or improvements to the information in this COLOPHON
 (which is not part of the original manual page), send a mail to
 man-pages@man7.org
 
 GNU grep 3.8-dirty 2019-12-29 GREP(1)
 

 Pages that refer to this page: look(1), pmrep(1), sed(1), regex(3), regex(7), bridge(8), ip(8), tc(8)

 HTML rendering created 2022-12-18 by Michael Kerrisk, author of The Linux Programming Interface, maintainer of the Linux man-pages project. 
   
 For details of in-depth Linux/UNIX system programming training courses that I teach, look here. 
   
 Hosting by jambit GmbH.  
   
 
GREP(1) User Commands GREP(1)
  NAME         top   grep - print lines that match patterns
  SYNOPSIS         top   grep [OPTION...] PATTERNS [FILE...]
 grep [OPTION...] -e  PATTERNS ... [FILE...]
 grep [OPTION...] -f  PATTERN_FILE ... [FILE...]
  DESCRIPTION         top   grep searches for PATTERNS in each FILE. PATTERNS is one or more
 patterns separated by newline characters, and grep prints each
 line that matches a pattern. Typically PATTERNS should be quoted
 when grep is used in a shell command.
 A FILE of â-â stands for standard input. If no FILE is given,
 recursive searches examine the working directory, and
 nonrecursive searches read standard input.
  OPTIONS         top   Generic Program Information
 --help Output a usage message and exit.
 -V, --version
 Output the version number of grep and exit.
 Pattern Syntax
 -E, --extended-regexp
 Interpret PATTERNS as extended regular expressions (EREs,
 see below).
 -F, --fixed-strings
 Interpret PATTERNS as fixed strings, not regular
 expressions.
 -G, --basic-regexp
 Interpret PATTERNS as basic regular expressions (BREs, see
 below). This is the default.
 -P, --perl-regexp
 Interpret PATTERNS as Perl-compatible regular expressions
 (PCREs). This option is experimental when combined with
 the -z (--null-data) option, and grep -P may warn of
 unimplemented features.
 Matching Control
 -e  PATTERNS, --regexp= PATTERNS
 Use PATTERNS as the patterns. If this option is used
 multiple times or is combined with the -f (--file) option,
 search for all patterns given. This option can be used to
 protect a pattern beginning with â-â.
 -f  FILE, --file= FILE
 Obtain patterns from FILE, one per line. If this option
 is used multiple times or is combined with the -e
 (--regexp) option, search for all patterns given. The
 empty file contains zero patterns, and therefore matches
 nothing.
 -i, --ignore-case
 Ignore case distinctions in patterns and input data, so
 that characters that differ only in case match each other.
 --no-ignore-case
 Do not ignore case distinctions in patterns and input
 data. This is the default. This option is useful for
 passing to shell scripts that already use -i, to cancel
 its effects because the two options override each other.
 -v, --invert-match
 Invert the sense of matching, to select non-matching
 lines.
 -w, --word-regexp
 Select only those lines containing matches that form whole
 words. The test is that the matching substring must
 either be at the beginning of the line, or preceded by a
 non-word constituent character. Similarly, it must be
 either at the end of the line or followed by a non-word
 constituent character. Word-constituent characters are
 letters, digits, and the underscore. This option has no
 effect if -x is also specified.
 -x, --line-regexp
 Select only those matches that exactly match the whole
 line. For a regular expression pattern, this is like
 parenthesizing the pattern and then surrounding it with ^
 and $.
 General Output Control
 -c, --count
 Suppress normal output; instead print a count of matching
 lines for each input file. With the -v, --invert-match
 option (see above), count non-matching lines.
 --color[= WHEN], --colour[= WHEN]
 Surround the matched (non-empty) strings, matching lines,
 context lines, file names, line numbers, byte offsets, and
 separators (for fields and groups of context lines) with
 escape sequences to display them in color on the terminal.
 The colors are defined by the environment variable
 GREP_COLORS. WHEN is never, always, or auto.
 -L, --files-without-match
 Suppress normal output; instead print the name of each
 input file from which no output would normally have been
 printed.
 -l, --files-with-matches
 Suppress normal output; instead print the name of each
 input file from which output would normally have been
 printed. Scanning each input file stops upon first match.
 -m  NUM, --max-count= NUM
 Stop reading a file after NUM matching lines. If NUM is
 zero, grep stops right away without reading input. A NUM
 of -1 is treated as infinity and grep does not stop; this
 is the default. If the input is standard input from a
 regular file, and NUM matching lines are output, grep
 ensures that the standard input is positioned to just
 after the last matching line before exiting, regardless of
 the presence of trailing context lines. This enables a
 calling process to resume a search. When grep stops after
 NUM matching lines, it outputs any trailing context lines.
 When the -c or --count option is also used, grep does not
 output a count greater than NUM. When the -v or
 --invert-match option is also used, grep stops after
 outputting NUM non-matching lines.
 -o, --only-matching
 Print only the matched (non-empty) parts of a matching
 line, with each such part on a separate output line.
 -q, --quiet, --silent
 Quiet; do not write anything to standard output. Exit
 immediately with zero status if any match is found, even
 if an error was detected. Also see the -s or
 --no-messages option.
 -s, --no-messages
 Suppress error messages about nonexistent or unreadable
 files.
 Output Line Prefix Control
 -b, --byte-offset
 Print the 0-based byte offset within the input file before
 each line of output. If -o (--only-matching) is
 specified, print the offset of the matching part itself.
 -H, --with-filename
 Print the file name for each match. This is the default
 when there is more than one file to search. This is a GNU
 extension.
 -h, --no-filename
 Suppress the prefixing of file names on output. This is
 the default when there is only one file (or only standard
 input) to search.
 --label= LABEL
 Display input actually coming from standard input as input
 coming from file LABEL. This can be useful for commands
 that transform a file's contents before searching, e.g.,
 gzip -cd foo.gz | grep --label=foo -H 'some pattern'. See
 also the -H option.
 -n, --line-number
 Prefix each line of output with the 1-based line number
 within its input file.
 -T, --initial-tab
 Make sure that the first character of actual line content
 lies on a tab stop, so that the alignment of tabs looks
 normal. This is useful with options that prefix their
 output to the actual content: -H,-n, and -b. In order to
 improve the probability that lines from a single file will
 all start at the same column, this also causes the line
 number and byte offset (if present) to be printed in a
 minimum size field width.
 -Z, --null
 Output a zero byte (the ASCII NUL character) instead of
 the character that normally follows a file name. For
 example, grep -lZ outputs a zero byte after each file name
 instead of the usual newline. This option makes the
 output unambiguous, even in the presence of file names
 containing unusual characters like newlines. This option
 can be used with commands like find -print0, perl -0, sort
 -z, and xargs -0 to process arbitrary file names, even
 those that contain newline characters.
 Context Line Control
 -A  NUM, --after-context= NUM
 Print NUM lines of trailing context after matching lines.
 Places a line containing a group separator (--) between
 contiguous groups of matches. With the -o or
 --only-matching option, this has no effect and a warning
 is given.
 -B  NUM, --before-context= NUM
 Print NUM lines of leading context before matching lines.
 Places a line containing a group separator (--) between
 contiguous groups of matches. With the -o or
 --only-matching option, this has no effect and a warning
 is given.
 -C  NUM, - NUM, --context= NUM
 Print NUM lines of output context. Places a line
 containing a group separator (--) between contiguous
 groups of matches. With the -o or --only-matching option,
 this has no effect and a warning is given.
 --group-separator= SEP
 When -A, -B, or -C are in use, print SEP instead of --
 between groups of lines.
 --no-group-separator
 When -A, -B, or -C are in use, do not print a separator
 between groups of lines.
 File and Directory Selection
 -a, --text
 Process a binary file as if it were text; this is
 equivalent to the --binary-files=text option.
 --binary-files= TYPE
 If a file's data or metadata indicate that the file
 contains binary data, assume that the file is of type
 TYPE. Non-text bytes indicate binary data; these are
 either output bytes that are improperly encoded for the
 current locale, or null input bytes when the -z option is
 not given.
 By default, TYPE is binary, and grep suppresses output
 after null input binary data is discovered, and suppresses
 output lines that contain improperly encoded data. When
 some output is suppressed, grep follows any output with a
 message to standard error saying that a binary file
 matches.
 If TYPE is without-match, when grep discovers null input
 binary data it assumes that the rest of the file does not
 match; this is equivalent to the -I option.
 If TYPE is text, grep processes a binary file as if it
 were text; this is equivalent to the -a option.
 When type is binary, grep may treat non-text bytes as line
 terminators even without the -z option. This means
 choosing binary versus text can affect whether a pattern
 matches a file. For example, when type is binary the
 pattern q$ might match q immediately followed by a null
 byte, even though this is not matched when type is text.
 Conversely, when type is binary the pattern . (period)
 might not match a null byte.
 Warning: The -a option might output binary garbage, which
 can have nasty side effects if the output is a terminal
 and if the terminal driver interprets some of it as
 commands. On the other hand, when reading files whose
 text encodings are unknown, it can be helpful to use -a or
 to set LC_ALL='C' in the environment, in order to find
 more matches even if the matches are unsafe for direct
 display.
 -D  ACTION, --devices= ACTION
 If an input file is a device, FIFO or socket, use ACTION
 to process it. By default, ACTION is read, which means
 that devices are read just as if they were ordinary files.
 If ACTION is skip, devices are silently skipped.
 -d  ACTION, --directories= ACTION
 If an input file is a directory, use ACTION to process it.
 By default, ACTION is read, i.e., read directories just as
 if they were ordinary files. If ACTION is skip, silently
 skip directories. If ACTION is recurse, read all files
 under each directory, recursively, following symbolic
 links only if they are on the command line. This is
 equivalent to the -r option.
 --exclude= GLOB
 Skip any command-line file with a name suffix that matches
 the pattern GLOB, using wildcard matching; a name suffix
 is either the whole name, or a trailing part that starts
 with a non-slash character immediately after a slash (/)
 in the name. When searching recursively, skip any subfile
 whose base name matches GLOB; the base name is the part
 after the last slash. A pattern can use *, ?, and [...]
 as wildcards, and \ to quote a wildcard or backslash
 character literally.
 --exclude-from= FILE
 Skip files whose base name matches any of the file-name
 globs read from FILE (using wildcard matching as described
 under --exclude).
 --exclude-dir= GLOB
 Skip any command-line directory with a name suffix that
 matches the pattern GLOB. When searching recursively,
 skip any subdirectory whose base name matches GLOB.
 Ignore any redundant trailing slashes in GLOB.
 -I Process a binary file as if it did not contain matching
 data; this is equivalent to the
 --binary-files=without-match option.
 --include= GLOB
 Search only files whose base name matches GLOB (using
 wildcard matching as described under --exclude). If
 contradictory --include and --exclude options are given,
 the last matching one wins. If no --include or --exclude
 options match, a file is included unless the first such
 option is --include.
 -r, --recursive
 Read all files under each directory, recursively,
 following symbolic links only if they are on the command
 line. Note that if no file operand is given, grep
 searches the working directory. This is equivalent to the
 -d recurse option.
 -R, --dereference-recursive
 Read all files under each directory, recursively. Follow
 all symbolic links, unlike -r.
 Other Options
 --line-buffered
 Use line buffering on output. This can cause a
 performance penalty.
 -U, --binary
 Treat the file(s) as binary. By default, under MS-DOS and
 MS-Windows, grep guesses whether a file is text or binary
 as described for the --binary-files option. If grep
 decides the file is a text file, it strips the CR
 characters from the original file contents (to make
 regular expressions with ^ and $ work correctly).
 Specifying -U overrules this guesswork, causing all files
 to be read and passed to the matching mechanism verbatim;
 if the file is a text file with CR/LF pairs at the end of
 each line, this will cause some regular expressions to
 fail. This option has no effect on platforms other than
 MS-DOS and MS-Windows.
 -z, --null-data
 Treat input and output data as sequences of lines, each
 terminated by a zero byte (the ASCII NUL character)
 instead of a newline. Like the -Z or --null option, this
 option can be used with commands like sort -z to process
 arbitrary file names.
  REGULAR EXPRESSIONS         top   A regular expression is a pattern that describes a set of
 strings. Regular expressions are constructed analogously to
 arithmetic expressions, by using various operators to combine
 smaller expressions.
 grep understands three different versions of regular expression
 syntax: âbasicâ (BRE), âextendedâ (ERE) and âperlâ (PCRE). In
 GNU grep there is no difference in available functionality
 between basic and extended syntax. In other implementations,
 basic regular expressions are less powerful. The following
 description applies to extended regular expressions; differences
 for basic regular expressions are summarized afterwards. Perl-
 compatible regular expressions give additional functionality, and
 are documented in pcre2syntax(3) and pcre2pattern(3), but work
 only if PCRE support is enabled.
 The fundamental building blocks are the regular expressions that
 match a single character. Most characters, including all letters
 and digits, are regular expressions that match themselves. Any
 meta-character with special meaning may be quoted by preceding it
 with a backslash.
 The period . matches any single character. It is unspecified
 whether it matches an encoding error.
 Character Classes and Bracket Expressions
 A bracket expression is a list of characters enclosed by [ and ].
 It matches any single character in that list. If the first
 character of the list is the caret ^ then it matches any
 character not in the list; it is unspecified whether it matches
 an encoding error. For example, the regular expression
 [0123456789] matches any single digit.
 Within a bracket expression, a range expression consists of two
 characters separated by a hyphen. It matches any single
 character that sorts between the two characters, inclusive, using
 the locale's collating sequence and character set. For example,
 in the default C locale, [a-d] is equivalent to [abcd]. Many
 locales sort characters in dictionary order, and in these locales
 [a-d] is typically not equivalent to [abcd]; it might be
 equivalent to [aBbCcDd], for example. To obtain the traditional
 interpretation of bracket expressions, you can use the C locale
 by setting the LC_ALL environment variable to the value C.
 Finally, certain named classes of characters are predefined
 within bracket expressions, as follows. Their names are self
 explanatory, and they are [:alnum:], [:alpha:], [:blank:],
 [:cntrl:], [:digit:], [:graph:], [:lower:], [:print:], [:punct:],
 [:space:], [:upper:], and [:xdigit:]. For example, [[:alnum:]]
 means the character class of numbers and letters in the current
 locale. In the C locale and ASCII character set encoding, this
 is the same as [0-9A-Za-z]. (Note that the brackets in these
 class names are part of the symbolic names, and must be included
 in addition to the brackets delimiting the bracket expression.)
 Most meta-characters lose their special meaning inside bracket
 expressions. To include a literal ] place it first in the list.
 Similarly, to include a literal ^ place it anywhere but first.
 Finally, to include a literal - place it last.
 Anchoring
 The caret ^ and the dollar sign $ are meta-characters that
 respectively match the empty string at the beginning and end of a
 line.
 The Backslash Character and Special Expressions
 The symbols \&lt; and \&gt; respectively match the empty string at the
 beginning and end of a word. The symbol \b matches the empty
 string at the edge of a word, and \B matches the empty string
 provided it's not at the edge of a word. The symbol \w is a
 synonym for [_[:alnum:]] and \W is a synonym for [^_[:alnum:]].
 Repetition
 A regular expression may be followed by one of several repetition
 operators:
 ? The preceding item is optional and matched at most once.
 * The preceding item will be matched zero or more times.
 + The preceding item will be matched one or more times.
 { n } The preceding item is matched exactly n times.
 { n ,} The preceding item is matched n or more times.
 {, m } The preceding item is matched at most m times. This is a
 GNU extension.
 { n , m } The preceding item is matched at least n times, but not
 more than m times.
 Concatenation
 Two regular expressions may be concatenated; the resulting
 regular expression matches any string formed by concatenating two
 substrings that respectively match the concatenated expressions.
 Alternation
 Two regular expressions may be joined by the infix operator |;
 the resulting regular expression matches any string matching
 either alternate expression.
 Precedence
 Repetition takes precedence over concatenation, which in turn
 takes precedence over alternation. A whole expression may be
 enclosed in parentheses to override these precedence rules and
 form a subexpression.
 Back-references and Subexpressions
 The back-reference \ n, where n is a single digit, matches the
 substring previously matched by the nth parenthesized
 subexpression of the regular expression.
 Basic vs Extended Regular Expressions
 In basic regular expressions the meta-characters ?, +, {, |, (,
 and ) lose their special meaning; instead use the backslashed
 versions \?, \+, \{, \|, \(, and \).
  EXIT STATUS         top   Normally the exit status is 0 if a line is selected, 1 if no
 lines were selected, and 2 if an error occurred. However, if the
 -q or --quiet or --silent is used and a line is selected, the
 exit status is 0 even if an error occurred.
  ENVIRONMENT         top   The behavior of grep is affected by the following environment
 variables.
 The locale for category LC_ foo is specified by examining the
 three environment variables LC_ALL, LC_ foo, LANG, in that order.
 The first of these variables that is set specifies the locale.
 For example, if LC_ALL is not set, but LC_MESSAGES is set to
 pt_BR, then the Brazilian Portuguese locale is used for the
 LC_MESSAGES category. The C locale is used if none of these
 environment variables are set, if the locale catalog is not
 installed, or if grep was not compiled with national language
 support (NLS). The shell command locale -a lists locales that
 are currently available.
 GREP_COLORS
 Controls how the --color option highlights output. Its
 value is a colon-separated list of capabilities that
 defaults to
 ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36 with the
 rv and ne boolean capabilities omitted (i.e., false).
 Supported capabilities are as follows.
 sl= SGR substring for whole selected lines (i.e.,
 matching lines when the -v command-line option is
 omitted, or non-matching lines when -v is
 specified). If however the boolean rv capability
 and the -v command-line option are both specified,
 it applies to context matching lines instead. The
 default is empty (i.e., the terminal's default
 color pair).
 cx= SGR substring for whole context lines (i.e., non-
 matching lines when the -v command-line option is
 omitted, or matching lines when -v is specified).
 If however the boolean rv capability and the -v
 command-line option are both specified, it applies
 to selected non-matching lines instead. The
 default is empty (i.e., the terminal's default
 color pair).
 rv Boolean value that reverses (swaps) the meanings of
 the sl= and cx= capabilities when the -v command-
 line option is specified. The default is false
 (i.e., the capability is omitted).
 mt=01;31
 SGR substring for matching non-empty text in any
 matching line (i.e., a selected line when the -v
 command-line option is omitted, or a context line
 when -v is specified). Setting this is equivalent
 to setting both ms= and mc= at once to the same
 value. The default is a bold red text foreground
 over the current line background.
 ms=01;31
 SGR substring for matching non-empty text in a
 selected line. (This is only used when the -v
 command-line option is omitted.) The effect of the
 sl= (or cx= if rv) capability remains active when
 this kicks in. The default is a bold red text
 foreground over the current line background.
 mc=01;31
 SGR substring for matching non-empty text in a
 context line. (This is only used when the -v
 command-line option is specified.) The effect of
 the cx= (or sl= if rv) capability remains active
 when this kicks in. The default is a bold red text
 foreground over the current line background.
 fn=35 SGR substring for file names prefixing any content
 line. The default is a magenta text foreground
 over the terminal's default background.
 ln=32 SGR substring for line numbers prefixing any
 content line. The default is a green text
 foreground over the terminal's default background.
 bn=32 SGR substring for byte offsets prefixing any
 content line. The default is a green text
 foreground over the terminal's default background.
 se=36 SGR substring for separators that are inserted
 between selected line fields (:), between context
 line fields, (-), and between groups of adjacent
 lines when nonzero context is specified (--). The
 default is a cyan text foreground over the
 terminal's default background.
 ne Boolean value that prevents clearing to the end of
 line using Erase in Line (EL) to Right (\33[K) each
 time a colorized item ends. This is needed on
 terminals on which EL is not supported. It is
 otherwise useful on terminals for which the
 back_color_erase (bce) boolean terminfo capability
 does not apply, when the chosen highlight colors do
 not affect the background, or when EL is too slow
 or causes too much flicker. The default is false
 (i.e., the capability is omitted).
 Note that boolean capabilities have no =... part. They
 are omitted (i.e., false) by default and become true when
 specified.
 See the Select Graphic Rendition (SGR) section in the
 documentation of the text terminal that is used for
 permitted values and their meaning as character
 attributes. These substring values are integers in
 decimal representation and can be concatenated with
 semicolons. grep takes care of assembling the result into
 a complete SGR sequence (\33[...m). Common values to
 concatenate include 1 for bold, 4 for underline, 5 for
 blink, 7 for inverse, 39 for default foreground color, 30
 to 37 for foreground colors, 90 to 97 for 16-color mode
 foreground colors, 38;5;0 to 38;5;255 for 88-color and
 256-color modes foreground colors, 49 for default
 background color, 40 to 47 for background colors, 100 to
 107 for 16-color mode background colors, and 48;5;0 to
 48;5;255 for 88-color and 256-color modes background
 colors.
 LC_ALL, LC_COLLATE, LANG
 These variables specify the locale for the LC_COLLATE
 category, which determines the collating sequence used to
 interpret range expressions like [a-z].
 LC_ALL, LC_CTYPE, LANG
 These variables specify the locale for the LC_CTYPE
 category, which determines the type of characters, e.g.,
 which characters are whitespace. This category also
 determines the character encoding, that is, whether text
 is encoded in UTF-8, ASCII, or some other encoding. In
 the C or POSIX locale, all characters are encoded as a
 single byte and every byte is a valid character.
 LC_ALL, LC_MESSAGES, LANG
 These variables specify the locale for the LC_MESSAGES
 category, which determines the language that grep uses for
 messages. The default C locale uses American English
 messages.
 POSIXLY_CORRECT
 If set, grep behaves as POSIX requires; otherwise, grep
 behaves more like other GNU programs. POSIX requires that
 options that follow file names must be treated as file
 names; by default, such options are permuted to the front
 of the operand list and are treated as options. Also,
 POSIX requires that unrecognized options be diagnosed as
 âillegalâ, but since they are not really against the law
 the default is to diagnose them as âinvalidâ.
 POSIXLY_CORRECT also disables
 _ N _GNU_nonoption_argv_flags_, described below.
 _ N _GNU_nonoption_argv_flags_
 (Here N is grep's numeric process ID.) If the ith
 character of this environment variable's value is 1, do
 not consider the ith operand of grep to be an option, even
 if it appears to be one. A shell can put this variable in
 the environment for each command it runs, specifying which
 operands are the results of file name wildcard expansion
 and therefore should not be treated as options. This
 behavior is available only with the GNU C library, and
 only when POSIXLY_CORRECT is not set.
  NOTES         top   This man page is maintained only fitfully; the full documentation
 is often more up-to-date.
  COPYRIGHT         top   Copyright 1998-2000, 2002, 2005-2022 Free Software Foundation,
 Inc.
 This is free software; see the source for copying conditions.
 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR
 A PARTICULAR PURPOSE.
  BUGS         top   Reporting Bugs
 Email bug reports to the bug-reporting address â¨bug-
 grep@gnu.orgâ©. An email archive 
 â¨https://lists.gnu.org/mailman/listinfo/bug-grepâ© and a bug
 tracker â¨https://debbugs.gnu.org/cgi/pkgreport.cgi?package=grepâ©
 are available.
 Known Bugs
 Large repetition counts in the { n , m } construct may cause grep to
 use lots of memory. In addition, certain other obscure regular
 expressions require exponential time and space, and may cause
 grep to run out of memory.
 Back-references are very slow, and may require exponential time.
  EXAMPLE         top   The following example outputs the location and contents of any
 line containing âfâ and ending in â.câ, within all files in the
 current directory whose names contain âgâ and end in â.hâ. The
 -n option outputs line numbers, the -- argument treats expansions
 of â*g*.hâ starting with â-â as file names not options, and the
 empty file /dev/null causes file names to be output even if only
 one file name happens to be of the form â*g*.hâ.
 $ grep -n -- 'f.*\.c$' *g*.h /dev/null
 argmatch.h:1:/* definitions and prototypes for argmatch.c
 The only line that matches is line 1 of argmatch.h. Note that
 the regular expression syntax used in the pattern differs from
 the globbing syntax that the shell uses to match file names.
  SEE ALSO         top   Regular Manual Pages
 awk(1), cmp(1), diff(1), find(1), perl(1), sed(1), sort(1),
 xargs(1), read(2), pcre2(3), pcre2syntax(3), pcre2pattern(3),
 terminfo(5), glob(7), regex(7)
 Full Documentation
 A complete manual â¨https://www.gnu.org/software/grep/manual/â© is
 available. If the info and grep programs are properly installed
 at your site, the command
 info grep
 should give you access to the complete manual.
  COLOPHON         top   This page is part of the GNU grep (regular expression file search
 tool) project. Information about the project can be found at 
 â¨https://www.gnu.org/software/grep/â©. If you have a bug report
 for this manual page, send it to bug-grep@gnu.org. This page was
 obtained from the project's upstream Git repository
 â¨git://git.savannah.gnu.org/grep.gitâ© on 2022-12-17. (At that
 time, the date of the most recent commit that was found in the
 repository was 2022-12-10.) If you discover any rendering
 problems in this HTML version of the page, or you believe there
 is a better or more up-to-date source for the page, or you have
 corrections or improvements to the information in this COLOPHON
 (which is not part of the original manual page), send a mail to
 man-pages@man7.org
GNU grep 3.8-dirty 2019-12-29 GREP(1)
Pages that refer to this page: 
 look(1),  
 pmrep(1),  
 sed(1),  
 regex(3),  
 regex(7),  
 bridge(8),  
 ip(8),  
 tc(8)
grep(1) — Linux manual page
https://man7.org/linux/man-pages/man1/grep.1.html
https://en.wikipedia.org/wiki/Grep
grep - Wikipedia
2002-03-29
Authority control National libraries Germany
<div><div>
	<p>From Wikipedia, the free encyclopedia</p>
	</div><div>
<table><caption>grep</caption><tbody><tr><td><a href="/wiki/File:Grep_example.png"></a><p>Example of <code>grep</code> command</p></td></tr><tr><th><a href="/wiki/Programmer">Original author(s)</a></th><td><a href="/wiki/Ken_Thompson">Ken Thompson</a><sup><a href="#cite_note-history102-1">[1]</a></sup><sup><a href="#cite_note-2">[2]</a></sup></td></tr><tr><th><a href="/wiki/Programmer">Developer(s)</a></th><td><a href="/wiki/AT%26T_Bell_Laboratories">AT&amp;T Bell Laboratories</a></td></tr><tr><th>Initial release</th><td>November 1973; 49 years ago<sup><a href="#cite_note-history102-1">[1]</a></sup></td></tr><tr><th>Written in</th><td><a href="/wiki/C_(programming_language)">C</a></td></tr><tr><th><a href="/wiki/Operating_system">Operating system</a></th><td><a href="/wiki/Unix">Unix</a>, <a href="/wiki/Unix-like">Unix-like</a>, <a href="/wiki/Plan_9_from_Bell_Labs">Plan 9</a>, <a href="/wiki/Inferno_(operating_system)">Inferno</a>, <a href="/wiki/OS-9">OS-9</a>, <a href="/wiki/MSX-DOS">MSX-DOS</a>, <a href="/wiki/IBM_i">IBM i</a></td></tr><tr><th><a href="/wiki/Computing_platform">Platform</a></th><td><a href="/wiki/Cross-platform">Cross-platform</a></td></tr><tr><th><a href="/wiki/Software_categories#Categorization_approaches">Type</a></th><td><a href="/wiki/Command_(computing)">Command</a></td></tr></tbody></table>
<p><b><code>grep</code></b> is a <a href="/wiki/Command_line_interface">command-line</a> utility for searching plain-text data sets for lines that match a <a href="/wiki/Regular_expression">regular expression</a>. Its name comes from the <a href="/wiki/Ed_(text_editor)">ed</a> command <i>g/re/p</i> (<i>globally search for a regular expression and print matching lines</i>), which has the same effect.<sup><a href="#cite_note-3">[3]</a></sup><sup><a href="#cite_note-etymology-4">[4]</a></sup> <code>grep</code> was originally developed for the <a href="/wiki/Unix">Unix</a> operating system, but later available for all <a href="/wiki/Unix-like">Unix-like</a> systems and some others such as <a href="/wiki/OS-9">OS-9</a>.<sup><a href="#cite_note-5">[5]</a></sup>
</p>
<h2>History[<a href="/w/index.php?title=Grep&amp;action=edit&amp;section=1">edit</a>]</h2>
<p>Before it was named, grep was a private utility written by <a href="/wiki/Ken_Thompson">Ken Thompson</a> to search files for certain patterns. <a href="/wiki/Doug_McIlroy">Doug McIlroy</a>, unaware of its existence, asked Thompson to write such a program. Responding that he would think about such a utility overnight, Thompson actually corrected bugs and made improvements for about an hour on his own program called <code>s</code> (short for "search"). The next day he presented the program to McIlroy, who said it was exactly what he wanted. Thompson's account may explain the belief that grep was written overnight.<sup><a href="#cite_note-6">[6]</a></sup>
</p><p>Thompson wrote the first version in <a href="/wiki/PDP-11">PDP-11</a> <a href="/wiki/Assembly_language">assembly language</a> to help <a href="/wiki/Lee_E._McMahon">Lee E. McMahon</a> analyze the text of <i><a href="/wiki/The_Federalist_Papers">The Federalist Papers</a></i> to determine authorship of the individual papers.<sup><a href="#cite_note-7">[7]</a></sup> The <a href="/wiki/Ed_(text_editor)">ed text editor</a> (also authored by Thompson) had <a href="/wiki/Regular_expression">regular expression</a> support but could not be used on such a large amount of text, so Thompson excerpted that code into a standalone tool.<sup><a href="#cite_note-history102-1">[1]</a></sup> He chose the name because in ed, the command <i>g/re/p</i> would print all lines matching a specified pattern.<sup><a href="#cite_note-8">[8]</a></sup><sup><a href="#cite_note-9">[9]</a></sup> <code>grep</code> was first included in <a href="/wiki/Version_4_Unix">Version 4 Unix</a>. Stating that it is "generally cited as <i>the</i> prototypical software tool", McIlroy credited <code>grep</code> with "irrevocably ingraining" Thompson's <a href="/wiki/Tools_philosophy">tools philosophy</a> in Unix.<sup><a href="#cite_note-reader-10">[10]</a></sup>
</p>
<h2>Implementations[<a href="/w/index.php?title=Grep&amp;action=edit&amp;section=2">edit</a>]</h2>
<p>A variety of <code>grep</code> implementations are available in many operating systems and software development environments.<sup><a href="#cite_note-11">[11]</a></sup> Early variants included <code>egrep</code> and <code>fgrep</code>, introduced in <a href="/wiki/Version_7_Unix">Version 7 Unix</a>.<sup><a href="#cite_note-reader-10">[10]</a></sup> The "<code>egrep</code>" variant supports an <a href="/wiki/Regular_expression#POSIX_basic_and_extended">extended regular expression</a> syntax added by <a href="/wiki/Alfred_Aho">Alfred Aho</a> after <a href="/wiki/Ken_Thompson">Ken Thompson</a>'s original regular expression implementation.<sup><a href="#cite_note-Huma1988-12">[12]</a></sup> The "<code>fgrep</code>" variant searches for any of a list of <i>fixed</i> strings using the <a href="/wiki/Aho%E2%80%93Corasick_string_matching_algorithm">Aho–Corasick string matching algorithm</a>.<sup><a href="#cite_note-Meurant1990-13">[13]</a></sup> Binaries of these variants exist in modern systems, usually linking to <code>grep</code> or calling grep as a shell script with the appropriate flag added, e.g. <code>exec grep -E "$@"</code>. <code>egrep</code> and <code>fgrep</code>, while commonly deployed on POSIX systems, to the point the POSIX specification mentions their widespread existence, are actually not part of POSIX.<sup><a href="#cite_note-14">[14]</a></sup>
</p><p>Other commands contain the word "grep" to indicate they are search tools, typically ones that rely on regular expression matches. The <a href="/wiki/Pgrep"><code>pgrep</code></a> utility, for instance, displays the processes whose names match a given regular expression.<sup><a href="#cite_note-15">[15]</a></sup>
</p><p>In the <a href="/wiki/Perl">Perl</a> programming language, <i>grep</i> is the name of the built-in function that finds elements in a list that satisfy a certain property.<sup><a href="#cite_note-16">[16]</a></sup> This <a href="/wiki/Higher-order_function">higher-order function</a> is typically named <code><a href="/wiki/Filter_(higher-order_function)">filter</a></code> or <code>where</code> in other languages.
</p><p>The <code>pcregrep</code> command is an implementation of <code>grep</code> that uses <a href="/wiki/Regular_expression#Perl_and_PCRE">Perl regular expression</a> syntax.<sup><a href="#cite_note-17">[17]</a></sup> Similar functionality can be invoked in the GNU version of <code>grep</code> with the <code>-P</code> flag.<sup><a href="#cite_note-18">[18]</a></sup>
</p><p><a href="/wiki/Porting">Ports</a> of <code>grep</code> (within <a href="/wiki/Cygwin">Cygwin</a> and <a href="/wiki/GnuWin32">GnuWin32</a>, for example) also run under <a href="/wiki/Microsoft_Windows">Microsoft Windows</a>. Some versions of Windows feature the similar <code>qgrep</code> or <code><a href="/wiki/Findstr">findstr</a></code> command.<sup><a href="#cite_note-19">[19]</a></sup>
</p><p>A <code>grep</code> command is also part of <a href="/wiki/ASCII_Corporation">ASCII</a>'s <i>MSX-DOS2 Tools</i> for <a href="/wiki/MSX-DOS">MSX-DOS</a> version 2.<sup><a href="#cite_note-20">[20]</a></sup>
</p><p>The grep, egrep, and fgrep commands have also been ported to the <a href="/wiki/IBM_i">IBM i</a> operating system.<sup><a href="#cite_note-21">[21]</a></sup>
</p><p>The software <a href="/wiki/Adobe_InDesign">Adobe InDesign</a> has functions GREP (since CS3 version (2007)<sup><a href="#cite_note-22">[22]</a></sup>), in the <i>find/change</i> dialog box<sup><a href="#cite_note-23">[23]</a></sup> "GREP" tab, and introduced with InDesign CS4<sup><a href="#cite_note-24">[24]</a></sup> in <i>paragraph styles</i><sup><a href="#cite_note-25">[25]</a></sup> "GREP styles".
</p>
<h3>agrep[<a href="/w/index.php?title=Grep&amp;action=edit&amp;section=3">edit</a>]</h3>
<p><b><i>a</i>grep</b> (approximate grep) matches even when the text only <i>approximately</i> fits the search pattern.<sup><a href="#cite_note-eGrep.SunX-26">[26]</a></sup>
</p><p>This following invocation finds <i>netmasks</i> in file <i>myfile</i>, but also any other word that can be derived from it, given no more than two substitutions.
</p>
<pre>agrep -2 netmasks myfile
</pre>
<p>This example generates a list of matches with the closest, that is those with the fewest, substitutions listed first. The command flag <i>B</i> means <i>best</i>:
</p>
<pre>agrep -B netmasks myfile
</pre>
<h2>Usage as a verb[<a href="/w/index.php?title=Grep&amp;action=edit&amp;section=4">edit</a>]</h2>
<p>In December 2003, the <i><a href="/wiki/Oxford_English_Dictionary">Oxford English Dictionary</a> Online</i> added "grep" as both a noun and a verb.<sup><a href="#cite_note-27">[27]</a></sup>
</p><p>A common verb usage is the phrase "You can't grep dead trees"—meaning one can more easily search through digital media, using tools such as <code>grep</code>, than one could with a hard copy (i.e. one made from "dead trees", which in this context is a <a href="/wiki/Dysphemism">dysphemism</a> for paper).<sup><a href="#cite_note-28">[28]</a></sup>
</p>
<h2>See also[<a href="/w/index.php?title=Grep&amp;action=edit&amp;section=5">edit</a>]</h2>
<ul><li><a href="/wiki/Boyer%E2%80%93Moore_string-search_algorithm">Boyer–Moore string-search algorithm</a></li>
<li><a href="/wiki/Agrep">agrep</a>, an approximate string-matching command</li>
<li><a href="/wiki/Find_(Windows)">find (Windows)</a> or <a href="/wiki/Findstr">Findstr</a>, a DOS and Windows command that performs text searches, similar to a simple <code>grep</code></li>
<li><a href="/wiki/Find_(Unix)">find (Unix)</a>, a Unix command that finds files by attribute, very different from <code>grep</code></li>
<li><a href="/wiki/List_of_Unix_commands">List of Unix commands</a></li>
<li><a href="/wiki/Visual_inspection#Humorous_terminology">vgrep</a>, or "visual <code>grep</code>"</li>
<li><a href="/wiki/Ngrep">ngrep</a>, the network grep</li></ul>
<h2>References[<a href="/w/index.php?title=Grep&amp;action=edit&amp;section=6">edit</a>]</h2>
<div>
<ol>
<li>^ <a href="#cite_ref-history102_1-0"><sup><i><b>a</b></i></sup></a> <a href="#cite_ref-history102_1-1"><sup><i><b>b</b></i></sup></a> <a href="#cite_ref-history102_1-2"><sup><i><b>c</b></i></sup></a> <cite>Kernighan, Brian (1984). <a href="https://archive.org/details/unixprogramminge0000kern/page/102"><i>The Unix Programming Environment</i></a>. Prentice Hall. pp. <a href="https://archive.org/details/unixprogramminge0000kern/page/102">102</a>. <a href="/wiki/ISBN_(identifier)">ISBN</a> <a href="/wiki/Special:BookSources/0-13-937681-X"><bdi>0-13-937681-X</bdi></a>.</cite>
</li>
<li><b><a href="#cite_ref-2">^</a></b> <a href="https://medium.com/@rualthanzauva/grep-was-a-private-command-of-mine-for-quite-a-while-before-i-made-it-public-ken-thompson-a40e24a5ef48">“grep was a private command of mine for quite a while before i made it public.” -Ken Thompson</a> <a href="https://web.archive.org/web/20150526111054/https://medium.com/@rualthanzauva/grep-was-a-private-command-of-mine-for-quite-a-while-before-i-made-it-public-ken-thompson-a40e24a5ef48">Archived</a> 2015-05-26 at the <a href="/wiki/Wayback_Machine">Wayback Machine</a>, By Benjamin Rualthanzauva, Published on Feb 5, 2014, Medium
</li>
<li><b><a href="#cite_ref-3">^</a></b> Hauben et al. 1997, Ch. 9
</li>
<li><b><a href="#cite_ref-etymology_4-0">^</a></b> <cite><a href="/wiki/Eric_S._Raymond">Raymond, Eric</a>. <a href="https://web.archive.org/web/20060617052845/http://www.catb.org/~esr/jargon/html/G/grep.html">"grep"</a>. <i>Jargon File</i>. Archived from <a href="http://www.catb.org/~esr/jargon/html/G/grep.html">the original</a> on 2006-06-17. Retrieved 2006-06-29.</cite>
</li>
<li><b><a href="#cite_ref-5">^</a></b> <cite>Paul S. Dayan (1992). <i>The OS-9 Guru - 1 : The Facts</i>. Galactic Industrial Limited. <a href="/wiki/ISBN_(identifier)">ISBN</a> <a href="/wiki/Special:BookSources/0-9519228-0-7"><bdi>0-9519228-0-7</bdi></a>.</cite>
</li>
<li><b><a href="#cite_ref-6">^</a></b> <cite><a href="https://www.youtube.com/watch?v=EY6q5dv_B-o"><i>VCF East 2019 -- Brian Kernighan interviews Ken Thompson</i></a> (video). YouTube. 6 May 2019. <a href="https://ghostarchive.org/varchive/youtube/20211211/EY6q5dv_B-o">Archived</a> from the original on 2021-12-11.</cite> (35 mins)
</li>
<li><b><a href="#cite_ref-7">^</a></b> Computerphile, <i><a href="https://www.youtube.com/watch?v=NTfOnGZUZDk">Where GREP Came From</a></i>, interview with <a href="/wiki/Brian_Kernighan">Brian Kernighan</a>
</li>
<li><b><a href="#cite_ref-8">^</a></b> <cite><a href="https://web.archive.org/web/20171020031534/https://perl.plover.com/classes/HoldSpace/samples/slide012.html">"ed regexes"</a>. <i>perl.plover.com</i>. Archived from <a href="http://perl.plover.com/classes/HoldSpace/samples/slide012.html">the original</a> on 20 October 2017. Retrieved 24 April 2018.</cite>
</li>
<li><b><a href="#cite_ref-9">^</a></b> <cite><a href="https://web.archive.org/web/20170809155158/https://robots.thoughtbot.com/how-grep-got-its-name">"How Grep Got its Name"</a>. <i>robots.thoughtbot.com</i>. Archived from <a href="http://robots.thoughtbot.com/how-grep-got-its-name">the original</a> on 9 August 2017. Retrieved 24 April 2018.</cite>
</li>
<li>^ <a href="#cite_ref-reader_10-0"><sup><i><b>a</b></i></sup></a> <a href="#cite_ref-reader_10-1"><sup><i><b>b</b></i></sup></a> <cite><a href="/wiki/Doug_McIlroy">McIlroy, M. D.</a> (1987). <a href="http://www.cs.dartmouth.edu/~doug/reader.pdf"><i>A Research Unix reader: annotated excerpts from the Programmer's Manual, 1971–1986</i></a> (PDF) (Technical report). CSTR. Bell Labs. 139. <a href="https://web.archive.org/web/20171111151817/http://www.cs.dartmouth.edu/~doug/reader.pdf">Archived</a> (PDF) from the original on 2017-11-11.</cite>
</li>
<li><b><a href="#cite_ref-11">^</a></b> <cite>Abou-Assaleh, Tony; Wei Ai (March 2004). <i>Survey of Global Regular Expression Print (GREP) Tools</i> (Technical report). Dalhousie University.</cite>
</li>
<li><b><a href="#cite_ref-Huma1988_12-0">^</a></b> <cite>Hume, Andrew (1988). "A Tale of Two Greps". <i>Software: Practice and Experience</i>. <b>18</b> (11): 1063. <a href="/wiki/Doi_(identifier)">doi</a>:<a href="https://doi.org/10.1002%2Fspe.4380181105">10.1002/spe.4380181105</a>. <a href="/wiki/S2CID_(identifier)">S2CID</a> <a href="https://api.semanticscholar.org/CorpusID:6395770">6395770</a>.</cite>
</li>
<li><b><a href="#cite_ref-Meurant1990_13-0">^</a></b> <cite>Meurant, Gerard (12 Sep 1990). <a href="https://books.google.com/books?id=6WriBQAAQBAJ"><i>Algorithms and Complexity</i></a>. Elsevier Science. p. 278. <a href="/wiki/ISBN_(identifier)">ISBN</a> <a href="/wiki/Special:BookSources/9780080933917"><bdi>9780080933917</bdi></a>. <a href="https://web.archive.org/web/20160304084311/https://books.google.com/books?id=6WriBQAAQBAJ&amp;printsec=frontcover&amp;source=gbs_ge_summary_r&amp;cad=0#v=onepage&amp;q&amp;f=false">Archived</a> from the original on 4 March 2016. Retrieved 12 December 2015.</cite>
</li>
<li><b><a href="#cite_ref-14">^</a></b> <cite><a href="http://pubs.opengroup.org/onlinepubs/009695399/utilities/grep.html">"grep"</a>. <i>www.pubs.opengroup.org</i>. The Open Group. <a href="https://web.archive.org/web/20151128184349/http://pubs.opengroup.org/onlinepubs/009695399/utilities/grep.html">Archived</a> from the original on 28 November 2015. Retrieved 12 December 2015.</cite>
</li>
<li><b><a href="#cite_ref-15">^</a></b> <cite><a href="http://linux.die.net/man/1/pgrep">"pgrep(1)"</a>. <i>www.linux.die.net</i>. <a href="https://web.archive.org/web/20151222084135/http://linux.die.net/man/1/pgrep">Archived</a> from the original on 22 December 2015. Retrieved 12 December 2015.</cite>
</li>
<li><b><a href="#cite_ref-16">^</a></b> <cite><a href="http://perldoc.perl.org/functions/grep.html">"grep"</a>. <i>www.perldoc.perl.org</i>. <a href="https://web.archive.org/web/20151207062445/http://perldoc.perl.org/functions/grep.html">Archived</a> from the original on 7 December 2015. Retrieved 12 December 2015.</cite>
</li>
<li><b><a href="#cite_ref-17">^</a></b> <cite><a href="http://www.pcre.org/original/doc/html/pcregrep.html">"pcregrep man page"</a>. <i>www.pcre.org</i>. University of Cambridge. <a href="https://web.archive.org/web/20151223035259/http://www.pcre.org/original/doc/html/pcregrep.html">Archived</a> from the original on 23 December 2015. Retrieved 12 December 2015.</cite>
</li>
<li><b><a href="#cite_ref-18">^</a></b> <cite><a href="http://linux.die.net/man/1/grep">"grep(1)"</a>. <i>www.linux.die.net</i>. <a href="https://web.archive.org/web/20151210004321/http://linux.die.net/man/1/grep">Archived</a> from the original on 10 December 2015. Retrieved 12 December 2015.</cite>
</li>
<li><b><a href="#cite_ref-19">^</a></b> <cite>Spalding, George (2000). <a href="https://archive.org/details/windows2000admin0000spal"><i>Windows 2000 administration</i></a>. Network professional's library. Osborne/McGraw-Hill. pp. <a href="https://archive.org/details/windows2000admin0000spal/page/634">634</a>. <a href="/wiki/ISBN_(identifier)">ISBN</a> <a href="/wiki/Special:BookSources/978-0-07-882582-8"><bdi>978-0-07-882582-8</bdi></a>. Retrieved 2010-12-10. <q>QGREP.EXE[:] A similar tool to grep in UNIX, this tool can be used to search for a text string</q></cite>
</li>
<li><b><a href="#cite_ref-20">^</a></b> <cite><a href="https://archive.org/details/MSXDOS2TOOLS">"MSX-DOS2 Tools User's Manual by ASCII Corporation"</a>. April 1993.</cite>
</li>
<li><b><a href="#cite_ref-21">^</a></b> <cite><a href="/wiki/IBM">IBM</a>. <a href="https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_74/rzahz/rzahzpdf.pdf?view=kc">"IBM System i Version 7.2 Programming Qshell"</a> (PDF). <i><a href="/wiki/IBM">IBM</a></i>. Retrieved 2020-09-05.</cite>
</li>
<li><b><a href="#cite_ref-22">^</a></b> <cite><a href="https://creativepro.com/review-adobe-indesign-cs3/">"Review: Adobe InDesign CS3 - CreativePro.com"</a>. <i>creativepro.com</i>. 20 April 2007. <a href="https://web.archive.org/web/20180105233709/https://creativepro.com/review-adobe-indesign-cs3/">Archived</a> from the original on 5 January 2018. Retrieved 24 April 2018.</cite>
</li>
<li><b><a href="#cite_ref-23">^</a></b> <cite><a href="https://helpx.adobe.com/indesign/using/find-change.html">"InDesign Help: find/change"</a>. <a href="https://web.archive.org/web/20160828124223/https://helpx.adobe.com/indesign/using/find-change.html">Archived</a> from the original on 2016-08-28. Retrieved 2016-08-12.</cite>
</li>
<li><b><a href="#cite_ref-24">^</a></b> <cite><a href="http://carijansen.com/tip-088/">"InDesign: GREP Styles (1) Setting text between parentheses in Italic"</a>. <a href="https://web.archive.org/web/20170924230421/http://carijansen.com/tip-088/">Archived</a> from the original on 2017-09-24. Retrieved 2018-01-05.</cite>
</li>
<li><b><a href="#cite_ref-25">^</a></b> <cite><a href="https://helpx.adobe.com/indesign/using/drop-caps-nested-styles.html#create_grep_styles">"InDesign Help: GREP styles"</a>. <a href="https://web.archive.org/web/20160828114627/https://helpx.adobe.com/indesign/using/drop-caps-nested-styles.html#create_grep_styles">Archived</a> from the original on 2016-08-28. Retrieved 2016-08-12.</cite>
</li>
<li><b><a href="#cite_ref-eGrep.SunX_26-0">^</a></b> <cite>S. Lee Henry (June 1998). "Proper Searching". <i>Sun Expert</i>. pp. 35–26.</cite>
</li>
<li><b><a href="#cite_ref-27">^</a></b> <cite><a href="https://public.oed.com/updates/new-words-list-december-2003/">"New words list December 2003"</a>. <i>Oxford English Dictionary</i>. Retrieved 2021-12-06.</cite>
</li>
<li><b><a href="#cite_ref-28">^</a></b> <i><a href="/wiki/Jargon_File">Jargon File</a></i>, article "Documentation"
</li>
</ol></div>
<dl><dt>Notes</dt></dl>
<div>
<ul><li><cite>Alain Magloire (August 2000). <i>Grep: Searching for a Pattern</i>. Iuniverse Inc. <a href="/wiki/ISBN_(identifier)">ISBN</a> <a href="/wiki/Special:BookSources/0-595-10039-2"><bdi>0-595-10039-2</bdi></a>.</cite></li>
<li>Hume, Andrew <i>Grep wars: The strategic search initiative.</i> In Peter Collinson, editor, <i>Proceedings of the EUUG Spring 88 Conference</i>, pages 237–245, Buntingford, UK, 1988. European UNIX User Group.</li>
<li><cite><a href="/wiki/Michael_Hauben">Michael Hauben</a>; et al. (April 1997). <i>Netizens: On the History and Impact of Usenet and the Internet (Perspectives)</i>. Wiley-IEEE Computer Society Press. <a href="/wiki/ISBN_(identifier)">ISBN</a> <a href="/wiki/Special:BookSources/978-0-8186-7706-9"><bdi>978-0-8186-7706-9</bdi></a>.</cite></li></ul>
</div>
<h2>External links[<a href="/w/index.php?title=Grep&amp;action=edit&amp;section=7">edit</a>]</h2>
<ul><li><a href="https://www.gnu.org/software/grep/">GNU Grep official website</a></li>
<li><a href="https://www.gnu.org/software/grep/manual/grep.html">GNU Grep manual</a></li>
<li><code><a href="https://9p.io/magic/man2html/1/grep">grep(1)</a></code> – <a href="/wiki/Plan_9_from_Bell_Labs">Plan 9</a> Programmer's Manual, Volume 1</li>
<li><code><a href="http://man.cat-v.org/inferno/1/grep">grep(1)</a></code> – <a href="/wiki/Inferno_(operating_system)">Inferno</a> General commands <a href="/wiki/Man_page">Manual</a></li>
<li><a href="http://lists.freebsd.org/pipermail/freebsd-current/2010-August/019310.html">"why GNU grep is fast"</a> - implementation details from GNU grep's author.</li>
<li><a href="https://www.linuxteacher.com/grep-command-in-unix-linux-with-examples/">Command Grep – 25 practical examples</a></li></ul>
</div>||||I|||| Jump to content
 Toggle sidebar
 Search
 * Create account
 * Log in
 Personal tools
 * Create account
 * Log in
 Pages for logged out editors learn more
 * Contributions
 * Talk
 Navigation
 * Main page
 * Contents
 * Current events
 * Random article
 * About Wikipedia
 * Contact us
 * Donate
 Contribute
 * Help
 * Learn to edit
 * Community portal
 * Recent changes
 * Upload file
 Tools
 * What links here
 * Related changes
 * Upload file
 * Special pages
 * Permanent link
 * Page information
 * Cite this page
 * Wikidata item
 Print/export
 * Download as PDF
 * Printable version
 In other projects
 * Wikimedia Commons
 * Wikibooks
 Languages
 On this Wikipedia the language links are at the top of the page across from the article title. Go to top.

 Contents

 move to sidebar hide
 * (Top)
 * 1 History
 * 2 Implementations
 Toggle Implementations subsection
 + 2.1 agrep
 * 3 Usage as a verb
 * 4 See also
 * 5 References
 * 6 External links
 Toggle the table of contents
 Toggle the table of contents

 grep

 32 languages
 * العربية
 * Azərbaycanca
 * Български
 * Català
 * Čeština
 * Dansk
 * Deutsch
 * Ελληνικά
 * Español
 * فارسی
 * Français
 * 한국어
 * Հայերեն
 * Hrvatski
 * Italiano
 * עברית
 * Latviešu
 * Magyar
 * Nederlands
 * 日本語
 * Norsk bokmål
 * Polski
 * Português
 * Română
 * Русский
 * Slovenščina
 * Српски / srpski
 * Suomi
 * Svenska
 * Türkçe
 * Українська
 * 中文
 Edit links
 * Article
 * Talk
 English
 * Read
 * Edit
 * View history
 More
 * Read
 * Edit
 * View history
 From Wikipedia, the free encyclopedia
 grep
 Example of grep command
 Original author(s) Ken Thompson[1][2] 
 Developer(s) AT&T Bell Laboratories 
 Initial release November 1973 ; 49 years ago [1] 
 Written in C 
 Operating system Unix, Unix-like, Plan 9, Inferno, OS-9, MSX-DOS, IBM i
 Platform Cross-platform 
 Type Command 
 

 grep is a command-line utility for searching plain-text data sets for lines that match a regular expression. Its name comes from the ed command g/re/p (globally search for a regular expression and print matching lines), which has the same effect.[3][4] grep was originally developed for the Unix operating system, but later available for all Unix-like systems and some others such as OS-9.[5]

 History [ edit ]

 Before it was named, grep was a private utility written by Ken Thompson to search files for certain patterns. Doug McIlroy, unaware of its existence, asked Thompson to write such a program. Responding that he would think about such a utility overnight, Thompson actually corrected bugs and made improvements for about an hour on his own program called s (short for "search"). The next day he presented the program to McIlroy, who said it was exactly what he wanted. Thompson's account may explain the belief that grep was written overnight.[6]

 Thompson wrote the first version in PDP-11 assembly language to help Lee E. McMahon analyze the text of The Federalist Papers to determine authorship of the individual papers.[7] The ed text editor (also authored by Thompson) had regular expression support but could not be used on such a large amount of text, so Thompson excerpted that code into a standalone tool.[1] He chose the name because in ed, the command g/re/p would print all lines matching a specified pattern.[8][9] grep was first included in Version 4 Unix. Stating that it is "generally cited as the prototypical software tool", McIlroy credited grep with "irrevocably ingraining" Thompson's tools philosophy in Unix.[10]

 Implementations [ edit ]

 A variety of grep implementations are available in many operating systems and software development environments.[11] Early variants included egrep and fgrep, introduced in Version 7 Unix.[10] The "egrep" variant supports an extended regular expression syntax added by Alfred Aho after Ken Thompson's original regular expression implementation.[12] The "fgrep" variant searches for any of a list of fixed strings using the Aho–Corasick string matching algorithm.[13] Binaries of these variants exist in modern systems, usually linking to grep or calling grep as a shell script with the appropriate flag added, e.g. exec grep -E "$@". egrep and fgrep, while commonly deployed on POSIX systems, to the point the POSIX specification mentions their widespread existence, are actually not part of POSIX.[14]

 Other commands contain the word "grep" to indicate they are search tools, typically ones that rely on regular expression matches. The pgrep utility, for instance, displays the processes whose names match a given regular expression.[15]

 In the Perl programming language, grep is the name of the built-in function that finds elements in a list that satisfy a certain property.[16] This higher-order function is typically named filter or where in other languages.

 The pcregrep command is an implementation of grep that uses Perl regular expression syntax.[17] Similar functionality can be invoked in the GNU version of grep with the -P flag.[18]

 Ports of grep (within Cygwin and GnuWin32, for example) also run under Microsoft Windows. Some versions of Windows feature the similar qgrep or findstr command.[19]

 A grep command is also part of ASCII's MSX-DOS2 Tools for MSX-DOS version 2.[20]

 The grep , egrep , and fgrep commands have also been ported to the IBM i operating system.[21]

 The software Adobe InDesign has functions GREP (since CS3 version (2007)[22]), in the find/change dialog box[23] "GREP" tab, and introduced with InDesign CS4[24] in paragraph styles[25] "GREP styles".

 agrep [ edit ]

 Main article: agrep

 agrep (approximate grep) matches even when the text only approximately fits the search pattern.[26]

 This following invocation finds netmasks in file myfile, but also any other word that can be derived from it, given no more than two substitutions.

 agrep -2 netmasks myfile
 

 This example generates a list of matches with the closest, that is those with the fewest, substitutions listed first. The command flag B means best:

 agrep -B netmasks myfile
 

 Usage as a verb [ edit ]

 In December 2003, the Oxford English Dictionary Online added "grep" as both a noun and a verb.[27]

 A common verb usage is the phrase "You can't grep dead trees"—meaning one can more easily search through digital media, using tools such as grep, than one could with a hard copy (i.e. one made from "dead trees", which in this context is a dysphemism for paper).[28]

 See also [ edit ]

 * Free and open-source software portal
 * Boyer–Moore string-search algorithm
 * agrep, an approximate string-matching command
 * find (Windows) or Findstr, a DOS and Windows command that performs text searches, similar to a simple grep
 * find (Unix), a Unix command that finds files by attribute, very different from grep
 * List of Unix commands
 * vgrep, or "visual grep"
 * ngrep, the network grep

 References [ edit ]

 1. ^ a b c Kernighan, Brian (1984). The Unix Programming Environment. Prentice Hall. pp. 102. ISBN 0-13-937681-X.
 2. ^ “grep was a private command of mine for quite a while before i made it public.” -Ken Thompson Archived 2015-05-26 at the Wayback Machine , By Benjamin Rualthanzauva, Published on Feb 5, 2014, Medium
 3. ^ Hauben et al. 1997, Ch. 9
 4. ^ Raymond, Eric. "grep". Jargon File. Archived from the original on 2006-06-17 . Retrieved 2006-06-29 .
 5. ^ Paul S. Dayan (1992). The OS-9 Guru - 1 : The Facts. Galactic Industrial Limited. ISBN 0-9519228-0-7.
 6. ^ VCF East 2019 -- Brian Kernighan interviews Ken Thompson (video). YouTube. 6 May 2019. Archived from the original on 2021-12-11. (35 mins)
 7. ^ Computerphile, Where GREP Came From , interview with Brian Kernighan
 8. ^ "ed regexes". perl.plover.com. Archived from the original on 20 October 2017 . Retrieved 24 April 2018 .
 9. ^ "How Grep Got its Name". robots.thoughtbot.com. Archived from the original on 9 August 2017 . Retrieved 24 April 2018 .
 10. ^ a b McIlroy, M. D. (1987). A Research Unix reader: annotated excerpts from the Programmer's Manual, 1971–1986 (PDF) (Technical report). CSTR. Bell Labs. 139. Archived (PDF) from the original on 2017-11-11.
 11. ^ Abou-Assaleh, Tony; Wei Ai (March 2004). Survey of Global Regular Expression Print (GREP) Tools (Technical report). Dalhousie University.
 12. ^ Hume, Andrew (1988). "A Tale of Two Greps". Software: Practice and Experience. 18 (11): 1063. doi:10.1002/spe.4380181105. S2CID 6395770.
 13. ^ Meurant, Gerard (12 Sep 1990). Algorithms and Complexity. Elsevier Science. p. 278. ISBN 9780080933917. Archived from the original on 4 March 2016 . Retrieved 12 December 2015 .
 14. ^ "grep". www.pubs.opengroup.org. The Open Group. Archived from the original on 28 November 2015 . Retrieved 12 December 2015 .
 15. ^ "pgrep(1)". www.linux.die.net. Archived from the original on 22 December 2015 . Retrieved 12 December 2015 .
 16. ^ "grep". www.perldoc.perl.org. Archived from the original on 7 December 2015 . Retrieved 12 December 2015 .
 17. ^ "pcregrep man page". www.pcre.org. University of Cambridge. Archived from the original on 23 December 2015 . Retrieved 12 December 2015 .
 18. ^ "grep(1)". www.linux.die.net. Archived from the original on 10 December 2015 . Retrieved 12 December 2015 .
 19. ^ Spalding, George (2000). Windows 2000 administration. Network professional's library. Osborne/McGraw-Hill. pp. 634. ISBN 978-0-07-882582-8 . Retrieved 2010-12-10 . "QGREP.EXE[:] A similar tool to grep in UNIX, this tool can be used to search for a text string"
 20. ^ "MSX-DOS2 Tools User's Manual by ASCII Corporation". April 1993.
 21. ^ IBM. "IBM System i Version 7.2 Programming Qshell" (PDF) . IBM . Retrieved 2020-09-05 .
 22. ^ "Review: Adobe InDesign CS3 - CreativePro.com". creativepro.com. 20 April 2007. Archived from the original on 5 January 2018 . Retrieved 24 April 2018 .
 23. ^ "InDesign Help: find/change". Archived from the original on 2016-08-28 . Retrieved 2016-08-12 .
 24. ^ "InDesign: GREP Styles (1) Setting text between parentheses in Italic". Archived from the original on 2017-09-24 . Retrieved 2018-01-05 .
 25. ^ "InDesign Help: GREP styles". Archived from the original on 2016-08-28 . Retrieved 2016-08-12 .
 26. ^ S. Lee Henry (June 1998). "Proper Searching". Sun Expert. pp. 35–26.
 27. ^ "New words list December 2003". Oxford English Dictionary . Retrieved 2021-12-06 .
 28. ^ Jargon File , article "Documentation"
 Notes
 * Alain Magloire (August 2000). Grep: Searching for a Pattern. Iuniverse Inc. ISBN 0-595-10039-2.
 * Hume, Andrew Grep wars: The strategic search initiative. In Peter Collinson, editor, Proceedings of the EUUG Spring 88 Conference, pages 237–245, Buntingford, UK, 1988. European UNIX User Group.
 * Michael Hauben; et al. (April 1997). Netizens: On the History and Impact of Usenet and the Internet (Perspectives). Wiley-IEEE Computer Society Press. ISBN 978-0-8186-7706-9.

 External links [ edit ]

 The Wikibook How To Search has a page on the topic of: grep
 * GNU Grep official website
 * GNU Grep manual
 * grep(1) – Plan 9 Programmer's Manual, Volume 1
 * grep(1) – Inferno General commands Manual
 * "why GNU grep is fast" - implementation details from GNU grep's author.
 * Command Grep – 25 practical examples
 * v 
 * t 
 * e 
 Unix command-line interface programs and shell builtins
  * cat 
  * chattr 
  * chmod 
  * chown 
  * chgrp 
  * cksum 
  * cmp 
  * cp 
  * dd 
  * du 
  * df 
  * file 
 File system * fuser 
  * ln 
  * ls 
  * mkdir 
  * mv 
  * pax 
  * pwd 
  * rm 
  * rmdir 
  * split 
  * tee 
  * touch 
  * type 
  * umask 
  * at 
  * bg 
  * crontab 
 Processes * fg 
  * kill 
  * nice 
  * ps 
  * time 
  * env 
  * exit 
  * logname 
  * mesg 
 User environment * talk 
  * tput 
  * uname 
  * who 
  * write 
  * awk 
  * basename 
  * comm 
  * csplit 
  * cut 
  * diff 
  * dirname 
  * ed 
  * ex 
  * fold 
  * head 
  * iconv 
  * join 
  * m4 
 Text processing * more 
  * nl 
  * paste 
  * patch 
  * printf 
  * read 
  * sed 
  * sort 
  * strings 
  * tail 
  * tr 
  * troff 
  * uniq 
  * vi 
  * wc 
  * xargs 
  * alias 
  * cd 
 Shell builtins * echo 
  * test 
  * unset 
  * wait 
 Searching * find 
  * grep 
 Documentation * man 
  * ar 
  * ctags 
  * lex 
 Software development * make 
  * nm 
  * strip 
  * yacc 
  * bc 
  * cal 
  * expr 
 Miscellaneous * lp 
  * od 
  * sleep 
  * true and false
 * Categories 
 + Standard Unix programs 
 + Unix SUS2008 utilities 
 * List 
 
 * v 
 * t 
 * e 
 Plan 9 command-line interface programs and shell builtins
  * chmod 
  * chgrp 
  * cmp 
  * cp 
  * dd 
  * du 
  * file 
 File system * gzip 
  * ls 
  * mkdir 
  * pwd 
  * rm 
  * split 
  * tee 
  * touch 
 Processes * kill 
  * ps 
 User environment * passwd 
  * who 
  * awk 
  * basename 
  * comm 
  * diff 
  * ed 
  * eqn 
  * join 
 Text processing * sed 
  * sort 
  * spell 
  * strings 
  * tail 
  * tr 
  * troff 
  * uniq 
  * wc 
 Shell builtins * echo 
  * test 
  * ip/ipconfig
 Networking * ip/ping 
  * netstat 
 Searching * grep 
  * ar 
  * hoc 
 Software development * lex 
  * nm 
  * strip 
  * yacc 
  * bc 
 Miscellaneous * cal 
  * fortune 
  * sleep 
 * Category 
 
 Authority control: National libraries * Germany
 
 Retrieved from "https://en.wikipedia.org/w/index.php?title=Grep&oldid=1136479714"
 Categories:
 * Unix text processing utilities
 * Unix SUS2008 utilities
 * Standard Unix programs
 * Plan 9 commands
 * Inferno (operating system) commands
 * IBM i Qshell commands
 Hidden categories:
 * Webarchive template wayback links
 * Articles with short description
 * Short description is different from Wikidata
 * Articles with GND identifiers
 * This page was last edited on 30 January 2023, at 14:47 (UTC) .
 * Text is available under the Creative Commons Attribution-ShareAlike License 3.0; additional terms may apply. By using this site, you agree to the Terms of Use and Privacy Policy. Wikipedia® is a registered trademark of the Wikimedia Foundation, Inc., a non-profit organization.
 * Privacy policy
 * About Wikipedia
 * Disclaimers
 * Contact Wikipedia
 * Mobile view
 * Developers
 * Statistics
 * Cookie statement
 * 
 * 
From Wikipedia, the free encyclopedia
	 
 grep      Example of grep command     Original author(s)   Ken Thompson  [1]   [2]      Developer(s)   AT&amp;T Bell Laboratories    Initial release November 1973; 49 years ago [1]     Written in  C     Operating system   Unix, Unix-like, Plan 9, Inferno, OS-9, MSX-DOS, IBM i     Platform   Cross-platform     Type   Command    
  grep  is a command-line utility for searching plain-text data sets for lines that match a regular expression. Its name comes from the ed command g/re/p (globally search for a regular expression and print matching lines), which has the same effect. [3]   [4]  grep was originally developed for the Unix operating system, but later available for all Unix-like systems and some others such as OS-9. [5] 
History[edit]
Before it was named, grep was a private utility written by Ken Thompson to search files for certain patterns. Doug McIlroy, unaware of its existence, asked Thompson to write such a program. Responding that he would think about such a utility overnight, Thompson actually corrected bugs and made improvements for about an hour on his own program called s (short for "search"). The next day he presented the program to McIlroy, who said it was exactly what he wanted. Thompson's account may explain the belief that grep was written overnight. [6] 
 Thompson wrote the first version in PDP-11 assembly language to help Lee E. McMahon analyze the text of  The Federalist Papers  to determine authorship of the individual papers. [7]  The ed text editor (also authored by Thompson) had regular expression support but could not be used on such a large amount of text, so Thompson excerpted that code into a standalone tool. [1]  He chose the name because in ed, the command g/re/p would print all lines matching a specified pattern. [8]   [9]  grep was first included in Version 4 Unix. Stating that it is "generally cited as the prototypical software tool", McIlroy credited grep with "irrevocably ingraining" Thompson's tools philosophy in Unix. [10] 
Implementations[edit]
A variety of grep implementations are available in many operating systems and software development environments. [11]  Early variants included egrep and fgrep, introduced in Version 7 Unix. [10]  The "egrep" variant supports an extended regular expression syntax added by Alfred Aho after Ken Thompson's original regular expression implementation. [12]  The "fgrep" variant searches for any of a list of fixed strings using the Aho–Corasick string matching algorithm. [13]  Binaries of these variants exist in modern systems, usually linking to grep or calling grep as a shell script with the appropriate flag added, e.g. exec grep -E "$@". egrep and fgrep, while commonly deployed on POSIX systems, to the point the POSIX specification mentions their widespread existence, are actually not part of POSIX. [14] 
 Other commands contain the word "grep" to indicate they are search tools, typically ones that rely on regular expression matches. The  pgrep  utility, for instance, displays the processes whose names match a given regular expression. [15] 
 In the Perl programming language, grep is the name of the built-in function that finds elements in a list that satisfy a certain property. [16]  This higher-order function is typically named  filter  or where in other languages.
 The pcregrep command is an implementation of grep that uses Perl regular expression syntax. [17]  Similar functionality can be invoked in the GNU version of grep with the -P flag. [18] 
  Ports of grep (within Cygwin and GnuWin32, for example) also run under Microsoft Windows. Some versions of Windows feature the similar qgrep or  findstr  command. [19] 
 A grep command is also part of ASCII's MSX-DOS2 Tools for MSX-DOS version 2. [20] 
 The grep, egrep, and fgrep commands have also been ported to the IBM i operating system. [21] 
 The software Adobe InDesign has functions GREP (since CS3 version (2007) [22] ), in the find/change dialog box [23]  "GREP" tab, and introduced with InDesign CS4 [24]  in paragraph styles  [25]  "GREP styles".
agrep[edit]
  agrep (approximate grep) matches even when the text only approximately fits the search pattern. [26] 
 This following invocation finds netmasks in file myfile, but also any other word that can be derived from it, given no more than two substitutions.
agrep -2 netmasks myfile
This example generates a list of matches with the closest, that is those with the fewest, substitutions listed first. The command flag B means best:
agrep -B netmasks myfile
Usage as a verb[edit]
In December 2003, the  Oxford English Dictionary Online added "grep" as both a noun and a verb. [27] 
 A common verb usage is the phrase "You can't grep dead trees"—meaning one can more easily search through digital media, using tools such as grep, than one could with a hard copy (i.e. one made from "dead trees", which in this context is a dysphemism for paper). [28] 
See also[edit]
  Boyer–Moore string-search algorithm 
 agrep, an approximate string-matching command
 find (Windows) or Findstr, a DOS and Windows command that performs text searches, similar to a simple grep 
 find (Unix), a Unix command that finds files by attribute, very different from grep 
 List of Unix commands 
 vgrep, or "visual grep"
 ngrep, the network grep 
References[edit]
^    a       b       c    Kernighan, Brian (1984).  The Unix Programming Environment . Prentice Hall. pp. 102. ISBN  0-13-937681-X .
  ^  “grep was a private command of mine for quite a while before i made it public.” -Ken Thompson Archived 2015-05-26 at the Wayback Machine, By Benjamin Rualthanzauva, Published on Feb 5, 2014, Medium
  ^  Hauben et al. 1997, Ch. 9
  ^   Raymond, Eric. "grep". Jargon File. Archived from the original on 2006-06-17. Retrieved 2006-06-29.
  ^  Paul S. Dayan (1992). The OS-9 Guru - 1 : The Facts. Galactic Industrial Limited. ISBN  0-9519228-0-7 .
  ^    VCF East 2019 -- Brian Kernighan interviews Ken Thompson  (video). YouTube. 6 May 2019. Archived from the original on 2021-12-11. (35 mins)
  ^  Computerphile,  Where GREP Came From , interview with Brian Kernighan
  ^   "ed regexes". perl.plover.com. Archived from the original on 20 October 2017. Retrieved 24 April 2018.
  ^   "How Grep Got its Name". robots.thoughtbot.com. Archived from the original on 9 August 2017. Retrieved 24 April 2018.
^    a       b     McIlroy, M. D. (1987).  A Research Unix reader: annotated excerpts from the Programmer's Manual, 1971–1986  (PDF) (Technical report). CSTR. Bell Labs. 139. Archived (PDF) from the original on 2017-11-11.
  ^  Abou-Assaleh, Tony; Wei Ai (March 2004). Survey of Global Regular Expression Print (GREP) Tools (Technical report). Dalhousie University.
  ^  Hume, Andrew (1988). "A Tale of Two Greps". Software: Practice and Experience. 18 (11): 1063. doi:10.1002/spe.4380181105. S2CID 6395770.
  ^  Meurant, Gerard (12 Sep 1990).  Algorithms and Complexity . Elsevier Science. p. 278. ISBN  9780080933917 . Archived from the original on 4 March 2016. Retrieved 12 December 2015.
  ^   "grep". www.pubs.opengroup.org. The Open Group. Archived from the original on 28 November 2015. Retrieved 12 December 2015.
  ^   "pgrep(1)". www.linux.die.net. Archived from the original on 22 December 2015. Retrieved 12 December 2015.
  ^   "grep". www.perldoc.perl.org. Archived from the original on 7 December 2015. Retrieved 12 December 2015.
  ^   "pcregrep man page". www.pcre.org. University of Cambridge. Archived from the original on 23 December 2015. Retrieved 12 December 2015.
  ^   "grep(1)". www.linux.die.net. Archived from the original on 10 December 2015. Retrieved 12 December 2015.
  ^  Spalding, George (2000).  Windows 2000 administration . Network professional's library. Osborne/McGraw-Hill. pp. 634. ISBN  978-0-07-882582-8 . Retrieved 2010-12-10. QGREP.EXE[:] A similar tool to grep in UNIX, this tool can be used to search for a text string 
  ^   "MSX-DOS2 Tools User's Manual by ASCII Corporation". April 1993.
  ^   IBM. "IBM System i Version 7.2 Programming Qshell" (PDF).  IBM . Retrieved 2020-09-05.
  ^   "Review: Adobe InDesign CS3 - CreativePro.com". creativepro.com. 20 April 2007. Archived from the original on 5 January 2018. Retrieved 24 April 2018.
  ^   "InDesign Help: find/change". Archived from the original on 2016-08-28. Retrieved 2016-08-12.
  ^   "InDesign: GREP Styles (1) Setting text between parentheses in Italic". Archived from the original on 2017-09-24. Retrieved 2018-01-05.
  ^   "InDesign Help: GREP styles". Archived from the original on 2016-08-28. Retrieved 2016-08-12.
  ^  S. Lee Henry (June 1998). "Proper Searching". Sun Expert. pp. 35–26.
  ^   "New words list December 2003". Oxford English Dictionary. Retrieved 2021-12-06.
  ^   Jargon File , article "Documentation"
 
 Notes 
  Alain Magloire (August 2000). Grep: Searching for a Pattern. Iuniverse Inc. ISBN  0-595-10039-2 . 
Hume, Andrew Grep wars: The strategic search initiative. In Peter Collinson, editor, Proceedings of the EUUG Spring 88 Conference, pages 237–245, Buntingford, UK, 1988. European UNIX User Group.
  Michael Hauben; et al. (April 1997). Netizens: On the History and Impact of Usenet and the Internet (Perspectives). Wiley-IEEE Computer Society Press. ISBN  978-0-8186-7706-9 .  
External links[edit]
  GNU Grep official website 
 GNU Grep manual 
  grep(1)  – Plan 9 Programmer's Manual, Volume 1
  grep(1)  – Inferno General commands Manual 
 "why GNU grep is fast" - implementation details from GNU grep's author.
 Command Grep – 25 practical examples
grep - Wikipedia
https://en.wikipedia.org/wiki/Grep
https://www.tomshardware.com/how-to/grep-command-linux
How to Use the Grep Command in Linux to Search Inside Files
2022-05-07
Jo Hinchliffe
<div><div>
 <p> You’re looking for that one file, the one that contains the all important information for your next meeting. Do you manually search all of your files? That will take time. Instead we use a little Linux command line magic. <em>Grep</em> is a pattern matching command that we can use to search inside files and directories for specific text. <em>Grep</em> is commonly used with the output of one command, piped to be the input of the grep command. For example we can search inside a file for a specific string of text using the <em>less</em> command, and pipe the output to <em>grep</em>.</p><p>In this how-to we will use the <em>grep </em>command and commonly added arguments to search for specific strings of data within files. We’ll begin by setting up a small directory of test files as searching an entire filesystem can take some time and create a lot of results.</p><p>All the commands in this how-to will work on most Linux machines. We’ve used a Ubuntu 20.04 install but you could run this how-to on a<a href="https://www.tomshardware.com/news/raspberry-pi"> <u>Raspberry Pi</u></a>. All of the how-to is performed via the Terminal. You can open a terminal window on most Linux machines by pressing <em>ctrl, alt </em>and <em>t.</em></p><h2>Set Up a Test Environment for grep </h2><figure><div><p></p></div><figcaption>(Image credit: Tom's Hardware)</figcaption></figure><p>As <em>grep </em>can be used in lots of different ways we need to set up a directory and some content that allow us to explore its uses. In this section we will create this test environment.</p><p>1. <strong>Set up a </strong><em><strong>test </strong></em><strong>directory and change directory so that you are inside it.</strong></p><pre><code>mkdir test
cd test</code></pre><p>2.<strong>Create 4 files, test1, test2, test3 and test4.</strong></p><pre><code>touch test1 test2 test3 test4
ls</code></pre><p>3. <strong>Edit </strong><em><strong>test1 </strong></em><strong>using </strong><em><strong>nano </strong></em><strong>to contain the following names on separate lines. </strong>Note that in <em>test1 </em>none of the names contain capitals. After editing in <em>nano </em>press <em>control x </em>to exit, press <em>y </em>to confirm the save and then press <em>enter</em>.</p><pre><code>nano test1</code></pre><p>4. <strong>Add the following text to the file. Then press CTRL + X, then Y and Enter to save and exit.</strong></p><pre><code>ali
mohamed
claire
aled
steve</code></pre><p>5. <strong>Edit </strong><em><strong>test2</strong></em><strong> using </strong><em><strong>nano. </strong></em>In <em>test2 </em>we will add a single longer line of test containing the name <em>steve</em>.</p><pre><code>nano test2</code></pre><p>6. <strong>Add the following text to the file. Then press CTRL + X, then Y and Enter to save and exit.</strong></p><pre><code>this is a long line of test that contains the name steve</code></pre><p>7. <strong>Edit</strong><em><strong> test3</strong></em><strong> in</strong><em><strong> nano.</strong></em> Similar to <em>test1 </em>we will add a list of names on separate lines but this list will include the name <em>steven.</em></p><pre><code>nano test3</code></pre><p>8. <strong>Add the following text to the file. Then press CTRL + X, then Y and Enter to save and exit.</strong></p><pre><code>alice
geoff
murbarak
mohamed
steven</code></pre><p>9. <strong>Finally edit </strong><em><strong>test4 </strong></em><strong>to complete our test environment.</strong> Note that in this file we are using a capital letter at the start of<em> Steve.</em></p><pre><code>nano test4</code></pre><p>10. <strong>Add the following text to the file. Then press CTRL + X, then Y and Enter to save and exit.</strong></p><pre><code>Steve ?</code></pre><h2>Simple Searches with grep </h2><figure><div><p></p></div><figcaption>(Image credit: Tom's Hardware)</figcaption></figure><p>Searching a file for a specific string is extremely useful. For example when debugging an error in a log file. Let’s start using <em>grep </em>in its most basic form. <br />
The <em>grep </em>command syntax is simply<em> grep </em>followed by any arguments, then the string we wish to search for and then finally the location in which to search.</p><p>1. <strong>Search </strong><em><strong>test1 </strong></em><strong>for the string </strong><em><strong>steve </strong></em><strong>using grep.</strong> The search criteria is case sensitive so ensure that you're searching correctly. Notice that the word<em> steve</em> is simply returned in red to indicate it has been found in the file.</p><pre><code>grep steve test1</code></pre><p>2. <strong>Search for the same string in multiple files. </strong>We can simply add a list of files to the <em>grep </em>command for it to search. Notice that, with multiple search areas, the returned results are tagged with each filename from which the result is found. Also notice that <em>grep </em>returns the complete line of text that contains the searched string.</p><pre><code>grep steve test1 test2</code></pre><p>3. <strong>Search all files within the directory.</strong> Adding an asterisk forces <em>grep</em> to search all files within the current directory. Notice that the returned results include the result from <em>test3 </em>where the search string <em>steve </em>is contained within Steven. Note also that these results don’t contain the result from <em>test4 </em>as in its basic form the <em>grep </em>command is case sensitive.</p><pre><code>grep steve *</code></pre><p>4. <strong>Add the argument </strong><em><strong>-i </strong></em><strong>to make </strong><em><strong>grep </strong></em><strong>case insensitive. </strong>This will return results from all four of the test files in the directory.</p><pre><code>grep -i steve *</code></pre><h2>Piping output to grep</h2><p>The strongest use case for grep is when it is paired with another command. Using pipes we send the output of a command to <em>grep</em> and use it to search for patterns / keywords.</p><p>1. <strong>Open a new terminal window.</strong></p><p>2. <strong>Use </strong><em><strong>lsusb</strong></em><strong> to list all of the USB devices attached to your machine. </strong>This will also list internal USB devices, such as laptop webcams. The output will differ depending on your machine, but you should be met with a wall of text.</p><pre><code>lsusb</code></pre><figure><div><p></p></div><figcaption>(Image credit: Tom's Hardware)</figcaption></figure><p>3. <strong>Use the </strong><em><strong>lsusb </strong></em><strong>command again, but this time use </strong><em><strong>grep </strong></em><strong>to search for Linux.</strong> By adding a pipe between <em>lsusb </em>and <em>grep</em> the output of the first command is used as the input of the second.</p><pre><code>lsusb | grep Linux</code></pre><figure><div><p></p></div><figcaption>(Image credit: Tom's Hardware)</figcaption></figure><h2>Using dmesg and grep to Inspect the Kernel Ring Buffer</h2><p>Let's try something a little more complex. This time we’ll use <em>dmesg</em> and <em>grep</em> to inspect the Kernel Ring Buffer (essentially the kernel’s log file). We are going to search for a keyword in <em>dmesg</em>, “secureboot”, and confirm that it is enabled.</p><p>1. <strong>Open a terminal and run the dmesg command as sudo. </strong>This will print a wall of console output to the terminal, something that we can search using grep.</p><pre><code>sudo dmesg</code></pre><figure><div><p></p></div><figcaption>(Image credit: Tom's Hardware)</figcaption></figure><p>2. <strong>Use the </strong><em><strong>grep </strong></em><strong>command to search for “secureboot” in the </strong><em><strong>dmesg</strong></em><strong> output. Use the </strong><em><strong>-i </strong></em><strong>argument </strong>to turn off case-sensitivity so that we catch every occurrence of secureboot. The output will show the lines at which secureboot appears in <em>dmesg</em>.</p><pre><code>sudo dmesg | less | grep -i secureboot</code></pre><figure><div><p></p></div><figcaption>(Image credit: Tom's Hardware)</figcaption></figure><h2>Other Uses of grep </h2><figure><div><p></p></div><figcaption>(Image credit: Tom's Hardware)</figcaption></figure><p>Like many Linux commands there are many useful additions and variants for the <em>grep </em>command. Let’s look at a couple of interesting examples.</p><p>1. <strong>Perform an inverted search using the </strong><em><strong>-v </strong></em><strong>argument. </strong>This will return a list of every line from the test environment files that doesn’t contain the search string <em>steve. </em>This argument is useful to dismiss occurrences of strings in logs or files when debugging an issue. Note that again the results are case sensitive and therefore they include the line containing the capitalized <em>Steve ? </em>from <em>test4.</em></p><pre><code>grep -v steve *</code></pre><p>2. <strong>Combine the </strong><em><strong>-v </strong></em><strong>and </strong><em><strong>-i </strong></em><strong>arguments to exclude all matching strings regardless of case.</strong></p><pre><code>grep -vi steve *</code></pre><p>3. <strong>Search for a string that contains non alphanumeric text or spaces. </strong>If you include a search string with a space or other non alphanumeric text this can break the <em>grep </em>command syntax, to create a search string containing these you need to use quotes to contain the string. In this step we are searching for “Steve ?” which is contained in the <em>test4 </em>file.</p><pre><code>grep “Steve ?” *</code></pre><h2>Searching Subdirectories with grep</h2><figure><div><p></p></div><figcaption>(Image credit: Tom's Hardware)</figcaption></figure><p>Like many Linux commands there are many useful additions and variants for the <em>grep </em>command. Let’s look at a couple of interesting examples.</p><p>1. <strong>Perform an inverted search using the </strong><em><strong>-v </strong></em><strong>argument. </strong>This will return a list of every line from the test environment files that doesn’t contain the search string <em>steve. </em>This argument is useful to dismiss occurrences of strings in logs or files when debugging an issue. Note that again the results are case sensitive and therefore they include the line containing the capitalized <em>Steve ? </em>from <em>test4.</em></p><pre><code>grep -v steve *</code></pre><p>2. <strong>Combine the </strong><em><strong>-v </strong></em><strong>and </strong><em><strong>-i </strong></em><strong>arguments to exclude all matching strings regardless of case.</strong></p><pre><code>grep -vi steve *</code></pre><p>3. <strong>Search for a string that contains non alphanumeric text or spaces. </strong>If you include a search string with a space or other non alphanumeric text this can break the <em>grep </em>command syntax, to create a search string containing these you need to use quotes to contain the string. In this step we are searching for “Steve ?” which is contained in the <em>test4 </em>file.</p><pre><code>grep “Steve ?” *</code></pre><h2>Searching Subdirectories with grep</h2><figure><div><p></p></div><figcaption>(Image credit: Tom's Hardware)</figcaption></figure><p>Often we will want to search for a string in the files contained in sub directories. We can do this simply by adding the <em>-r </em>recursive argument to the <em>grep </em>command.</p><p>1. <strong>Create a subdirectory containing a test file within the </strong><em><strong>test </strong></em><strong>directory.</strong></p><pre><code>mkdir sub_directory
cd sub_directory
touch test5</code></pre><p>2. <strong>Open test5 using the nano text editor </strong>and <strong>add the text “steve in a sub directory” to the file. Then press CTRL + X, then Y and Enter </strong>to save and exit.</p><pre><code>nano test5.</code></pre><p>3.<strong> Return to the </strong><em><strong>test </strong></em><strong>directory </strong>and <strong>perform a search adding the </strong><em><strong>-r </strong></em><strong>option. </strong>Notice that the result for <em>test5 </em>includes the location of the file listed in the output.</p><pre><code>cd ..
grep -r steve *</code></pre><figure><div><p></p></div><figcaption>(Image credit: Tom's Hardware)</figcaption></figure><p>With grep in Linux, you have a good collection of approaches for searching out file contents across your system. As with many Linux commands it can be worthwhile looking at the help menu to see all the varied arguments you can add to <em>grep</em>. Run <em>grep --h </em>in a terminal emulator to check out all the options.</p><p><strong>MORE:</strong> <a href="https://www.tomshardware.com/how-to/check-disk-usage-linux">How To Check Disk Usage in Linux</a></p><p><strong>MORE:</strong> <a href="https://www.tomshardware.com/how-to/kill-process-linux">How To Kill a Process in Linux</a></p><p><strong>MORE:</strong> <a href="https://www.tomshardware.com/how-to/find-files-linux">How To Find Files in Linux</a></p>
</div><div><section><p>Get instant access to breaking news, in-depth reviews and helpful tips.</p></section></div>||||I||||Skip to main content
 Open menu Close menu
 Tom's Hardware
 Search Search Tom's Hardware
 RSS
 (opens in new tab) (opens in new tab) (opens in new tab) (opens in new tab) (opens in new tab)
 US Edition

 * 
 * Reviews
 * Best Picks
 * Raspberry Pi
 * CPUs
 * GPUs
 * Coupons
 * More
 + Laptops
 + SSDs
 + Motherboards
 + Cooling
 + Desktops
 + PC Builds
 + Monitors
 + RAM
 + PC Cases
 + Keyboards
 + Headsets
 + Mice
 + Power Supplies
 + 3D Printers
 + VR Headsets
 + About Tom's Hardware
 Forums (opens in new tab)
 Trending
 * Core i5-13400
 * Ryzen 5 7600
 * RTX 4090 Ti / Titan RTX Ada
 * Raptor Lake
 * RX 7900 XTX

 When you purchase through links on our site, we may earn an affiliate commission. Here’s how it works.

 1. Home
 2. How-to

 How to Use the Grep Command in Linux to Search Inside Files

 By Jo Hinchliffe
 published 7 May 2022

 Use grep to search smarter in the Linux terminal

 * (opens in new tab)
 * (opens in new tab)
 * 
 * (opens in new tab)
 * (opens in new tab)
 * (opens in new tab)
 * 
 Comments (0)
 (Image credit: Tom's Hardware)

 You’re looking for that one file, the one that contains the all important information for your next meeting. Do you manually search all of your files? That will take time. Instead we use a little Linux command line magic. Grep is a pattern matching command that we can use to search inside files and directories for specific text. Grep is commonly used with the output of one command, piped to be the input of the grep command. For example we can search inside a file for a specific string of text using the less command, and pipe the output to grep.

 In this how-to we will use the grep command and commonly added arguments to search for specific strings of data within files. We’ll begin by setting up a small directory of test files as searching an entire filesystem can take some time and create a lot of results.

 All the commands in this how-to will work on most Linux machines. We’ve used a Ubuntu 20.04 install but you could run this how-to on a Raspberry Pi. All of the how-to is performed via the Terminal. You can open a terminal window on most Linux machines by pressing ctrl, alt and t.

 Set Up a Test Environment for grep

 (Image credit: Tom's Hardware)

 As grep can be used in lots of different ways we need to set up a directory and some content that allow us to explore its uses. In this section we will create this test environment.

 1. Set up a test directory and change directory so that you are inside it.

 mkdir test
 cd test

 2.Create 4 files, test1, test2, test3 and test4.

 touch test1 test2 test3 test4
 ls

 3. Edit test1 using nano to contain the following names on separate lines. Note that in test1 none of the names contain capitals. After editing in nano press control x to exit, press y to confirm the save and then press enter.

 nano test1

 4. Add the following text to the file. Then press CTRL + X, then Y and Enter to save and exit.

 ali
 mohamed
 claire
 aled
 steve

 5. Edit test2 using nano. In test2 we will add a single longer line of test containing the name steve.

 nano test2

 6. Add the following text to the file. Then press CTRL + X, then Y and Enter to save and exit.

 this is a long line of test that contains the name steve

 7. Edit test3 in nano. Similar to test1 we will add a list of names on separate lines but this list will include the name steven.

 nano test3

 8. Add the following text to the file. Then press CTRL + X, then Y and Enter to save and exit.

 alice
 geoff
 murbarak
 mohamed
 steven

 9. Finally edit test4 to complete our test environment. Note that in this file we are using a capital letter at the start of Steve.

 nano test4

 10. Add the following text to the file. Then press CTRL + X, then Y and Enter to save and exit.

 Steve ?

 Simple Searches with grep

 (Image credit: Tom's Hardware)

 Searching a file for a specific string is extremely useful. For example when debugging an error in a log file. Let’s start using grep in its most basic form.
 The grep command syntax is simply grep followed by any arguments, then the string we wish to search for and then finally the location in which to search.

 1. Search test1 for the string steve using grep. The search criteria is case sensitive so ensure that you're searching correctly. Notice that the word steve is simply returned in red to indicate it has been found in the file.

 grep steve test1

 2. Search for the same string in multiple files. We can simply add a list of files to the grep command for it to search. Notice that, with multiple search areas, the returned results are tagged with each filename from which the result is found. Also notice that grep returns the complete line of text that contains the searched string.

 grep steve test1 test2

 3. Search all files within the directory. Adding an asterisk forces grep to search all files within the current directory. Notice that the returned results include the result from test3 where the search string steve is contained within Steven. Note also that these results don’t contain the result from test4 as in its basic form the grep command is case sensitive.

 grep steve *

 4. Add the argument -i to make grep case insensitive. This will return results from all four of the test files in the directory.

 grep -i steve *

 Piping output to grep

 The strongest use case for grep is when it is paired with another command. Using pipes we send the output of a command to grep and use it to search for patterns / keywords.

 1. Open a new terminal window.

 2. Use lsusb to list all of the USB devices attached to your machine. This will also list internal USB devices, such as laptop webcams. The output will differ depending on your machine, but you should be met with a wall of text.

 lsusb

 (Image credit: Tom's Hardware)

 3. Use the lsusb command again, but this time use grep to search for Linux. By adding a pipe between lsusb and grep the output of the first command is used as the input of the second.

 lsusb | grep Linux

 (Image credit: Tom's Hardware)

 Using dmesg and grep to Inspect the Kernel Ring Buffer

 Let's try something a little more complex. This time we’ll use dmesg and grep to inspect the Kernel Ring Buffer (essentially the kernel’s log file). We are going to search for a keyword in dmesg, “secureboot”, and confirm that it is enabled.

 1. Open a terminal and run the dmesg command as sudo. This will print a wall of console output to the terminal, something that we can search using grep.

 sudo dmesg

 (Image credit: Tom's Hardware)

 2. Use the grep command to search for “secureboot” in the dmesg output. Use the -i argument to turn off case-sensitivity so that we catch every occurrence of secureboot. The output will show the lines at which secureboot appears in dmesg.

 sudo dmesg | less | grep -i secureboot

 (Image credit: Tom's Hardware)

 Other Uses of grep

 (Image credit: Tom's Hardware)

 Like many Linux commands there are many useful additions and variants for the grep command. Let’s look at a couple of interesting examples.

 1. Perform an inverted search using the -v argument. This will return a list of every line from the test environment files that doesn’t contain the search string steve. This argument is useful to dismiss occurrences of strings in logs or files when debugging an issue. Note that again the results are case sensitive and therefore they include the line containing the capitalized Steve ? from test4.

 grep -v steve *

 2. Combine the -v and -i arguments to exclude all matching strings regardless of case.

 grep -vi steve *

 3. Search for a string that contains non alphanumeric text or spaces. If you include a search string with a space or other non alphanumeric text this can break the grep command syntax, to create a search string containing these you need to use quotes to contain the string. In this step we are searching for “Steve ?” which is contained in the test4 file.

 grep “Steve ?” *

 Searching Subdirectories with grep

 (Image credit: Tom's Hardware)

 Like many Linux commands there are many useful additions and variants for the grep command. Let’s look at a couple of interesting examples.

 1. Perform an inverted search using the -v argument. This will return a list of every line from the test environment files that doesn’t contain the search string steve. This argument is useful to dismiss occurrences of strings in logs or files when debugging an issue. Note that again the results are case sensitive and therefore they include the line containing the capitalized Steve ? from test4.

 grep -v steve *

 2. Combine the -v and -i arguments to exclude all matching strings regardless of case.

 grep -vi steve *

 3. Search for a string that contains non alphanumeric text or spaces. If you include a search string with a space or other non alphanumeric text this can break the grep command syntax, to create a search string containing these you need to use quotes to contain the string. In this step we are searching for “Steve ?” which is contained in the test4 file.

 grep “Steve ?” *

 Searching Subdirectories with grep

 (Image credit: Tom's Hardware)

 Often we will want to search for a string in the files contained in sub directories. We can do this simply by adding the -r recursive argument to the grep command.

 1. Create a subdirectory containing a test file within the test directory.

 mkdir sub_directory
 cd sub_directory
 touch test5

 2. Open test5 using the nano text editor and add the text “steve in a sub directory” to the file. Then press CTRL + X, then Y and Enter to save and exit.

 nano test5.

 3. Return to the test directory and perform a search adding the -r option. Notice that the result for test5 includes the location of the file listed in the output.

 cd ..
 grep -r steve *

 (Image credit: Tom's Hardware)

 With grep in Linux, you have a good collection of approaches for searching out file contents across your system. As with many Linux commands it can be worthwhile looking at the help menu to see all the varied arguments you can add to grep. Run grep --h in a terminal emulator to check out all the options.

 MORE: How To Check Disk Usage in Linux

 MORE: How To Kill a Process in Linux

 MORE: How To Find Files in Linux

 Be In the Know

 Get instant access to breaking news, in-depth reviews and helpful tips.

 Contact me with news and offers from other Future brandsReceive email from us on behalf of our trusted partners or sponsors
 By submitting your information you agree to the Terms & Conditions (opens in new tab) and Privacy Policy (opens in new tab) and are aged 16 or over.

 Jo Hinchliffe

 Jo Hinchliffe is a UK-based freelance writer for Tom's Hardware US. His writing is focused on tutorials for the Linux command line.

 Topics
 Linux
 Operating Systems
 See all comments (0)
 No comments yet Comment from the forums
 MOST POPULARMOST SHARED
 1. 1
 Make a Windows 11 Image That Runs on 2GB of RAM With Tiny11 Builder
 2. 2
 Intel vs AMD: Which CPUs Are Better in 2023?
 3. 3
 Ryzen 9 7950X3D Beats Intel Flagship By 11% In Leaked Gaming Benchmarks
 4. 4
 Microsoft Admits Pushing Windows 11 Upgrade Offers to Ineligible PCs
 5. 5
 Minecraft RTX GPUs Benchmarked: Which Runs It Best in 2023?
 1. 1
 Make a Windows 11 Image That Runs on 2GB of RAM With Tiny11 Builder
 2. 2
 Intel vs AMD: Which CPUs Are Better in 2023?
 3. 3
 Ryzen 9 7950X3D Beats Intel Flagship By 11% In Leaked Gaming Benchmarks
 4. 4
 Microsoft Admits Pushing Windows 11 Upgrade Offers to Ineligible PCs
 5. 5
 Minecraft RTX GPUs Benchmarked: Which Runs It Best in 2023?

 Tom's Hardware is part of Future US Inc, an international media group and leading digital publisher. Visit our corporate site (opens in new tab) .

 * Terms and conditions (opens in new tab)
 * Privacy policy (opens in new tab)
 * Cookies policy (opens in new tab)
 * Accessibility Statement (opens in new tab)
 * Advertise (opens in new tab)
 * About us (opens in new tab)
 * Coupons (opens in new tab)
 * Careers (opens in new tab)

 © Future US, Inc. Full 7th Floor, 130 West 42nd Street, New York, NY 10036.

You’re looking for that one file, the one that contains the all important information for your next meeting. Do you manually search all of your files? That will take time. Instead we use a little Linux command line magic. Grep is a pattern matching command that we can use to search inside files and directories for specific text. Grep is commonly used with the output of one command, piped to be the input of the grep command. For example we can search inside a file for a specific string of text using the less command, and pipe the output to grep. In this how-to we will use the grep command and commonly added arguments to search for specific strings of data within files. We’ll begin by setting up a small directory of test files as searching an entire filesystem can take some time and create a lot of results. All the commands in this how-to will work on most Linux machines. We’ve used a Ubuntu 20.04 install but you could run this how-to on a Raspberry Pi . All of the how-to is performed via the Terminal. You can open a terminal window on most Linux machines by pressing ctrl, alt and t.  Set Up a Test Environment for grep       (Image credit: Tom's Hardware)  As grep can be used in lots of different ways we need to set up a directory and some content that allow us to explore its uses. In this section we will create this test environment. 1. Set up a   test   directory and change directory so that you are inside it.   mkdir test
cd test  2.Create 4 files, test1, test2, test3 and test4.   touch test1 test2 test3 test4
ls  3. Edit   test1   using   nano   to contain the following names on separate lines. Note that in test1 none of the names contain capitals. After editing in nano press control x to exit, press y to confirm the save and then press enter.  nano test1  4. Add the following text to the file. Then press CTRL + X, then Y and Enter to save and exit.   ali
mohamed
claire
aled
steve  5. Edit   test2   using   nano.  In test2 we will add a single longer line of test containing the name steve.  nano test2  6. Add the following text to the file. Then press CTRL + X, then Y and Enter to save and exit.   this is a long line of test that contains the name steve  7. Edit   test3   in   nano.  Similar to test1 we will add a list of names on separate lines but this list will include the name steven.   nano test3  8. Add the following text to the file. Then press CTRL + X, then Y and Enter to save and exit.   alice
geoff
murbarak
mohamed
steven  9. Finally edit   test4   to complete our test environment. Note that in this file we are using a capital letter at the start of Steve.   nano test4  10. Add the following text to the file. Then press CTRL + X, then Y and Enter to save and exit.   Steve ?  Simple Searches with grep       (Image credit: Tom's Hardware)  Searching a file for a specific string is extremely useful. For example when debugging an error in a log file. Let’s start using grep in its most basic form. 
The grep command syntax is simply grep followed by any arguments, then the string we wish to search for and then finally the location in which to search. 1. Search   test1   for the string   steve   using grep. The search criteria is case sensitive so ensure that you're searching correctly. Notice that the word steve is simply returned in red to indicate it has been found in the file.  grep steve test1  2. Search for the same string in multiple files. We can simply add a list of files to the grep command for it to search. Notice that, with multiple search areas, the returned results are tagged with each filename from which the result is found. Also notice that grep returns the complete line of text that contains the searched string.  grep steve test1 test2  3. Search all files within the directory. Adding an asterisk forces grep to search all files within the current directory. Notice that the returned results include the result from test3 where the search string steve is contained within Steven. Note also that these results don’t contain the result from test4 as in its basic form the grep command is case sensitive.  grep steve *  4. Add the argument   -i   to make   grep   case insensitive. This will return results from all four of the test files in the directory.  grep -i steve *  Piping output to grep The strongest use case for grep is when it is paired with another command. Using pipes we send the output of a command to grep and use it to search for patterns / keywords. 1. Open a new terminal window.  2. Use   lsusb   to list all of the USB devices attached to your machine. This will also list internal USB devices, such as laptop webcams. The output will differ depending on your machine, but you should be met with a wall of text.  lsusb       (Image credit: Tom's Hardware)  3. Use the   lsusb   command again, but this time use   grep   to search for Linux. By adding a pipe between lsusb and grep the output of the first command is used as the input of the second.  lsusb | grep Linux       (Image credit: Tom's Hardware)  Using dmesg and grep to Inspect the Kernel Ring Buffer Let's try something a little more complex. This time we’ll use dmesg and grep to inspect the Kernel Ring Buffer (essentially the kernel’s log file). We are going to search for a keyword in dmesg, “secureboot”, and confirm that it is enabled. 1. Open a terminal and run the dmesg command as sudo. This will print a wall of console output to the terminal, something that we can search using grep.  sudo dmesg       (Image credit: Tom's Hardware)  2. Use the   grep   command to search for “secureboot” in the   dmesg   output. Use the   -i   argument to turn off case-sensitivity so that we catch every occurrence of secureboot. The output will show the lines at which secureboot appears in dmesg.  sudo dmesg | less | grep -i secureboot       (Image credit: Tom's Hardware)  Other Uses of grep       (Image credit: Tom's Hardware)  Like many Linux commands there are many useful additions and variants for the grep command. Let’s look at a couple of interesting examples. 1. Perform an inverted search using the   -v   argument. This will return a list of every line from the test environment files that doesn’t contain the search string steve. This argument is useful to dismiss occurrences of strings in logs or files when debugging an issue. Note that again the results are case sensitive and therefore they include the line containing the capitalized Steve ? from test4.   grep -v steve *  2. Combine the   -v   and   -i   arguments to exclude all matching strings regardless of case.   grep -vi steve *  3. Search for a string that contains non alphanumeric text or spaces. If you include a search string with a space or other non alphanumeric text this can break the grep command syntax, to create a search string containing these you need to use quotes to contain the string. In this step we are searching for “Steve ?” which is contained in the test4 file.  grep “Steve ?” *  Searching Subdirectories with grep      (Image credit: Tom's Hardware)  Like many Linux commands there are many useful additions and variants for the grep command. Let’s look at a couple of interesting examples. 1. Perform an inverted search using the   -v   argument. This will return a list of every line from the test environment files that doesn’t contain the search string steve. This argument is useful to dismiss occurrences of strings in logs or files when debugging an issue. Note that again the results are case sensitive and therefore they include the line containing the capitalized Steve ? from test4.   grep -v steve *  2. Combine the   -v   and   -i   arguments to exclude all matching strings regardless of case.   grep -vi steve *  3. Search for a string that contains non alphanumeric text or spaces. If you include a search string with a space or other non alphanumeric text this can break the grep command syntax, to create a search string containing these you need to use quotes to contain the string. In this step we are searching for “Steve ?” which is contained in the test4 file.  grep “Steve ?” *  Searching Subdirectories with grep      (Image credit: Tom's Hardware)  Often we will want to search for a string in the files contained in sub directories. We can do this simply by adding the -r recursive argument to the grep command. 1. Create a subdirectory containing a test file within the   test   directory.   mkdir sub_directory
cd sub_directory
touch test5  2. Open test5 using the nano text editor and add the text “steve in a sub directory” to the file. Then press CTRL + X, then Y and Enter to save and exit.  nano test5.  3. Return to the   test   directory and perform a search adding the   -r   option. Notice that the result for test5 includes the location of the file listed in the output.  cd ..
grep -r steve *       (Image credit: Tom's Hardware)  With grep in Linux, you have a good collection of approaches for searching out file contents across your system. As with many Linux commands it can be worthwhile looking at the help menu to see all the varied arguments you can add to grep. Run grep --h in a terminal emulator to check out all the options.  MORE: How To Check Disk Usage in Linux   MORE: How To Kill a Process in Linux   MORE: How To Find Files in Linux 
   Get instant access to breaking news, in-depth reviews and helpful tips.
How to Use the Grep Command in Linux to Search Inside Files
https://www.tomshardware.com/how-to/grep-command-linux
https://github.com/toshi-search/Toshi
GitHub - toshi-search/Toshi: A full-text search engine in rust
2021-06-30
Toshi-Search
<div><div>
 <article><h2>Toshi</h2>
<h5>A Full-Text Search Engine in Rust</h5>
<p><a href="https://opensource.org/licenses/MIT"></a>
<a href="https://app.codacy.com/app/shcarman/Toshi?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=toshi-search/Toshi&amp;utm_campaign=Badge_Grade_Settings"></a>
<a href="https://github.com/toshi-search/toshi/actions"></a>
<a href="https://codecov.io/gh/toshi-search/Toshi"></a>
<a href="https://gitter.im/toshi-search/Toshi?utm_source=badge&amp;utm_medium=badge&amp;utm_campaign=pr-badge&amp;utm_content=badge"></a>
<a href="https://deps.rs/repo/github/toshi-search/toshi"></a></p>
<blockquote>
<p><em>Please note that this is far from production ready, also Toshi is still under active development, I'm just slow.</em></p>
</blockquote>
<h4>Description</h4>
<p>Toshi is meant to be a full-text search engine similar to Elasticsearch. Toshi strives
to be to Elasticsearch what <a href="https://github.com/tantivy-search/tantivy">Tantivy</a> is to Lucene.</p>
<h4>Motivations</h4>
<p>Toshi will always target stable Rust and will try our best to never make any use of unsafe Rust. While underlying libraries may make some
use of unsafe, Toshi will make a concerted effort to vet these libraries in an effort to be completely free of unsafe Rust usage. The
reason I chose this was because I felt that for this to actually become an attractive option for people to consider it would have to have
be safe, stable and consistent. This was why stable Rust was chosen because of the guarantees and safety it provides. I did not want to go down the rabbit hole of using nightly features to then have issues with their stability later on. Since Toshi is not
meant to be a library, I'm perfectly fine with having this requirement because people who would want to use this more than likely will
take it off the shelf and not modify it. My motivation was to cater to that use case when building Toshi.</p>
<h4>Build Requirements</h4>
<p>At this current time Toshi should build and work fine on Windows, Mac OS X, and Linux. From dependency requirements you are going to need 1.39.0 and Cargo installed in order to build. You can get rust easily from
<a href="https://rustup.rs/">rustup</a>.</p>
<h4>Configuration</h4>
<p>There is a default configuration file in config/config.toml:</p>
<div><pre>host = "127.0.0.1"
port = 8080
path = "data2/"
writer_memory = 200000000
log_level = "info"
json_parsing_threads = 4
bulk_buffer_size = 10000
auto_commit_duration = 10
experimental = false
[experimental_features]
master = true
nodes = [
 "127.0.0.1:8081"
]
[merge_policy]
kind = "log"
min_merge_size = 8
min_layer_size = 10_000
level_log_size = 0.75</pre></div>
<h5>Host</h5>
<p><code>host = "localhost"</code></p>
<p>The hostname Toshi will bind to upon start.</p>
<h5>Port</h5>
<p><code>port = 8080</code></p>
<p>The port Toshi will bind to upon start.</p>
<h5>Path</h5>
<p><code>path = "data/"</code></p>
<p>The data path where Toshi will store its data and indices.</p>
<h5>Writer Memory</h5>
<p><code>writer_memory = 200000000</code></p>
<p>The amount of memory (in bytes) Toshi should allocate to commits for new documents.</p>
<h5>Log Level</h5>
<p><code>log_level = "info"</code></p>
<p>The detail level to use for Toshi's logging.</p>
<h5>Json Parsing</h5>
<p><code>json_parsing_threads = 4</code></p>
<p>When Toshi does a bulk ingest of documents it will spin up a number of threads to parse the document's json as it's
received. This controls the number of threads spawned to handle this job.</p>
<h5>Bulk Buffer</h5>
<p><code>bulk_buffer_size = 10000</code></p>
<p>This will control the buffer size for parsing documents into an index. It will control the amount of memory a bulk ingest will
take up by blocking when the message buffer is filled. If you want to go totally off the rails you can set this to 0 in order to make the buffer unbounded.</p>
<h5>Auto Commit Duration</h5>
<p><code>auto_commit_duration = 10</code></p>
<p>This controls how often an index will automatically commit documents if there are docs to be committed. Set this to 0 to disable this feature, but you will have to do commits yourself when you submit documents.</p>
<h5>Merge Policy</h5>
<div><pre>[merge_policy]
kind = "log"</pre></div>
<p>Tantivy will merge index segments according to the configuration outlined here. There are 2 options for this. "log" which is the default
segment merge behavior. Log has 3 additional values to it as well. Any of these 3 values can be omitted to use Tantivy's default value.
The default values are listed below.</p>
<div><pre>min_merge_size = 8
min_layer_size = 10_000
level_log_size = 0.75</pre></div>
<p>In addition there is the "nomerge" option, in which Tantivy will do no merging of segments.</p>
<h5>Experimental Settings</h5>
<div><pre>experimental = false
[experimental_features]
master = true
nodes = [
 "127.0.0.1:8081"
]</pre></div>
<p>In general these settings aren't ready for usage yet as they are very unstable or flat out broken. Right now the distribution of Toshi
is behind this flag, so if experimental is set to false then all these settings are ignored.</p>
<h4>Building and Running</h4>
<p>Toshi can be built using <code>cargo build --release</code>. Once Toshi is built you can run <code>./target/release/toshi</code> from the top level directory to start Toshi according to the configuration in config/config.toml</p>
<p>You should get a startup message like this.</p>
<div><pre> ______ __ _ ____ __
 /_ __/__ ___ / / (_) / __/__ ___ _________/ /
 / / / _ \(_-&lt;/ _ \/ / _\ \/ -_) _ `/ __/ __/ _ \
 /_/ \___/___/_//_/_/ /___/\__/\_,_/_/ \__/_//_/
 Such Relevance, Much Index, Many Search, Wow
 
 INFO toshi::index &gt; Indexes: []</pre></div>
<p>You can verify Toshi is running with:</p>
<div><pre>curl -X GET http://localhost:8080/</pre></div>
<p>which should return:</p>
<div><pre>{
 "name": "Toshi Search",
 "version": "0.1.1"
}</pre></div>
<p>Once toshi is running it's best to check the <code>requests.http</code> file in the root of this project to see some more examples of usage.</p>
<h4>Example Queries</h4>
<h5>Term Query</h5>
<div><pre>{ "query": {"term": {"test_text": "document" } }, "limit": 10 }</pre></div>
<h5>Fuzzy Term Query</h5>
<div><pre>{ "query": {"fuzzy": {"test_text": {"value": "document", "distance": 0, "transposition": false } } }, "limit": 10 }</pre></div>
<h5>Phrase Query</h5>
<div><pre>{ "query": {"phrase": {"test_text": {"terms": ["test","document"] } } }, "limit": 10 }</pre></div>
<h5>Range Query</h5>
<div><pre>{ "query": {"range": { "test_i64": { "gte": 2012, "lte": 2015 } } }, "limit": 10 }</pre></div>
<h5>Regex Query</h5>
<div><pre>{ "query": {"regex": { "test_text": "d[ou]{1}c[k]?ument" } }, "limit": 10 }</pre></div>
<h5>Boolean Query</h5>
<div><pre>{ "query": {"bool": {"must": [ { "term": { "test_text": "document" } } ], "must_not": [ {"range": {"test_i64": { "gt": 2017 } } } ] } }, "limit": 10 }</pre></div>
<h5>Usage</h5>
<p>To try any of the above queries you can use the above example</p>
<div><pre>curl -X POST http://localhost:8080/test_index -H 'Content-Type: application/json' -d '{ "query": {"term": {"test_text": "document" } }, "limit": 10 }'</pre></div>
<p>Also, to note, limit is optional, 10 is the default value. It's only included here for completeness.</p>
<h4>Running Tests</h4>
<p><code>cargo test</code></p>
<h4>What is a Toshi?</h4>
<p>Toshi is a three year old Shiba Inu. He is a very good boy and is the official mascot of this project. Toshi personally reviews all code before it is committed to this repository and is dedicated to only accepting the highest quality contributions from his human. He will, though, accept treats for easier code reviews.</p>
</article>
 </div>||||I|||| Skip to content
 Toggle navigation
 Sign up
 * Product
 + Actions
 Automate any workflow
 + Packages
 Host and manage packages
 + Security
 Find and fix vulnerabilities
 + Codespaces
 Instant dev environments
 + Copilot
 Write better code with AI
 + Code review
 Manage code changes
 + Issues
 Plan and track work
 + Discussions
 Collaborate outside of code
 + Explore
 + All features
 + Documentation
 + GitHub Skills
 + Blog
 * Solutions
 + For
 + Enterprise
 + Teams
 + Startups
 + Education
 + By Solution
 + CI/CD & Automation
 + DevOps
 + DevSecOps
 + Case Studies
 + Customer Stories
 + Resources
 * Open Source
 + GitHub Sponsors
 Fund open source developers
 + The ReadME Project
 GitHub community articles
 + Repositories
 + Topics
 + Trending
 + Collections
 * Pricing
 * In this repository All GitHub ↵
 Jump to ↵
 * No suggested jump to results
 * In this repository All GitHub ↵
 Jump to ↵
 * In this organization All GitHub ↵
 Jump to ↵
 * In this repository All GitHub ↵
 Jump to ↵
 Sign in
 Sign up
 {{ message }}
 toshi-search / Toshi Public
 * 
 * Notifications
 * Fork 122
 * Star 3.8k

 A full-text search engine in rust

 License

 MIT license
 3.8k stars 122 forks
 Star
 Notifications
 * Code
 * Issues 13
 * Pull requests 6
 * Actions
 * Projects 1
 * Security
 * Insights
 More
 * Code
 * Issues
 * Pull requests
 * Actions
 * Projects
 * Security
 * Insights

 toshi-search/Toshi

 This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
 master
 Switch branches/tags
 Branches Tags
 Could not load branches
 Nothing to show
 {{ refName }} default
 View all branches
 Could not load tags
 Nothing to show
 {{ refName }} default
 View all tags

 Name already in use

 A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
 Cancel Create
 9 branches 0 tags
 Code
 * Local
 * Codespaces
 * Clone
 HTTPS GitHub CLI

 Use Git or checkout with SVN using the web URL.

 Work fast with our official CLI. Learn more.

 * Open with GitHub Desktop
 * Download ZIP

 Sign In Required

 Please sign in to use Codespaces.

 Launching GitHub Desktop

 If nothing happens, download GitHub Desktop and try again.

 Launching GitHub Desktop

 If nothing happens, download GitHub Desktop and try again.

 Launching Xcode

 If nothing happens, download Xcode and try again.

 Launching Visual Studio Code

 Your codespace will open once ready.

 There was a problem preparing your codespace, please try again.

 Latest commit

 Git stats

 * 446 commits

 Files

 Permalink
 Failed to load latest commit information.
 Type
 Name
 Latest commit message
 Commit time
 .github
 Update CI/CD
 June 30, 2021 14:07
 ci
 More inflight
 January 20, 2021 11:48
 config
 Fix various little bugs in platform specific code, added a list endpo…
 June 6, 2021 11:54
 docs
 More inflight
 January 20, 2021 11:48
 toshi-client
 Update deps, fix some lints
 January 4, 2023 09:29
 toshi-proto
 Fix an issue with bulk insert and having very long lines, the maximum…
 November 25, 2021 10:55
 toshi-raft
 Bump prost from 0.7.0 to 0.8.0 (#805)
 September 6, 2021 22:57
 toshi-server
 Update deps, fix some lints
 January 4, 2023 09:29
 toshi-types
 Update deps, fix some lints
 January 4, 2023 09:29
 .gitignore
 More inflight
 January 20, 2021 11:48
 Cargo.lock
 Merge branch 'master' of https://github.com/toshi-search/Toshi
 January 4, 2023 09:30
 Cargo.toml
 Fix some lints
 September 8, 2021 13:21
 LICENSE
 More inflight
 January 20, 2021 11:48
 README.md
 even more dep updates
 February 20, 2021 13:37
 SECURITY.md
 Create SECURITY.md
 July 1, 2021 01:49
 codecov.yml
 More inflight
 January 20, 2021 11:48
 doc.json
 More inflight
 January 20, 2021 11:48
 requests.http
 Fix various little bugs in platform specific code, added a list endpo…
 June 6, 2021 11:54
 rustfmt.toml
 Fix an issue with bulk insert and having very long lines, the maximum…
 November 25, 2021 10:55
 schema.json
 More inflight
 January 20, 2021 11:48
 View code
 Toshi A Full-Text Search Engine in Rust Description Motivations Build Requirements Configuration Host Port Path Writer Memory Log Level Json Parsing Bulk Buffer Auto Commit Duration Merge Policy Experimental Settings Building and Running Example Queries Term Query Fuzzy Term Query Phrase Query Range Query Regex Query Boolean Query Usage Running Tests What is a Toshi?

 README.md

 Toshi

 A Full-Text Search Engine in Rust

 Please note that this is far from production ready, also Toshi is still under active development, I'm just slow.

 Description

 Toshi is meant to be a full-text search engine similar to Elasticsearch. Toshi strives to be to Elasticsearch what Tantivy is to Lucene.

 Motivations

 Toshi will always target stable Rust and will try our best to never make any use of unsafe Rust. While underlying libraries may make some use of unsafe, Toshi will make a concerted effort to vet these libraries in an effort to be completely free of unsafe Rust usage. The reason I chose this was because I felt that for this to actually become an attractive option for people to consider it would have to have be safe, stable and consistent. This was why stable Rust was chosen because of the guarantees and safety it provides. I did not want to go down the rabbit hole of using nightly features to then have issues with their stability later on. Since Toshi is not meant to be a library, I'm perfectly fine with having this requirement because people who would want to use this more than likely will take it off the shelf and not modify it. My motivation was to cater to that use case when building Toshi.

 Build Requirements

 At this current time Toshi should build and work fine on Windows, Mac OS X, and Linux. From dependency requirements you are going to need 1.39.0 and Cargo installed in order to build. You can get rust easily from rustup.

 Configuration

 There is a default configuration file in config/config.toml:

 host = "127.0.0.1"
 port = 8080
 path = "data2/"
 writer_memory = 200000000
 log_level = "info"
 json_parsing_threads = 4
 bulk_buffer_size = 10000
 auto_commit_duration = 10
 experimental = false
 
 [experimental_features]
 master = true
 nodes = [
 "127.0.0.1:8081"
 ]
 
 [merge_policy]
 kind = "log"
 min_merge_size = 8
 min_layer_size = 10_000
 level_log_size = 0.75

 Host

 host = "localhost"

 The hostname Toshi will bind to upon start.

 Port

 port = 8080

 The port Toshi will bind to upon start.

 Path

 path = "data/"

 The data path where Toshi will store its data and indices.

 Writer Memory

 writer_memory = 200000000

 The amount of memory (in bytes) Toshi should allocate to commits for new documents.

 Log Level

 log_level = "info"

 The detail level to use for Toshi's logging.

 Json Parsing

 json_parsing_threads = 4

 When Toshi does a bulk ingest of documents it will spin up a number of threads to parse the document's json as it's received. This controls the number of threads spawned to handle this job.

 Bulk Buffer

 bulk_buffer_size = 10000

 This will control the buffer size for parsing documents into an index. It will control the amount of memory a bulk ingest will take up by blocking when the message buffer is filled. If you want to go totally off the rails you can set this to 0 in order to make the buffer unbounded.

 Auto Commit Duration

 auto_commit_duration = 10

 This controls how often an index will automatically commit documents if there are docs to be committed. Set this to 0 to disable this feature, but you will have to do commits yourself when you submit documents.

 Merge Policy

 [merge_policy]
 kind = "log"

 Tantivy will merge index segments according to the configuration outlined here. There are 2 options for this. "log" which is the default segment merge behavior. Log has 3 additional values to it as well. Any of these 3 values can be omitted to use Tantivy's default value. The default values are listed below.

 min_merge_size = 8
 min_layer_size = 10_000
 level_log_size = 0.75

 In addition there is the "nomerge" option, in which Tantivy will do no merging of segments.

 Experimental Settings

 experimental = false
 
 [experimental_features]
 master = true
 nodes = [
 "127.0.0.1:8081"
 ]

 In general these settings aren't ready for usage yet as they are very unstable or flat out broken. Right now the distribution of Toshi is behind this flag, so if experimental is set to false then all these settings are ignored.

 Building and Running

 Toshi can be built using cargo build --release. Once Toshi is built you can run ./target/release/toshi from the top level directory to start Toshi according to the configuration in config/config.toml

 You should get a startup message like this.

 ______ __ _ ____ __
 /_ __/__ ___ / / (_) / __/__ ___ _________/ /
 / / / _ \(_-</ _ \/ / _\ \/ -_) _ `/ __/ __/ _ \
 /_/ \___/___/_//_/_/ /___/\__/\_,_/_/ \__/_//_/
 Such Relevance, Much Index, Many Search, Wow
 
 INFO toshi::index > Indexes: []

 You can verify Toshi is running with:

 curl -X GET http://localhost:8080/

 which should return:

 {
 "name": "Toshi Search",
 "version": "0.1.1"
 }

 Once toshi is running it's best to check the requests.http file in the root of this project to see some more examples of usage.

 Example Queries

 Term Query

 { "query": {"term": {"test_text": "document" } }, "limit": 10 }

 Fuzzy Term Query

 { "query": {"fuzzy": {"test_text": {"value": "document", "distance": 0, "transposition": false } } }, "limit": 10 }

 Phrase Query

 { "query": {"phrase": {"test_text": {"terms": ["test","document"] } } }, "limit": 10 }

 Range Query

 { "query": {"range": { "test_i64": { "gte": 2012, "lte": 2015 } } }, "limit": 10 }

 Regex Query

 { "query": {"regex": { "test_text": "d[ou]{1}c[k]?ument" } }, "limit": 10 }

 Boolean Query

 { "query": {"bool": {"must": [ { "term": { "test_text": "document" } } ], "must_not": [ {"range": {"test_i64": { "gt": 2017 } } } ] } }, "limit": 10 }

 Usage

 To try any of the above queries you can use the above example

 curl -X POST http://localhost:8080/test_index -H 'Content-Type: application/json' -d '{ "query": {"term": {"test_text": "document" } }, "limit": 10 }'

 Also, to note, limit is optional, 10 is the default value. It's only included here for completeness.

 Running Tests

 cargo test

 What is a Toshi?

 Toshi is a three year old Shiba Inu. He is a very good boy and is the official mascot of this project. Toshi personally reviews all code before it is committed to this repository and is dedicated to only accepting the highest quality contributions from his human. He will, though, accept treats for easier code reviews.

 About

 A full-text search engine in rust

 Topics

 search rust search-engine elasticsearch indexing rust-lang

 Resources

 Readme

 License

 MIT license

 Security policy

 Security policy

 Stars

 3.8k stars

 Watchers

 57 watching

 Forks

 122 forks

 Releases

 No releases published

 Sponsor this project

 Sponsor
 Learn more about GitHub Sponsors

 Packages 0

 No packages published

 Contributors 18

 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 + 7 contributors

 Languages

 * Rust 99.3%
 * Shell 0.7%

 Footer

 © 2023 GitHub, Inc.

 Footer navigation

 * Terms
 * Privacy
 * Security
 * Status
 * Docs
 * Contact GitHub
 * Pricing
 * API
 * Training
 * Blog
 * About
 You can’t perform that action at this time.
 You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Toshi
A Full-Text Search Engine in Rust
  
 
 
 
 
  
 Please note that this is far from production ready, also Toshi is still under active development, I'm just slow. 
Description
Toshi is meant to be a full-text search engine similar to Elasticsearch. Toshi strives
to be to Elasticsearch what Tantivy is to Lucene.
Motivations
Toshi will always target stable Rust and will try our best to never make any use of unsafe Rust. While underlying libraries may make some
use of unsafe, Toshi will make a concerted effort to vet these libraries in an effort to be completely free of unsafe Rust usage. The
reason I chose this was because I felt that for this to actually become an attractive option for people to consider it would have to have
be safe, stable and consistent. This was why stable Rust was chosen because of the guarantees and safety it provides. I did not want to go down the rabbit hole of using nightly features to then have issues with their stability later on. Since Toshi is not
meant to be a library, I'm perfectly fine with having this requirement because people who would want to use this more than likely will
take it off the shelf and not modify it. My motivation was to cater to that use case when building Toshi.
Build Requirements
At this current time Toshi should build and work fine on Windows, Mac OS X, and Linux. From dependency requirements you are going to need 1.39.0 and Cargo installed in order to build. You can get rust easily from
rustup.
Configuration
There is a default configuration file in config/config.toml:
 host = "127.0.0.1"
port = 8080
path = "data2/"
writer_memory = 200000000
log_level = "info"
json_parsing_threads = 4
bulk_buffer_size = 10000
auto_commit_duration = 10
experimental = false
[experimental_features]
master = true
nodes = [
 "127.0.0.1:8081"
]
[merge_policy]
kind = "log"
min_merge_size = 8
min_layer_size = 10_000
level_log_size = 0.75 
Host
 host = "localhost" 
The hostname Toshi will bind to upon start.
Port
 port = 8080 
The port Toshi will bind to upon start.
Path
 path = "data/" 
The data path where Toshi will store its data and indices.
Writer Memory
 writer_memory = 200000000 
The amount of memory (in bytes) Toshi should allocate to commits for new documents.
Log Level
 log_level = "info" 
The detail level to use for Toshi's logging.
Json Parsing
 json_parsing_threads = 4 
When Toshi does a bulk ingest of documents it will spin up a number of threads to parse the document's json as it's
received. This controls the number of threads spawned to handle this job.
Bulk Buffer
 bulk_buffer_size = 10000 
This will control the buffer size for parsing documents into an index. It will control the amount of memory a bulk ingest will
take up by blocking when the message buffer is filled. If you want to go totally off the rails you can set this to 0 in order to make the buffer unbounded.
Auto Commit Duration
 auto_commit_duration = 10 
This controls how often an index will automatically commit documents if there are docs to be committed. Set this to 0 to disable this feature, but you will have to do commits yourself when you submit documents.
Merge Policy
 [merge_policy]
kind = "log" 
Tantivy will merge index segments according to the configuration outlined here. There are 2 options for this. "log" which is the default
segment merge behavior. Log has 3 additional values to it as well. Any of these 3 values can be omitted to use Tantivy's default value.
The default values are listed below.
 min_merge_size = 8
min_layer_size = 10_000
level_log_size = 0.75 
In addition there is the "nomerge" option, in which Tantivy will do no merging of segments.
Experimental Settings
 experimental = false
[experimental_features]
master = true
nodes = [
 "127.0.0.1:8081"
] 
In general these settings aren't ready for usage yet as they are very unstable or flat out broken. Right now the distribution of Toshi
is behind this flag, so if experimental is set to false then all these settings are ignored.
Building and Running
Toshi can be built using cargo build --release. Once Toshi is built you can run ./target/release/toshi from the top level directory to start Toshi according to the configuration in config/config.toml
You should get a startup message like this.
  ______ __ _ ____ __
 /_ __/__ ___ / / (_) / __/__ ___ _________/ /
 / / / _ \(_-&lt;/ _ \/ / _\ \/ -_) _ `/ __/ __/ _ \
 /_/ \___/___/_//_/_/ /___/\__/\_,_/_/ \__/_//_/
 Such Relevance, Much Index, Many Search, Wow
 
 INFO toshi::index &gt; Indexes: [] 
You can verify Toshi is running with:
 curl -X GET http://localhost:8080/ 
which should return:
 {
 "name": "Toshi Search",
 "version": "0.1.1"
} 
Once toshi is running it's best to check the requests.http file in the root of this project to see some more examples of usage.
Example Queries
Term Query
 { "query": {"term": {"test_text": "document" } }, "limit": 10 } 
Fuzzy Term Query
 { "query": {"fuzzy": {"test_text": {"value": "document", "distance": 0, "transposition": false } } }, "limit": 10 } 
Phrase Query
 { "query": {"phrase": {"test_text": {"terms": ["test","document"] } } }, "limit": 10 } 
Range Query
 { "query": {"range": { "test_i64": { "gte": 2012, "lte": 2015 } } }, "limit": 10 } 
Regex Query
 { "query": {"regex": { "test_text": "d[ou]{1}c[k]?ument" } }, "limit": 10 } 
Boolean Query
 { "query": {"bool": {"must": [ { "term": { "test_text": "document" } } ], "must_not": [ {"range": {"test_i64": { "gt": 2017 } } } ] } }, "limit": 10 } 
Usage
To try any of the above queries you can use the above example
 curl -X POST http://localhost:8080/test_index -H 'Content-Type: application/json' -d '{ "query": {"term": {"test_text": "document" } }, "limit": 10 }' 
Also, to note, limit is optional, 10 is the default value. It's only included here for completeness.
Running Tests
 cargo test 
What is a Toshi?
Toshi is a three year old Shiba Inu. He is a very good boy and is the official mascot of this project. Toshi personally reviews all code before it is committed to this repository and is dedicated to only accepting the highest quality contributions from his human. He will, though, accept treats for easier code reviews.
GitHub - toshi-search/Toshi: A full-text search engine in rust
https://github.com/toshi-search/Toshi
https://rust.extension.sh/
Rust Search Extension: The ultimate search extension for Rust
None
None
<div><div>
 
 <p>Overview</p>
 
<p>You can press <code>space</code> after the keyword, then increase or decrease the number of <strong>-</strong> (hyphen) to page down or page up.</p>
<h2>Search docs</h2>
<p>We support search all kinds of Rust docs blaze-fastly. Those docs including:</p>
<ul>
<li>The <strong>stable</strong>/<strong>nightly</strong> documentation of official crates (including <strong>std</strong>, <strong>proc_macro</strong>, <strong>test</strong>).</li>
<li>All external docs on <a href="https://docs.rs/">docs.rs</a>.</li>
<li>All <strong>rustc</strong> crates docs.</li>
</ul>
<blockquote>
<p>We'll sync the latest <strong>std</strong>/<strong>nightly</strong> search index automatically every day to ensure the docs freshness.
There is no extension updating required to get the latest search index since v1.0.</p>
</blockquote>
<h2>Search Primitive Types and Modules</h2>
<p></p>
<h2>Search Structs, Traits and Enums</h2>
<p></p>
<h2>Search Functions, Methods and Macros</h2>
<p></p>
<h2>Search nightly docs</h2>
<p>You can prefix a <strong>/</strong> (slash) before the keyword to search nightly docs. </p>
<h2>Search rustc docs</h2>
<p>You can prefix a <strong>//</strong> (double slash) before the keyword to search all of 
crates <a href="https://doc.rust-lang.org/nightly/nightly-rustc/">docs of <strong>rustc</strong></a>, 
such as <em>rustc_mir</em>, <em>rustc_hir</em>, or <em>rustc_ast</em>, etc.</p>
<blockquote>
<p>It makes no sense to have a built-in search-index of <strong>rustc</strong> since the <strong>rustc</strong> is changed 
very frequently. Therefore, you need to open the <strong>rustc</strong> docs page in advance to sync the 
search-index before you search <strong>rustc</strong> docs. However, the search-index of <strong>rustc</strong> is very big, 
we never persist it to the local storage (due to the limited storage size available 
to browser extension).</p>
</blockquote>
<p></p>
<h2>Search with type mode</h2>
<p>You can prefix a type to get the exclusive search result. Those type keywords including:</p>
<ul>
<li><strong>mod</strong></li>
<li><strong>struct</strong></li>
<li><strong>enum</strong></li>
<li><strong>fn</strong></li>
<li><strong>trait</strong></li>
<li><strong>type</strong></li>
<li><strong>macro</strong></li>
<li><strong>const</strong></li>
</ul>
<p>For example, <code>fn:asref</code> to search function or <code>trait:iterator</code> to search trait.</p>
<p></p>
<h2>Source code mode</h2>
<p>Since <strong>v1.2</strong>, we can straight open the source code page for our docs search result.
Simply prefix <code>src:</code> (or <code>s:</code>, an alias to <code>src:</code>) before the keyword, you'll be 
redirected to the correct source code line of your search result after you press <code>Enter</code>.
For example, input <code>src:try_fold</code> or <code>s:try_fold</code>, you'll open the source code line of <code>std::iter::Iterator::try_fold()</code>. </p>
<h2>Offline mode: search local Rust docs</h2>
<p>You can run command <code>rustup doc --std</code> to open the offline std docs. 
To enable the offline mode, you should check the checkbox and input the offline docs path on the settings page. 
However, please check the <a href="/faq/#caveats">Caveats</a> if you are a Firefox user.</p>
<p></p>
<h2>Search external crate docs</h2>
<p>After you <a href="/#add-your-favorite-crate-to-extension">add the crate to extension</a>, you can prefix <strong>@crate-name</strong> to search
the docs exclusive to that crate. For example, input <code>@tokio spawn</code> to search docs of <strong>tokio</strong>. </p>
<p></p>
<p><strong>~</strong> is another pretty prefix to search the external crate docs. Unlike the <strong>@</strong> prefix, <strong>~</strong>
gives you the power to search docs across all your favorite crates effortlessly. </p>
<p>For example, input <code>~spawn</code>, you can get results related to "spawn" from all your favorite crates 
(e.g. <strong>tokio</strong>, <strong>async_std</strong>, <strong>smol</strong>, and <strong>futures</strong> ). </p>
<p></p>
<h2>Search builtin attributes</h2>
<p>Search builtin attributes (such as <code>derive</code>, <code>non_exhaustive</code>) are also supported, 
by default, the result is mixed with other related docs or crates though. </p>
<p>If you prefer to search attribute exclusively, prefix a <strong>#</strong> (pound sign) before the keyword to narrow the result.</p>
<p></p>
<h2>Search top 20K crates</h2>
<p>We build top 20K crates index once a day to help you search crates instantly. 
You can prefix an <strong>!</strong> (exclamation mark) before the keyword to search <a href="https://docs.rs/">docs.rs</a> exclusively, 
prefix one more <strong>!</strong> (double exclamation marks) to open <a href="https://crates.io/">crates.io</a> page,
prefix <strong>!!!</strong> (triple exclamation marks) to open crate's repository (See <a href="/#open-repository-quickly">Open repository quickly</a>).</p>
<p></p>
<h2>Search compiler error code</h2>
<p></p>
<h2>Search Rust book chapters</h2>
<p>You can search all of Rust book chapters too! The result will show the title of the related page, 
parent chapter, and grandparent chapter. Don't forget the <strong>%</strong> is the prefix to perform the book searching.</p>
<p></p>
<h2>Search Cargo Clippy lints</h2>
<p><strong>&gt;</strong> (right angle bracket) is also a great prefix to help you search <a href="https://rust-lang.github.io/rust-clippy/master/">Cargo Clippy lints</a> exclusively. </p>
<p></p>
<h2>Search Caniuse.rs</h2>
<p>You can search <a href="https://caniuse.rs/">caniuse.rs</a> with <strong>?</strong> prefix.</p>
<p></p>
<h2>Search Rust Version</h2>
<p>Just input any Rust version (such as <code>1.38</code> or <code>v1.38</code>) to open the release page of that version.</p>
<p></p>
<h2>Commands system</h2>
<p>The command system brings a handy set of useful and convenient commands to you. 
Each command starts with a <strong>:</strong> (colon), followed by the name, and function differently in individual.
Those commands including but not limited to:</p>
<ul>
<li><strong>:help</strong> - Show the help messages. </li>
<li><strong>:blog</strong> - Search Rust release blog posts.</li>
<li><strong>:cargo</strong> - Search useful third-party cargo subcommands. </li>
<li><strong>:yet</strong> - Search Are We Yet websites. </li>
<li><strong>:book</strong> - Search Rust books.</li>
<li><strong>:book/zh</strong> - Search Chinese Rust books.</li>
<li><strong>:stable</strong> - Show stable Rust scheduled release date. </li>
<li><strong>:label</strong> - Search issue labels of rust-lang repository. </li>
<li><strong>:tool</strong> - Show useful rust tools.</li>
<li><strong>:mirror</strong> - Search Rust mirror websites.</li>
<li><strong>:stats</strong> - Open search statistics page.</li>
<li><strong>:update</strong> - Open the <a href="/update">update page</a> to sync the latest index automatically.</li>
<li><strong>:release</strong> - Open rust-lang repository <a href="https://github.com/rust-lang/rust/blob/master/RELEASES.md">release page</a>.</li>
<li><strong>:rfc</strong> - Search Rust RFCs.</li>
<li><strong>:rustc</strong> - Search rustc codegen options and lints.</li>
<li><strong>:target</strong> - Search rust target for three tiers.</li>
<li><strong>:history</strong> - Show your local search history.</li>
</ul>
<p></p>
<h2>Rust docs enhancement</h2>
<h2>Make all "since" and "issue" linkable</h2>
<p>Two kinds of tags links to corresponding urls, including:</p>
<ul>
<li><strong>"since"</strong> links to Github release page (works in docs page and source code page)</li>
<li><strong>"issue"</strong> links to Github issue (works in source code page)</li>
</ul>
<p></p>
<h2>Docs.rs enhancement</h2>
<h2>Display Feature Flags</h2>
<p>Docs.rs don't display the crate's feature flags, which is inconvenient. So Rust Search Extension fills the gap.</p>
<p></p>
<p>Also, we support optional dependencies.</p>
<h2>Add your favorite crate to extension</h2>
<p>By clicking the <code>+ to Rust Search Extension</code> button, you can add the crate to the extension, which brings the 
search capability for this crate on the address bar.</p>
<h2>Show Table of Content</h2>
<p></p>
<h2>Rust repository enhancement</h2>
<h2>Show Table of Content in the release page</h2>
<p></p>
<h2>Searching statistics</h2>
<p>Searching statistics page provides a set of useful charts to visualize your search history. This gives you a 
powerful insight view on how frequency you search, how much valuable time you saved.</p>
<p>These charts including:</p>
<ul>
<li>A calendar heatmap represents your searching history in the last year</li>
<li>A percentage chart reflects each category weight you searched</li>
<li>Weekly, daily, and hourly bar chart tells you searching frequency in different time dimensionality</li>
<li>Top searched crates chart gives you the rank of personal crate searching</li>
</ul>
<p>
</p>
<h2>Miscellaneous</h2>
<h2>Manage your indexed crates</h2>
<p></p>
<h2>Import/Export your data</h2>
<p></p>
<h2>Customize crates searching platform</h2>
<p>You can customize your preferred crates searching platform such as <a href="https://crates.io/">crates.io</a>(default) 
or <a href="https://lib.rs/">lib.rs</a> on the settings page.</p>
<h2>Open repository quickly</h2>
<p>You can prefix <strong>!!!</strong> (triple !) to open crate's repository quickly. 
For example, input <code>!!!tokio</code> then enter, the extension will obtain the repository url then redirect to 
the github repository page of <strong>tokio</strong> effortlessly.</p>
 
 </div>||||I|||| Rust Search Extension
Testimonial FAQ Changelog Privacy Github

 The ultimate search extension for Rust

 Search docs, crates, builtin attributes, official books, and error codes, etc in your address bar instantly. Input keyword rs then press Space to get started. Just that easy!

 Current version 1.9.1 Install to Chrome Install to Firefox Install to Edge
 Explore More ⇩
 Pagination
 Search docs
 - Search Primitive Types and Modules
 - Search Structs, Traits and Enums
 - Search Functions, Methods and Macros
 - Search nightly docs
 - Search rustc docs
 - Search with type mode
 - Source code mode
 - Offline mode: search local Rust docs
 - Search external crate docs
 Search builtin attributes
 Search top 20K crates
 Search compiler error code
 Search Rust book chapters
 Search Cargo Clippy lints
 Search Caniuse.rs
 Search Rust Version
 Commands system
 Rust docs enhancement
 - Make all "since" and "issue" linkable
 Docs.rs enhancement
 - Display Feature Flags
 - Add your favorite crate to extension
 - Show Table of Content
 Rust repository enhancement
 - Show Table of Content in the release page
 Searching statistics
 Miscellaneous
 - Manage your indexed crates
 - Import/Export your data
 - Customize crates searching platform
 - Open repository quickly
 Overview

 Pagination

 You can press space after the keyword, then increase or decrease the number of - (hyphen) to page down or page up.

 Search docs

 We support search all kinds of Rust docs blaze-fastly. Those docs including:

 * The stable/nightly documentation of official crates (including std, proc_macro, test).
 * All external docs on docs.rs.
 * All rustc crates docs.

 We'll sync the latest std/nightly search index automatically every day to ensure the docs freshness. There is no extension updating required to get the latest search index since v1.0.

 Search Primitive Types and Modules

 Search Structs, Traits and Enums

 Search Functions, Methods and Macros

 Search nightly docs

 You can prefix a / (slash) before the keyword to search nightly docs.

 Search rustc docs

 You can prefix a // (double slash) before the keyword to search all of crates docs of rustc, such as rustc_mir, rustc_hir, or rustc_ast, etc.

 It makes no sense to have a built-in search-index of rustc since the rustc is changed very frequently. Therefore, you need to open the rustc docs page in advance to sync the search-index before you search rustc docs. However, the search-index of rustc is very big, we never persist it to the local storage (due to the limited storage size available to browser extension).

 Search with type mode

 You can prefix a type to get the exclusive search result. Those type keywords including:

 * mod
 * struct
 * enum
 * fn
 * trait
 * type
 * macro
 * const

 For example, fn:asref to search function or trait:iterator to search trait.

 Source code mode

 Since v1.2, we can straight open the source code page for our docs search result. Simply prefix src: (or s:, an alias to src:) before the keyword, you'll be redirected to the correct source code line of your search result after you press Enter. For example, input src:try_fold or s:try_fold, you'll open the source code line of std::iter::Iterator::try_fold().

 Offline mode: search local Rust docs

 You can run command rustup doc --std to open the offline std docs. To enable the offline mode, you should check the checkbox and input the offline docs path on the settings page. However, please check the Caveats if you are a Firefox user.

 Search external crate docs

 After you add the crate to extension, you can prefix @crate-name to search the docs exclusive to that crate. For example, input @tokio spawn to search docs of tokio.

 ~ is another pretty prefix to search the external crate docs. Unlike the @ prefix, ~ gives you the power to search docs across all your favorite crates effortlessly.

 For example, input ~spawn, you can get results related to "spawn" from all your favorite crates (e.g. tokio, async_std, smol, and futures ).

 Search builtin attributes

 Search builtin attributes (such as derive, non_exhaustive) are also supported, by default, the result is mixed with other related docs or crates though.

 If you prefer to search attribute exclusively, prefix a # (pound sign) before the keyword to narrow the result.

 Search top 20K crates

 We build top 20K crates index once a day to help you search crates instantly. You can prefix an ! (exclamation mark) before the keyword to search docs.rs exclusively, prefix one more ! (double exclamation marks) to open crates.io page, prefix !!! (triple exclamation marks) to open crate's repository (See Open repository quickly).

 Search compiler error code

 Search Rust book chapters

 You can search all of Rust book chapters too! The result will show the title of the related page, parent chapter, and grandparent chapter. Don't forget the % is the prefix to perform the book searching.

 Search Cargo Clippy lints

 > (right angle bracket) is also a great prefix to help you search Cargo Clippy lints exclusively.

 Search Caniuse.rs

 You can search caniuse.rs with ? prefix.

 Search Rust Version

 Just input any Rust version (such as 1.38 or v1.38) to open the release page of that version.

 Commands system

 The command system brings a handy set of useful and convenient commands to you. Each command starts with a : (colon), followed by the name, and function differently in individual. Those commands including but not limited to:

 * :help - Show the help messages.
 * :blog - Search Rust release blog posts.
 * :cargo - Search useful third-party cargo subcommands.
 * :yet - Search Are We Yet websites.
 * :book - Search Rust books.
 * :book/zh - Search Chinese Rust books.
 * :stable - Show stable Rust scheduled release date.
 * :label - Search issue labels of rust-lang repository.
 * :tool - Show useful rust tools.
 * :mirror - Search Rust mirror websites.
 * :stats - Open search statistics page.
 * :update - Open the update page to sync the latest index automatically.
 * :release - Open rust-lang repository release page.
 * :rfc - Search Rust RFCs.
 * :rustc - Search rustc codegen options and lints.
 * :target - Search rust target for three tiers.
 * :history - Show your local search history.

 Rust docs enhancement

 Make all "since" and "issue" linkable

 Two kinds of tags links to corresponding urls, including:

 * "since" links to Github release page (works in docs page and source code page)
 * "issue" links to Github issue (works in source code page)

 Docs.rs enhancement

 Display Feature Flags

 Docs.rs don't display the crate's feature flags, which is inconvenient. So Rust Search Extension fills the gap.

 Also, we support optional dependencies.

 Add your favorite crate to extension

 By clicking the + to Rust Search Extension button, you can add the crate to the extension, which brings the search capability for this crate on the address bar.

 Show Table of Content

 Rust repository enhancement

 Show Table of Content in the release page

 Searching statistics

 Searching statistics page provides a set of useful charts to visualize your search history. This gives you a powerful insight view on how frequency you search, how much valuable time you saved.

 These charts including:

 * A calendar heatmap represents your searching history in the last year
 * A percentage chart reflects each category weight you searched
 * Weekly, daily, and hourly bar chart tells you searching frequency in different time dimensionality
 * Top searched crates chart gives you the rank of personal crate searching

 Miscellaneous

 Manage your indexed crates

 Import/Export your data

 Customize crates searching platform

 You can customize your preferred crates searching platform such as crates.io(default) or lib.rs on the settings page.

 Open repository quickly

 You can prefix !!! (triple !) to open crate's repository quickly. For example, input !!!tokio then enter, the extension will obtain the repository url then redirect to the github repository page of tokio effortlessly.

Overview
 
You can press space after the keyword, then increase or decrease the number of - (hyphen) to page down or page up.
Search docs
We support search all kinds of Rust docs blaze-fastly. Those docs including:
The stable/nightly documentation of official crates (including std, proc_macro, test).
All external docs on docs.rs.
All rustc crates docs.
We'll sync the latest std/nightly search index automatically every day to ensure the docs freshness.
There is no extension updating required to get the latest search index since v1.0.
Search Primitive Types and Modules
 
Search Structs, Traits and Enums
 
Search Functions, Methods and Macros
 
Search nightly docs
You can prefix a / (slash) before the keyword to search nightly docs. 
Search rustc docs
You can prefix a // (double slash) before the keyword to search all of 
crates docs of rustc , 
such as rustc_mir, rustc_hir, or rustc_ast, etc.
It makes no sense to have a built-in search-index of rustc since the rustc is changed 
very frequently. Therefore, you need to open the rustc docs page in advance to sync the 
search-index before you search rustc docs. However, the search-index of rustc is very big, 
we never persist it to the local storage (due to the limited storage size available 
to browser extension).
 
Search with type mode
You can prefix a type to get the exclusive search result. Those type keywords including:
 mod 
 struct 
 enum 
 fn 
 trait 
 type 
 macro 
 const 
For example, fn:asref to search function or trait:iterator to search trait.
 
Source code mode
Since v1.2, we can straight open the source code page for our docs search result.
Simply prefix src: (or s:, an alias to src:) before the keyword, you'll be 
redirected to the correct source code line of your search result after you press Enter.
For example, input src:try_fold or s:try_fold, you'll open the source code line of std::iter::Iterator::try_fold(). 
Offline mode: search local Rust docs
You can run command rustup doc --std to open the offline std docs. 
To enable the offline mode, you should check the checkbox and input the offline docs path on the settings page. 
However, please check the Caveats if you are a Firefox user.
 
Search external crate docs
After you add the crate to extension, you can prefix @crate-name to search
the docs exclusive to that crate. For example, input @tokio spawn to search docs of tokio. 
 
 ~ is another pretty prefix to search the external crate docs. Unlike the @ prefix, ~
gives you the power to search docs across all your favorite crates effortlessly. 
For example, input ~spawn, you can get results related to "spawn" from all your favorite crates 
(e.g. tokio, async_std, smol, and futures ). 
 
Search builtin attributes
Search builtin attributes (such as derive, non_exhaustive) are also supported, 
by default, the result is mixed with other related docs or crates though. 
If you prefer to search attribute exclusively, prefix a # (pound sign) before the keyword to narrow the result.
 
Search top 20K crates
We build top 20K crates index once a day to help you search crates instantly. 
You can prefix an ! (exclamation mark) before the keyword to search docs.rs exclusively, 
prefix one more ! (double exclamation marks) to open crates.io page,
prefix !!! (triple exclamation marks) to open crate's repository (See Open repository quickly).
 
Search compiler error code
 
Search Rust book chapters
You can search all of Rust book chapters too! The result will show the title of the related page, 
parent chapter, and grandparent chapter. Don't forget the % is the prefix to perform the book searching.
 
Search Cargo Clippy lints
 &gt; (right angle bracket) is also a great prefix to help you search Cargo Clippy lints exclusively. 
 
Search Caniuse.rs
You can search caniuse.rs with ? prefix.
 
Search Rust Version
Just input any Rust version (such as 1.38 or v1.38) to open the release page of that version.
 
Commands system
The command system brings a handy set of useful and convenient commands to you. 
Each command starts with a : (colon), followed by the name, and function differently in individual.
Those commands including but not limited to:
 :help - Show the help messages. 
 :blog - Search Rust release blog posts.
 :cargo - Search useful third-party cargo subcommands. 
 :yet - Search Are We Yet websites. 
 :book - Search Rust books.
 :book/zh - Search Chinese Rust books.
 :stable - Show stable Rust scheduled release date. 
 :label - Search issue labels of rust-lang repository. 
 :tool - Show useful rust tools.
 :mirror - Search Rust mirror websites.
 :stats - Open search statistics page.
 :update - Open the update page to sync the latest index automatically.
 :release - Open rust-lang repository release page.
 :rfc - Search Rust RFCs.
 :rustc - Search rustc codegen options and lints.
 :target - Search rust target for three tiers.
 :history - Show your local search history.
 
Rust docs enhancement
Make all "since" and "issue" linkable
Two kinds of tags links to corresponding urls, including:
 "since" links to Github release page (works in docs page and source code page)
 "issue" links to Github issue (works in source code page)
 
Docs.rs enhancement
Display Feature Flags
Docs.rs don't display the crate's feature flags, which is inconvenient. So Rust Search Extension fills the gap.
 
Also, we support optional dependencies.
Add your favorite crate to extension
By clicking the + to Rust Search Extension button, you can add the crate to the extension, which brings the 
search capability for this crate on the address bar.
Show Table of Content
 
Rust repository enhancement
Show Table of Content in the release page
 
Searching statistics
Searching statistics page provides a set of useful charts to visualize your search history. This gives you a 
powerful insight view on how frequency you search, how much valuable time you saved.
These charts including:
A calendar heatmap represents your searching history in the last year
A percentage chart reflects each category weight you searched
Weekly, daily, and hourly bar chart tells you searching frequency in different time dimensionality
Top searched crates chart gives you the rank of personal crate searching
Miscellaneous
Manage your indexed crates
 
Import/Export your data
 
Customize crates searching platform
You can customize your preferred crates searching platform such as crates.io(default) 
or lib.rs on the settings page.
Open repository quickly
You can prefix !!! (triple !) to open crate's repository quickly. 
For example, input !!!tokio then enter, the extension will obtain the repository url then redirect to 
the github repository page of tokio effortlessly.
Rust Search Extension: The ultimate search extension for Rust
https://rust.extension.sh/