{"id":39501794,"url":"https://github.com/mccurdyc/neighbor","last_synced_at":"2026-01-18T05:48:03.126Z","repository":{"id":57506717,"uuid":"148036664","full_name":"mccurdyc/neighbor","owner":"mccurdyc","description":"👷 Importable Go packages and an accompanying command-line interface for searching, efficiently cloning and executing an arbitrary command against GitHub projects, to avoid having to \"roll your own\".","archived":false,"fork":false,"pushed_at":"2020-01-16T12:54:12.000Z","size":12830,"stargazers_count":21,"open_issues_count":10,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-06-20T13:38:29.099Z","etag":null,"topics":["cli","github","github-api","github-golang","golang","golang-package","search"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/mccurdyc/neighbor","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mccurdyc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-09T15:04:42.000Z","updated_at":"2023-12-05T14:57:47.000Z","dependencies_parsed_at":"2022-08-29T20:20:55.795Z","dependency_job_id":null,"html_url":"https://github.com/mccurdyc/neighbor","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/mccurdyc/neighbor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mccurdyc%2Fneighbor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mccurdyc%2Fneighbor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mccurdyc%2Fneighbor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mccurdyc%2Fneighbor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mccurdyc","download_url":"https://codeload.github.com/mccurdyc/neighbor/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mccurdyc%2Fneighbor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28531550,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cli","github","github-api","github-golang","golang","golang-package","search"],"created_at":"2026-01-18T05:48:03.055Z","updated_at":"2026-01-18T05:48:03.110Z","avatar_url":"https://github.com/mccurdyc.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/mccurdyc/neighbor/blob/master/docs/imgs/orange-background-logo.png?raw=true\"\u003e\u003cbr\u003e\n\u003c/div\u003e\n\n[![Build Status][build-badge]][build-url]\n[![GolangCI][golint-badge]][golint-url]\n[![GoDoc][godoc-badge]][godoc-url]\n[![License][license-badge]][license-url]\n[![codecov][codecov-badge]][codecov-url]\n[![Discord chat][discord-badge]][discord-url]\n[![Gitter][gitter-badge]][gitter-url]\n[![Release][release-badge]][release-url]\n\n[build-badge]: https://circleci.com/gh/mccurdyc/neighbor/tree/master.svg?style=svg\n[build-url]: https://circleci.com/gh/mccurdyc/neighbor/tree/master\n[golint-badge]: https://golangci.com/badges/github.com/mccurdyc/neighbor.svg\n[golint-url]: https://golangci.com\n[godoc-badge]: https://godoc.org/github.com/mccurdyc/neighbor?status.svg\n[godoc-url]: https://pkg.go.dev/github.com/mccurdyc/neighbor?tab=overview\n[license-badge]: https://img.shields.io/github/license/mccurdyc/neighbor\n[license-url]: LICENSE\n[codecov-badge]: https://codecov.io/gh/mccurdyc/neighbor/branch/master/graph/badge.svg\n[codecov-url]: https://codecov.io/gh/mccurdyc/neighbor\n[discord-badge]: https://img.shields.io/discord/666244141784498177?logo=discord\u0026label=discord\u0026logoColor=white\n[discord-url]: https://discord.gg/qq9sA7\n[gitter-badge]: https://badges.gitter.im/neighborproject/community.svg\n[gitter-url]: https://gitter.im/neighborproject/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\n[release-badge]: https://img.shields.io/github/release/mccurdyc/neighbor.svg\n[release-url]: https://github.com/mccurdyc/neighbor/releases/latest\n\nneighbor has importable Go packages (e.g., `builtin/*`, `sdk/*`) and an accompanying\ncommand-line interface for searching, cloning and executing an arbitrary binary\nagainst GitHub projects. Abstractions are in place to make doing the aforementioned\neasy and efficient for projects obtained from arbitrary search and retrieval methods\n(i.e., not limited to GitHub Search, repositories or Git clone).\n\nThe motivation for neighbor is to provide users (e.g., developers, researchers, etc.)\nwith a way to search, efficiently clone and evaluate projects without having to\n\"roll their own\". Instead users can focus on the task at hand. [TODO] Another motivation\nfor neighbor is to provide researchers with a standard, reproducible way of obtaining projects.\nIn order to guarantee fair comparisons of approaches, rather than \"hand-picked\"\nprojects that reinforce claims. This can be accomplished now via `zip`ping the\nproject versions retrieved from a run of neighbor.\n\nneighbor uses [v3 of GitHub's REST API](https://developer.github.com/v3/).\n\n### Why neighbor\n\n+ Extensibility\n  + Abstract interfaces for projects, search and retrieval functions which means\n  that it is easy to add new \"types\" or projects (e.g., something other than GitHub\n  repositories) and use other methods for search and retrieval in addition to\n  GitHub search and Git clone, respectively.\n+ Abstracting GitHub API interaction (searching, sorting and cloning)\n  + Transparent pagination\n  + Transparent authentication\n  + Transparent rate limit handling\n+ Doing the above efficiently by leveraging Go's concurrent capabilities\n\n## Requirements\n\n+ [Go `1.13+`](https://golang.org/dl/)\n  + Why `1.13+`?\n    + [Updates to error handling](https://blog.golang.org/go1.13-errors)\n    + [Updates to modules](https://golang.org/doc/go1.13#modules) for dependency management\n  + [Installing Go documentation](https://golang.org/doc/install)\n\n## Getting Started\n\n1. Installing the project\n\n    `GOPROXY=https://proxy.golang.org go get github.com/mccurdyc/neighbor@latest`\n\n2. Searching and Evaluating\n\n    First, you should review the [Searching on GitHub](https://help.github.com/en/github/searching-for-information-on-github/searching-on-github) documentation.\n\n    1. **Plain Retrieve Example**\n\n      ```bash\n      make build\n      ./bin/neighbor --query=\"org:neighbor-projects NOT minikube\" --plain_retrieve --projects_directory=\"_projects_directory\" --num_projects=2 --clean=false\n      ```\n\n    2. **Repository Search Example**\n\n      ```bash\n      make build\n      ./bin/neighbor --query=\"org:neighbor-projects NOT minikube\" --command=\"ls -al\" --projects_directory=\"_projects_directory\" --num_projects=2 --clean=false\n      ```\n\n    3. **Code Search Example**\n\n      _Note: [GitHub requires users to be logged in to search code](https://developer.github.com/v3/search/#search-code).\n      Even in public repositories._ Refer to the Code search documentation [here](https://help.github.com/en/github/searching-for-information-on-github/searching-code)\n      for building a query. Code searches are searched elastically and are not\n      guaranteed to return exact matches. Searching code for exact matches is currently\n      in beta and only work on very specific repositories, see [this section in the documentation](https://help.github.com/en/github/searching-for-information-on-github/searching-code-for-exact-matches#searching-code-for-exact-matches)\n\n      It is critical that you read the above documentation because Code search may\n      not behave as you would expect. For example,\n\n      \u003e You can't use the following wildcard characters as part of your search query:\n      ```\n      . , : ; / \\ ` ' \" = * ! ? # $ \u0026 + ^ | ~ \u003c \u003e ( ) { } [ ]\n      ```\n\n      The search will simply ignore these symbols. Additionally, I have found that\n      using [`extension:EXTENSION`](https://help.github.com/en/github/searching-for-information-on-github/searching-code#search-by-file-extension)\n      is more reliable and accurate than [`filename:FILENAME`](https://help.github.com/en/github/searching-for-information-on-github/searching-code#search-by-filename).\n\n      ```bash\n      make build\n      ./bin/neighbor --search_type=\"code\" --auth_token=\"abc123\" --query=\"pkg/errors in:file extension:mod path:/ user:mccurdyc\" --command=\"ls -al\"\n      ```\n\n    4. **Multi-Line Command Example**\n\n      Multi-line commands work, but **pipes (i.e., `|`) do not**. In order to use pipes,\n      you should create a custom binary that handles piping the output from one command\n      to the next (e.g., [\"How to pipe several comands in Go?\" on StackOverflow](https://stackoverflow.com/questions/10781516/how-to-pipe-several-commands-in-go))\n\n      ```bash\n      make build\n      ./bin/neighbor --search_type=\"code\" --auth_token=\"abc123\" --query=\"pkg/errors in:file extension:mod path:/ user:mccurdyc\" --command=\"ls \\\n      -al\"\n      ```\n\n3. Confirming\n\n    One way to confirm that you obtained the number of projects that you expected\n    is to run the following:\n\n    ```bash\n    find _external_projects -mindepth 2 -maxdepth 2 | wc -l\n    ```\n\n## Usage\n\n```bash\nUsage: neighbor (--file=\u003cfile\u003e | --query=\u003cstring\u003e (--command=\u003cstring\u003e | --plain_retrieve)) [--auth_token=\u003cgithub-access-token\u003e] [--search_type=\u003crepository|code\u003e] [--projects_directory=\u003cstring\u003e] [--num_projects=\u003cint\u003e] [--clean=\u003cbool\u003e | --plain_retrieve]\n\n  -alsologtostderr\n        log to standard error as well as files\n  -auth_token string\n        Your personal GitHub access token. This is required to access private repositories and increases rate limits.\n  -clean\n        Delete the projects directory after running the command against each project. (default true)\n  -command string\n        The command to execute on each project returned from a search query.\n  -file string\n        Absolute filepath to the config file.\n  -help\n        Print this help menu.\n  -log_backtrace_at value\n        when logging hits line file:N, emit a stack trace\n  -log_dir string\n        If non-empty, write log files in this directory\n  -logtostderr\n        log to standard error instead of files\n  -num_projects int\n        The number of _desired_ projects to obtain. (default 10)\n  -plain_retrieve\n        Whether projects should just be retrieved and not evaluated.\n  -projects_directory string\n        Where the projects should be stored locally and found for evalutation. (default \"_external_projects\")\n  -query string\n        The search query to execute.\n  -search_type string\n        The type of search to perform. (default \"project\")\n  -stderrthreshold value\n        logs at or above this threshold go to stderr\n  -v value\n        log level for V logs\n  -vmodule value\n        comma-separated list of pattern=N settings for file-filtered logging\n```\n\n## FAQ\n\n### What about private repositories?\n\nGenerate a [GitHub Personal Access Token](https://github.com/settings/tokens)\nneighbor uses token authentication for communicating and authenticating with GitHub.\nTo read more about GitHub's token authentication, visit [this site](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/).\n\n\u003e You can create a personal access token and use it in place of a password when performing Git operations over HTTPS with Git on the command line or the API.\n\nAuthentication is required to both increase the [GitHub API limitations](https://godoc.org/github.com/google/go-github/github#hdr-Rate_Limiting)\nas well as access private content (e.g., repositories, gists, etc.).\n\n+ Use the `--auth_token` command-line argument\n+ If using a config file, add the generated token to the file\n  ```json\n  {\n    \"auth_token\": \"yourAccessToken1234567890abcdefghijklmnopqrstuvwxyz\",\n    ...\n  }\n  ```\n\n### Executing a Cli Command/Executable Binary\n\nneighbor allows you to specify an executable binary to be run on\na per-repository basis with **each repository as the working directory**.\n\nExamples can be found in the [examples](./_examples).\n\n## License\n+ [GNU General Public License Version 3](./LICENSE)\n\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fmccurdyc%2Fneighbor.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fmccurdyc%2Fneighbor?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmccurdyc%2Fneighbor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmccurdyc%2Fneighbor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmccurdyc%2Fneighbor/lists"}