{"id":13621615,"url":"https://github.com/janeklb/gh-search","last_synced_at":"2025-05-01T14:33:03.837Z","repository":{"id":44568034,"uuid":"328812136","full_name":"janeklb/gh-search","owner":"janeklb","description":"GitHub code search with full text regex filtering, from your cli.","archived":false,"fork":false,"pushed_at":"2023-12-24T12:01:32.000Z","size":101,"stargazers_count":37,"open_issues_count":5,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-26T19:22:58.800Z","etag":null,"topics":["github","github-api","search"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/janeklb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-01-11T22:54:05.000Z","updated_at":"2024-08-03T19:20:45.978Z","dependencies_parsed_at":"2024-01-14T08:07:04.411Z","dependency_job_id":null,"html_url":"https://github.com/janeklb/gh-search","commit_stats":{"total_commits":78,"total_committers":3,"mean_commits":26.0,"dds":"0.23076923076923073","last_synced_commit":"b334d9faf1dab4cecd4715e4ede4463814367b7a"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janeklb%2Fgh-search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janeklb%2Fgh-search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janeklb%2Fgh-search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janeklb%2Fgh-search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/janeklb","download_url":"https://codeload.github.com/janeklb/gh-search/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224261927,"owners_count":17282267,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","github-api","search"],"created_at":"2024-08-01T21:01:08.683Z","updated_at":"2024-11-12T11:17:21.446Z","avatar_url":"https://github.com/janeklb.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD004 --\u003e\n\n# gh-search\n\n[![Last release](https://img.shields.io/pypi/v/gh-search.svg)](https://pypi.python.org/pypi/gh-search)\n[![Python versions](https://img.shields.io/pypi/pyversions/gh-search.svg)](https://pypi.python.org/pypi/gh-search)\n[![Unittests status](https://github.com/janeklb/gh-search/actions/workflows/lint-and-test.yml/badge.svg?branch=main)](https://github.com/janeklb/gh-search/actions/workflows/lint-and-test.yml?query=branch%3Amain)\n\nGitHub code search with full text regex filtering, from your cli.\n\n## Features\n\n- Filters search results (eg. ignore archived repositories or search for specific text in matched content)\n- Displays results grouped by `organisation/repository`\n- GitHub API rate limit aware (prevent accidentally consuming your entire core API quota)\n- Uses GitHub's [Rest API] (and therefore works with GitHub Enterprise)\n\n[Rest API]: https://docs.github.com/en/rest/reference/search#search-code\n\n## Installation\n\n`gh-search` is available as a python package via [pypi.org](https://pypi.org/project/gh-search/) and requires Python 3.12+\n\n```bash\npipx install gh-search\n```\n\n## Authentication\n\nA valid GitHub personal access token, with the `repo` scope, is required to retrieve search results.\nIt can be set on a `GITHUB_TOKEN` envvar or passed to the script via the `--github-token` option.\n\n### Enterprise\n\nTo search GitHub Enterprise set the `GITHUB_API_URL` envvar to your organisation's GitHub v3 API endpoint.\neg. `GITHUB_API_URL=https://github.mycompany.net/api/v3`. You can also use the `--github-api-url` option for this.\n\n## Usage\n\nInvoke with `gh-search` and pass a query string as the first argument. For example, to search for the word \"usage\" in this repo:\n\n```shell\ngh-search usage repo:janeklb/gh-search\n```\n\n_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._\n\n### Example: regex content filtering\n\nIf you are searching for a specific non-alphanumeric string you can use the `--regex-content-filter` (or `--content-filter`) options. This _must_\nbe combined with a valid GitHub Search API query (which will produce the result set that will subsequently be filtered).\n\nFor 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:\n\n```shell\ngh-search special_var -e \"special_var\\\\s*=\\\\s*10\"\n```\n\n### All available options\n\n```text\nUsage: gh-search [OPTIONS] QUERY...\n\n  QUERY must contain at least one search term, but may also contain search qualifiers\n  (https://docs.github.com/en/github/searching-for-information-on-github/searching-code)\n\nOptions:\n  --github-token TEXT             GitHub Auth Token. Will fall back on GITHUB_TOKEN envvar.\n  --github-api-url TEXT           Override default GitHub API URL. Can also specify via GITHUB_API_URL envvar.\n  -p, --path-filter TEXT          Exclude results whose path (or part of path) does not match this.\n  -c, --content-filter TEXT       Exclude results whose content does not match this.\n  -e, --regex-content-filter TEXT\n                                  Exclude results whose content does not match this regex.\n  -a, --include-archived          Include results from archived repos.\n  -l, --repos-with-matches        Only the names of repos are printed. Equivalent to --output=repo-list\n  -o, --output TEXT               Output style; one of: default, repo-list, json, yaml\n  -v, --verbose                   Verbose output.\n  --help                          Show this message and exit.\n```\n\n### Saving default configuration values to disk\n\nDefault values for options can specified via a config file. Location of this file is based on\n[`click.get_app_dir`](https://click.palletsprojects.com/en/8.0.x/api/#click.get_app_dir), with\n`gh-search` as the `app_name` (eg. `~/Library/Application\\ Support/gh-search/config` on MacOS).\nYou'll see the exact file location printed out next to the help text of the `--config` of\n`gh-search --help` (or if you run with the `--verbose` flag).\n\nThe option names must be converted to snake_case as per [`click`][click]'s parameter naming.\n\nFor example, in order set a default `--github-token` and `--github-api-url` you would write the\nfollowing to your config file (replacing `\u003cPLACE HOLDERS\u003e` accordingly):\n\n```config\ngithub_token=\"\u003cYOUR TOKEN\u003e\"\ngithub_api_url=\"\u003cTHE API URL\u003e\"\n```\n\n### Rate Limiting\n\n`gh-search` checks your [rate limits] and will prompt you to continue if your search might:\n\n- perform more than `500` core API requests\n- leave you with less than `10%` of your core API quota\n\nOnly the **core** API quota is checked because `gh-search`'s filters can make heavy use it. The **search** API quota is _not_ checked.\n\n## Developing\n\n- `make install-dev` install dev dependencies (set up your own virtual environment first)\n- `make unit` run unit tests\n- `make lint` run linters\n\n[searching code]: https://docs.github.com/en/github/searching-for-information-on-github/searching-code\n[rate limits]: https://docs.github.com/en/rest/reference/rate-limit\n[click]: https://click.palletsprojects.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaneklb%2Fgh-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaneklb%2Fgh-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaneklb%2Fgh-search/lists"}