Skip to main content

Github search from the cli

Project description

gh-search

Last release Python versions Unittests status

GitHub code search with full text regex filtering, from your cli.

Features

  • Filters search results (eg. ignore archived repositories or search for specific text in matched content)
  • Displays results grouped by organisation/repository
  • GitHub API rate limit aware (prevent accidentally consuming your entire core API quota)
  • Uses GitHub's Rest API (and therefore works with GitHub Enterprise)

Installation

gh-search is available as a python package via pypi.org and requires Python 3.12+

pipx install gh-search

Authentication

A valid GitHub personal access token, with the repo scope, is required to retrieve search results. It can be set on a GITHUB_TOKEN envvar or passed to the script via the --github-token option.

Enterprise

To search GitHub Enterprise set the GITHUB_API_URL envvar to your organisation's GitHub v3 API endpoint. eg. GITHUB_API_URL=https://github.mycompany.net/api/v3. You can also use the --github-api-url option for this.

Usage

Invoke with gh-search and pass a query string as the first argument. For example, to search for the word "usage" in this repo:

gh-search usage repo:janeklb/gh-search

Note that repo: is a search qualifier natively supported by the GitHub Search API. See GitHub's searching code documentation to see what other qualifiers are available.

Example: regex content filtering

If you are searching for a specific non-alphanumeric string you can use the --regex-content-filter (or --content-filter) options. This must be combined with a valid GitHub Search API query (which will produce the result set that will subsequently be filtered).

For example if you're looking for a special_var variable being set to a value of characters beginning with 10 you could do something like:

gh-search special_var -e "special_var\\s*=\\s*10"

All available options

Usage: gh-search [OPTIONS] QUERY...

  QUERY must contain at least one search term, but may also contain search qualifiers
  (https://docs.github.com/en/github/searching-for-information-on-github/searching-code)

Options:
  --github-token TEXT             GitHub Auth Token. Will fall back on GITHUB_TOKEN envvar.
  --github-api-url TEXT           Override default GitHub API URL. Can also specify via GITHUB_API_URL envvar.
  -p, --path-filter TEXT          Exclude results whose path (or part of path) does not match this.
  -c, --content-filter TEXT       Exclude results whose content does not match this.
  -e, --regex-content-filter TEXT
                                  Exclude results whose content does not match this regex.
  -a, --include-archived          Include results from archived repos.
  -l, --repos-with-matches        Only the names of repos are printed. Equivalent to --output=repo-list
  -o, --output TEXT               Output style; one of: default, repo-list, json, yaml
  -v, --verbose                   Verbose output.
  --help                          Show this message and exit.

Saving default configuration values to disk

Default values for options can specified via a config file. Location of this file is based on click.get_app_dir, with gh-search as the app_name (eg. ~/Library/Application\ Support/gh-search/config on MacOS). You'll see the exact file location printed out next to the help text of the --config of gh-search --help (or if you run with the --verbose flag).

The option names must be converted to snake_case as per click's parameter naming.

For example, in order set a default --github-token and --github-api-url you would write the following to your config file (replacing <PLACE HOLDERS> accordingly):

github_token="<YOUR TOKEN>"
github_api_url="<THE API URL>"

Rate Limiting

gh-search checks your rate limits and will prompt you to continue if your search might:

  • perform more than 500 core API requests
  • leave you with less than 10% of your core API quota

Only the core API quota is checked because gh-search's filters can make heavy use it. The search API quota is not checked.

Developing

  • make install-dev install dev dependencies (set up your own virtual environment first)
  • make unit run unit tests
  • make lint run linters

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gh_search-0.9.1.tar.gz (9.3 kB view details)

Uploaded Source

Built Distribution

gh_search-0.9.1-py3-none-any.whl (10.9 kB view details)

Uploaded Python 3

File details

Details for the file gh_search-0.9.1.tar.gz.

File metadata

  • Download URL: gh_search-0.9.1.tar.gz
  • Upload date:
  • Size: 9.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.4

File hashes

Hashes for gh_search-0.9.1.tar.gz
Algorithm Hash digest
SHA256 f9cf3ea0f0f8606b689ebf5caab8771e97fa588de59e28ef3eb8d9f271c4955e
MD5 94c89bbe3335ffbac26014e5db51b5a9
BLAKE2b-256 5d35204264f32c197ddb252453f3a7ac9d0dc42ae04a1a9f5ab18efec86b63c0

See more details on using hashes here.

File details

Details for the file gh_search-0.9.1-py3-none-any.whl.

File metadata

  • Download URL: gh_search-0.9.1-py3-none-any.whl
  • Upload date:
  • Size: 10.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.4

File hashes

Hashes for gh_search-0.9.1-py3-none-any.whl
Algorithm Hash digest
SHA256 b6d35a0ded9690624cc4c72d9e9f1926babfcea963901c4e0fc4693f1a88d758
MD5 9cc5ee76afdbab63a40f27a782770797
BLAKE2b-256 283d1fb9b0b8b7416301f9abf5e16717f12214d4781c8b1a7bca2cdb28d9873f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page