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
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | f9cf3ea0f0f8606b689ebf5caab8771e97fa588de59e28ef3eb8d9f271c4955e |
|
MD5 | 94c89bbe3335ffbac26014e5db51b5a9 |
|
BLAKE2b-256 | 5d35204264f32c197ddb252453f3a7ac9d0dc42ae04a1a9f5ab18efec86b63c0 |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | b6d35a0ded9690624cc4c72d9e9f1926babfcea963901c4e0fc4693f1a88d758 |
|
MD5 | 9cc5ee76afdbab63a40f27a782770797 |
|
BLAKE2b-256 | 283d1fb9b0b8b7416301f9abf5e16717f12214d4781c8b1a7bca2cdb28d9873f |