Git Text Finder CLI

A command-line tool to find text in Git repositories.

Features

• Clone Git repositories or use existing local copies
• Search for text within repository files
• Process multiple repositories from a file
• Support for specifying branch names (falls back to 'main' then 'master' if specified branch doesn't exist)
• Include only specific files in search using glob patterns (e.g., *.js, *.ts)
• Exclude files from search using glob patterns (e.g., *.xml, test/*)
• Clone repositories to a dedicated 'repositories' directory (automatically added to .gitignore)
• Output results to a formatted Markdown file or CSV file with sequence numbers
• Display results in a table format with sequence numbers in the terminal
• Verbose mode for detailed information about the search process

Installation

Local Installation

# Clone this repository
git clone <repository-url>
cd git-text-finder

# Install dependencies
npm install

# Link the package globally
npm link

Global Installation (once published)

npm install -g git-text-finder

Usage

# Using a single repository
git-text-finder --repo <repository-url> --search <text-to-search> [options]

# Using a file with multiple repositories
git-text-finder --file <path-to-repo-file> --search <text-to-search> [options]

Options

• -r, --repo <url>: Git repository URL

• -f, --file <path>: File containing repository URLs (one per line, with optional #branch)

• -b, --branch <name>: Default branch name (default: "main", falls back to 'main' then 'master' if specified branch doesn't exist)

• -s, --search <text...>: Text to search for (multiple terms can be provided, required)

• -o, --output <file>: Output file path (default: "search-results.md")

• --format <type>: Output format (markdown or csv, default: "markdown")

• -e, --exclude <patterns...>: File patterns to exclude (glob patterns supported, e.g., *.xml)

• -i, --include <patterns...>: File patterns to include (glob patterns supported, e.g., *.js, *.ts). If not specified, all files are included

• -v, --verbose: Enable verbose output (prints detailed information about files being searched)

• -h, --help: Display help information

• -V, --version: Display version information

Repository File Format

The repository file should contain one repository URL per line. You can optionally specify a branch name by appending #branch-name to the URL:

[email protected]:username/repo1.git
[email protected]:username/repo2.git#main
[email protected]:username/repo3.git#develop
https://github.com/username/repo4.git#feature/new-feature

If no branch is specified, the default branch (specified by --branch or "main" if not provided) will be used. If the specified branch doesn't exist, the tool will try to use 'main', then 'master'. If neither exists, an error will be reported.

Examples

# Search for "TODO" in a single repository
git-text-finder --repo https://github.com/username/repo.git --search "TODO"

# Search for multiple terms in a single repository
git-text-finder --repo https://github.com/username/repo.git --search "TODO" "FIXME" "BUG"

# Search in multiple repositories defined in a file
git-text-finder --file .repository --search "TODO"

# Search for multiple terms in multiple repositories
git-text-finder --file .repository --search "TODO" "FIXME" "BUG"

# Search in a specific branch and save results to a custom file
git-text-finder --repo https://github.com/username/repo.git --branch develop --search "FIXME" --output fixme-results.md

# Exclude specific file types from the search
git-text-finder --repo https://github.com/username/repo.git --search "TODO" --exclude "*.xml" "*.json" "test/*"

# Include only specific file types in the search
git-text-finder --repo https://github.com/username/repo.git --search "TODO" --include "*.js" "*.ts"

# Combine include and exclude patterns
git-text-finder --repo https://github.com/username/repo.git --search "TODO" --include "*.js" "*.ts" --exclude "test/*" "vendor/*"

# Enable verbose output to see detailed information about the search process
git-text-finder --repo https://github.com/username/repo.git --search "TODO" --verbose

# Output results in CSV format
git-text-finder --repo https://github.com/username/repo.git --search "TODO" --format csv

# Specify custom output file with CSV format
git-text-finder --repo https://github.com/username/repo.git --search "TODO" --format csv --output results.csv

Output

The tool can generate output in two formats:

Markdown Format (default)

When using the default markdown format, the tool generates a Markdown file with a table of results, including:

• Sequence number (#)
• Repository URL
• Branch name
• File path
• Line number
• Search term that matched
• Content of the line containing the search term

CSV Format

When using the CSV format (--format csv), the tool generates a CSV file with the same information, making it easy to import into spreadsheet applications or process with other tools.

License

ISC