C Perl M4 Shell Perl 6 Makefile Python
Latest commit 1a5e259 Aug 25, 2017 @ggreer Bump version to v2.1.0
Permalink
Failed to load latest commit information.
doc Update docs to explain mmap defaults. Regenerate manpage. Dec 3, 2016
m4 Add pthread detection m4 macro. Jun 20, 2014
src Merge branch 'master' of https://github.com/stedolan/the_silver_searcher Aug 25, 2017
tests Merge branch 'master' of github.com:ggreer/the_silver_searcher Aug 25, 2017
.clang-format The ultimate clang-format styling directives to end all clang-format … Mar 29, 2015
.gitignore Add script for performance-guided optimization. Ignore pgo files. Jan 28, 2017
.travis.yml Travis CI doesn't seem to obey this directive, so remove it. Looks li… Jun 23, 2016
CONTRIBUTING.md Adding filetypes Apr 2, 2017
LICENSE Add license. Apache License 2.0 ftw. Dec 3, 2011
Makefile.am Fix #896 - Stream decompress zipped files Jun 17, 2017
Makefile.w32 Makefile.w32: Remove Perl-regex grep dependency Feb 17, 2016
NOTICE Update date in NOTICE Jun 23, 2016
README.md doc: Describe how to install on MSYS2 Jul 21, 2017
_the_silver_searcher add zsh completion function Sep 27, 2016
ag.bashcomp.sh remove shebang from bash completion script May 29, 2016
autogen.sh Create autogen.sh script Dec 11, 2016
build.sh Create autogen.sh script Dec 11, 2016
configure.ac Bump version to v2.1.0 Aug 25, 2017
format.sh Fix shellcheck warnings/errors in shell scripts. Feb 16, 2016
pgo.sh Add script for performance-guided optimization. Ignore pgo files. Jan 28, 2017
sanitize.sh Add script to automatically run tests with the LLVM sanitizers or val… Jun 4, 2017
the_silver_searcher.spec.in Update docs and help to refer to .ignore instead of .agignore. agigno… Sep 24, 2016

README.md

The Silver Searcher

A code searching tool similar to ack, with a focus on speed.

Build Status

Floobits Status

#ag on Freenode

Do you know C? Want to improve ag? I invite you to pair with me.

What's so great about Ag?

  • It is an order of magnitude faster than ack.
  • It ignores file patterns from your .gitignore and .hgignore.
  • If there are files in your source repo you don't want to search, just add their patterns to a .ignore file. (*cough* *.min.js *cough*)
  • The command name is 33% shorter than ack, and all keys are on the home row!

Ag is quite stable now. Most changes are new features, minor bug fixes, or performance improvements. It's much faster than Ack in my benchmarks:

ack test_blah ~/code/  104.66s user 4.82s system 99% cpu 1:50.03 total

ag test_blah ~/code/  4.67s user 4.58s system 286% cpu 3.227 total

Ack and Ag found the same results, but Ag was 34x faster (3.2 seconds vs 110 seconds). My ~/code directory is about 8GB. Thanks to git/hg/ignore, Ag only searched 700MB of that.

There are also graphs of performance across releases.

How is it so fast?

  • Ag uses Pthreads to take advantage of multiple CPU cores and search files in parallel.
  • Files are mmap()ed instead of read into a buffer.
  • Literal string searching uses Boyer-Moore strstr.
  • Regex searching uses PCRE's JIT compiler (if Ag is built with PCRE >=8.21).
  • Ag calls pcre_study() before executing the same regex on every file.
  • Instead of calling fnmatch() on every pattern in your ignore files, non-regex patterns are loaded into arrays and binary searched.

I've written several blog posts showing how I've improved performance. These include how I added pthreads, wrote my own scandir(), benchmarked every revision to find performance regressions, and profiled with gprof and Valgrind.

Installing

macOS

brew install the_silver_searcher

or

port install the_silver_searcher

Linux

  • Ubuntu >= 13.10 (Saucy) or Debian >= 8 (Jessie)

      apt-get install silversearcher-ag
    
  • Fedora 21 and lower

      yum install the_silver_searcher
    
  • Fedora 22+

      dnf install the_silver_searcher
    
  • RHEL7+

      yum install epel-release.noarch the_silver_searcher
    
  • Gentoo

      emerge -a sys-apps/the_silver_searcher
    
  • Arch

      pacman -S the_silver_searcher
    
  • Slackware

      sbopkg -i the_silver_searcher
    
  • openSUSE:

      zypper install the_silver_searcher
    
  • CentOS:

      yum install the_silver_searcher
    
  • SUSE Linux Enterprise: Follow these simple instructions.

BSD

  • FreeBSD

      pkg install the_silver_searcher
    
  • OpenBSD/NetBSD

      pkg_add the_silver_searcher
    

Windows

  • Win32/64

    Unofficial daily builds are available.

  • MSYS2

      pacman -S mingw-w64-{i686,x86_64}-ag
    
  • Cygwin

    Run the relevant setup-*.exe, and select "the_silver_searcher" in the "Utils" category.

Building from source

Building master

  1. Install dependencies (Automake, pkg-config, PCRE, LZMA):

    • macOS:

        brew install automake pkg-config pcre xz
      

      or

        port install automake pkgconfig pcre xz
      
    • Ubuntu/Debian:

        apt-get install -y automake pkg-config libpcre3-dev zlib1g-dev liblzma-dev
      
    • Fedora:

        yum -y install pkgconfig automake gcc zlib-devel pcre-devel xz-devel
      
    • CentOS:

        yum -y groupinstall "Development Tools"
        yum -y install pcre-devel xz-devel
      
    • openSUSE:

        zypper source-install --build-deps-only the_silver_searcher
      
    • Windows: It's complicated. See this wiki page.

  2. Run the build script (which just runs aclocal, automake, etc):

     ./build.sh
    

    On Windows (inside an msys/MinGW shell):

     make -f Makefile.w32
    
  3. Make install:

     sudo make install
    

Building a release tarball

GPG-signed releases are available here.

Building release tarballs requires the same dependencies, except for automake and pkg-config. Once you've installed the dependencies, just run:

./configure
make
make install

You may need to use sudo or run as root for the make install.

Editor Integration

Vim

You can use Ag with [ack.vim][] by adding the following line to your .vimrc:

let g:ackprg = 'ag --nogroup --nocolor --column'

or:

let g:ackprg = 'ag --vimgrep'

Which has the same effect but will report every match on the line.

Emacs

You can use ag.el as an Emacs front-end to Ag. See also: helm-ag.

TextMate

TextMate users can use Ag with my fork of the popular AckMate plugin, which lets you use both Ack and Ag for searching. If you already have AckMate you just want to replace Ack with Ag, move or delete "~/Library/Application Support/TextMate/PlugIns/AckMate.tmplugin/Contents/Resources/ackmate_ack" and run ln -s /usr/local/bin/ag "~/Library/Application Support/TextMate/PlugIns/AckMate.tmplugin/Contents/Resources/ackmate_ack"

Other stuff you might like

  • Ack - Better than grep. Without Ack, Ag would not exist.
  • ack.vim
  • Exuberant Ctags - Faster than Ag, but it builds an index beforehand. Good for really big codebases.
  • Git-grep - As fast as Ag but only works on git repos.
  • ripgrep
  • Sack - A utility that wraps Ack and Ag. It removes a lot of repetition from searching and opening matching files.