Github search from the cli
Project description
gh-search
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 testsmake lint
run linters
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for gh_search-0.9.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b6d35a0ded9690624cc4c72d9e9f1926babfcea963901c4e0fc4693f1a88d758 |
|
MD5 | 9cc5ee76afdbab63a40f27a782770797 |
|
BLAKE2b-256 | 283d1fb9b0b8b7416301f9abf5e16717f12214d4781c8b1a7bca2cdb28d9873f |