Codakey
Play
← Back to ggreer/the_silver_searcher

How to Deploy & Use ggreer/the_silver_searcher

The Silver Searcher - Deploy/Usage Guide

Prerequisites

Runtime Dependencies

  • PCRE library (Perl Compatible Regular Expressions) - required for regex matching
  • LZMA library - required for compressed file support
  • Zlib - required for compressed file support

Build Dependencies

  • Automake - build system
  • pkg-config - dependency management
  • C compiler (gcc, clang, or equivalent)

Platform-Specific Notes

  • macOS: Xcode command line tools recommended
  • Linux: Development tools group/package
  • Windows: MSYS2 or Cygwin environment recommended for building from source

Installation

Package Manager Installation (Recommended)

macOS

# Homebrew
brew install the_silver_searcher

# MacPorts
port install the_silver_searcher

Linux

# Ubuntu/Debian
apt-get install silversearcher-ag

# Fedora
dnf install the_silver_searcher

# CentOS/RHEL
yum install epel-release.noarch the_silver_searcher

# Gentoo
emerge -a sys-apps/the_silver_searcher

# Arch Linux
pacman -S the_silver_searcher

# openSUSE
zypper install the_silver_searcher

BSD

# FreeBSD
pkg install the_silver_searcher

# OpenBSD/NetBSD
pkg_add the_silver_searcher

Windows

# Chocolatey
choco install ag

# Winget
winget install "The Silver Searcher"

# MSYS2
pacman -S mingw-w64-{i686,x86_64}-ag

Building from Source

  1. Install build dependencies
# 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 zlib-devel

# openSUSE
zypper source-install --build-deps-only the_silver_searcher
  1. Clone and build
git clone https://github.com/ggreer/the_silver_searcher.git
cd the_silver_searcher
./build.sh
sudo make install
  1. Windows build (MSYS2/MinGW)
make -f Makefile.w32

Configuration

Environment Variables

  • No specific environment variables required for basic operation

Configuration Files

  • .gitignore - automatically respected for ignored patterns
  • .hgignore - automatically respected for ignored patterns
  • .ignore - custom ignore patterns (supports glob patterns)

Custom Ignore Patterns

Create a .ignore file in your project root:

*.min.js
*.map
node_modules/

Performance Tuning

  • No runtime configuration needed - performance is built-in
  • Uses all available CPU cores by default via pthreads

Build & Run

Basic Usage

# Search for pattern in current directory
ag "search_pattern"

# Search in specific directory
ag "search_pattern" /path/to/directory

# Case-insensitive search
ag -i "search_pattern"

# Show line numbers
ag -n "search_pattern"

# Count matches only
ag -c "search_pattern"

Common Options

# Search hidden files
ag -u "pattern"

# Follow symlinks
ag -f "pattern"

# List filenames only
ag -l "pattern"

# Show file paths relative to search directory
ag -G "pattern"

Integration with Editors

  • Vim: Use with plugins like ack.vim (configure to use ag instead of ack)
  • Emacs: Use with ag.el package
  • VS Code: Use with search-ag extension

Deployment

Standalone Binary

The Silver Searcher is a command-line tool that doesn't require deployment - simply install on target machines.

Distribution

  • Package managers: Use system package managers for easy distribution
  • Binary distribution: Pre-built binaries available for Windows
  • Source distribution: Build from source for custom requirements

Platform Recommendations

  • Linux servers: Use system package managers
  • macOS development: Homebrew installation
  • Windows: Chocolatey or winget for easy installation
  • Cross-platform: Build from source for consistency

Troubleshooting

Common Issues

"Command not found" after installation

# Check installation path
which ag

# Verify installation
ag --version

# Reinstall if necessary
sudo make uninstall && sudo make install

Performance issues

# Ensure ag is using all cores
ag --version  # Check if built with pthread support

# Check for filesystem issues
df -h  # Ensure disk space
mount | grep -E "(nfs|sshfs)"  # Avoid network filesystems

Build failures

# Missing dependencies
./build.sh 2>&1 | grep -i "error:.*not found"

# Clean and rebuild
make clean
./build.sh

Regex pattern issues

# Test simple patterns first
ag "literal_string"

# Use -Q for literal matching (no regex)
ag -Q "pattern_with_special_chars"

# Check PCRE version
pcretest -C

Performance Tips

  • Avoid searching network-mounted directories
  • Use .ignore files to exclude large directories (node_modules, .git, etc.)
  • For very large codebases, consider breaking searches into smaller chunks

Version Compatibility

  • Requires PCRE >= 8.21 for JIT compilation
  • Built with default optimization flags for best performance
  • Compatible with POSIX-compliant systems

Getting Help

# Show all options
ag --help

# Check version and build info
ag --version

# Report issues
# https://github.com/ggreer/the_silver_searcher/issues
← Project overviewView alternatives to ggreer/the_silver_searcher →