From 8457ec84b80a60d0e06a01158258a53af04293e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mislav=20Marohni=C4=87?= Date: Thu, 10 Nov 2022 14:59:57 +0100 Subject: [PATCH 1/4] Overhaul README for stable release --- README.md | 58 ++++++++++++++++++++++++------------------------------- 1 file changed, 25 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index f148f38..4958a7e 100644 --- a/README.md +++ b/README.md @@ -1,69 +1,61 @@ -# go-gh beta +# Go library for the GitHub CLI -**This project is in beta!** Feedback is welcome. +`go-gh` is a collection of Go modules to make authoring [GitHub CLI extensions][extensions] easier. -A Go module for CLI Go applications and [gh extensions][extensions] that want a convenient way to interact with [gh][], and the GitHub API using [gh][] environment configuration. +Modules from this library will obey GitHub CLI conventions by default: -`go-gh` supports multiple ways of getting access to `gh` functionality: +- [`CurrentRepository()`](https://pkg.go.dev/github.com/cli/go-gh#CurrentRepository) respects `GH_REPO` and reads from git remote configuration as fallback; +- GitHub API requests will be authenticated using the same mechanism as gh, respecting `GH_TOKEN` and `GH_HOST` if present; +- Inspecting [`term`](https://pkg.go.dev/github.com/cli/go-gh/pkg/term) capabilities is done with respect to e.g. `NO_COLOR`; +- Generating [table-](https://pkg.go.dev/github.com/cli/go-gh/pkg/tableprinter) or [Go template](https://pkg.go.dev/github.com/cli/go-gh/pkg/template)-based output uses the same engine as gh; +- The [`browser`](https://pkg.go.dev/github.com/cli/go-gh/pkg/browser) module activates the user's preferred web browser. -* Helpers that automatically read a `gh` config to authenticate themselves -* `gh.Exec` shells out to a `gh` install on your machine - -If you'd like to use `go-gh` on systems without `gh` installed and configured, you can provide custom authentication details to the `go-gh` API helpers. +## Usage +See the [go-gh full reference documentation](https://pkg.go.dev/github.com/cli/go-gh). -## Installation -```bash -go get github.com/cli/go-gh -``` - -## Usage ```golang package main + import ( "fmt" + "log" "github.com/cli/go-gh" ) func main() { // These examples assume `gh` is installed and has been authenticated - // Execute `gh issue list -R cli/cli`, and print the output. - args := []string{"issue", "list", "-R", "cli/cli"} - stdOut, _, err := gh.Exec(args...) + // Shell out to a gh command and read its output + issueList, _, err := gh.Exec("issue", "list", "--repo", "cli/cli", "--limit", "5") if err != nil { - fmt.Println(err) - return + log.Fatal(err) } - fmt.Println(stdOut.String()) + fmt.Println(issueList.String()) // Use an API helper to grab repository tags client, err := gh.RESTClient(nil) if err != nil { - fmt.Println(err) - return + log.Fatal(err) } - response := []struct{ Name string }{} + response := []struct{ + Name string + }{} err = client.Get("repos/cli/cli/tags", &response) if err != nil { - fmt.Println(err) - return + log.Fatal(err) } fmt.Println(response) } ``` -See [examples][examples] for more use cases. - -## Reference Documentation - -Full reference docs can be found on [pkg.go.dev](https://pkg.go.dev/github.com/cli/go-gh). +See [examples][] for more demonstrations of usage. ## Contributing -If anything feels off, or if you feel that some functionality is missing, please check out the [contributing page][contributing]. There you will find instructions for sharing your feedback, and submitting pull requests to the project. +If anything feels off, or if you feel that some functionality is missing, please check out our [contributing docs][contributing]. There you will find instructions for sharing your feedback and for submitting pull requests to the project. Thank you! + -[extensions]: https://github.com/topics/gh-extension -[gh]: https://github.com/cli/cli +[extensions]: https://docs.github.com/en/github-cli/github-cli/creating-github-cli-extensions [examples]: ./example_gh_test.go [contributing]: ./.github/CONTRIBUTING.md From 46ee12d4bfa26cd59a74e8f535d17aa216126ee5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mislav=20Marohni=C4=87?= Date: Thu, 10 Nov 2022 16:46:54 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Ariel Deitcher <1149246+mntlty@users.noreply.github.com> --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4958a7e..dd411bb 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,15 @@ Modules from this library will obey GitHub CLI conventions by default: -- [`CurrentRepository()`](https://pkg.go.dev/github.com/cli/go-gh#CurrentRepository) respects `GH_REPO` and reads from git remote configuration as fallback; -- GitHub API requests will be authenticated using the same mechanism as gh, respecting `GH_TOKEN` and `GH_HOST` if present; +- [`CurrentRepository()`](https://pkg.go.dev/github.com/cli/go-gh#CurrentRepository) respects the value of the `GH_REPO` environment variable if set, and reads from git remote configuration as fallback; +- GitHub API requests will be authenticated using the same mechanism as `gh`, respecting the value of the `GH_TOKEN` and `GH_HOST` environment variables if present; - Inspecting [`term`](https://pkg.go.dev/github.com/cli/go-gh/pkg/term) capabilities is done with respect to e.g. `NO_COLOR`; -- Generating [table-](https://pkg.go.dev/github.com/cli/go-gh/pkg/tableprinter) or [Go template](https://pkg.go.dev/github.com/cli/go-gh/pkg/template)-based output uses the same engine as gh; +- Generating [table](https://pkg.go.dev/github.com/cli/go-gh/pkg/tableprinter) or [Go template](https://pkg.go.dev/github.com/cli/go-gh/pkg/template) based output uses the same engine as gh; - The [`browser`](https://pkg.go.dev/github.com/cli/go-gh/pkg/browser) module activates the user's preferred web browser. ## Usage -See the [go-gh full reference documentation](https://pkg.go.dev/github.com/cli/go-gh). +See the full `go-gh` [reference documentation](https://pkg.go.dev/github.com/cli/go-gh) for more information ```golang package main From 017620a036df7ac7d49b7411a9fc22c6741c535b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mislav=20Marohni=C4=87?= Date: Thu, 10 Nov 2022 16:51:32 +0100 Subject: [PATCH 3/4] fixup features --- README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index dd411bb..4c0c27b 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,14 @@ Modules from this library will obey GitHub CLI conventions by default: -- [`CurrentRepository()`](https://pkg.go.dev/github.com/cli/go-gh#CurrentRepository) respects the value of the `GH_REPO` environment variable if set, and reads from git remote configuration as fallback; -- GitHub API requests will be authenticated using the same mechanism as `gh`, respecting the value of the `GH_TOKEN` and `GH_HOST` environment variables if present; -- Inspecting [`term`](https://pkg.go.dev/github.com/cli/go-gh/pkg/term) capabilities is done with respect to e.g. `NO_COLOR`; -- Generating [table](https://pkg.go.dev/github.com/cli/go-gh/pkg/tableprinter) or [Go template](https://pkg.go.dev/github.com/cli/go-gh/pkg/template) based output uses the same engine as gh; +- [`CurrentRepository()`](https://pkg.go.dev/github.com/cli/go-gh#CurrentRepository) respects the value of the `GH_REPO` environment variable if set, and reads from git remote configuration as fallback. + +- GitHub API requests will be authenticated using the same mechanism as `gh`, i.e. respecting the values `GH_TOKEN` and `GH_HOST` environment variables if set and falling back to the user's stored OAuth token. + +- [Terminal capabilities](https://pkg.go.dev/github.com/cli/go-gh/pkg/term) are determined by taking environment variables `GH_FORCE_TTY`, `NO_COLOR`, `CLICOLOR`, etc. into account. + +- Generating [table](https://pkg.go.dev/github.com/cli/go-gh/pkg/tableprinter) or [Go template](https://pkg.go.dev/github.com/cli/go-gh/pkg/template) output uses the same engine as gh. + - The [`browser`](https://pkg.go.dev/github.com/cli/go-gh/pkg/browser) module activates the user's preferred web browser. ## Usage From 4b55f26ecb1135e6ac76a3774d198f9dbbad05e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mislav=20Marohni=C4=87?= Date: Thu, 10 Nov 2022 16:53:01 +0100 Subject: [PATCH 4/4] fixup --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4c0c27b..8b59400 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ Modules from this library will obey GitHub CLI conventions by default: -- [`CurrentRepository()`](https://pkg.go.dev/github.com/cli/go-gh#CurrentRepository) respects the value of the `GH_REPO` environment variable if set, and reads from git remote configuration as fallback. +- [`CurrentRepository()`](https://pkg.go.dev/github.com/cli/go-gh#CurrentRepository) respects the value of the `GH_REPO` environment variable and reads from git remote configuration as fallback. -- GitHub API requests will be authenticated using the same mechanism as `gh`, i.e. respecting the values `GH_TOKEN` and `GH_HOST` environment variables if set and falling back to the user's stored OAuth token. +- GitHub API requests will be authenticated using the same mechanism as `gh`, i.e. using the values of `GH_TOKEN` and `GH_HOST` environment variables and falling back to the user's stored OAuth token. - [Terminal capabilities](https://pkg.go.dev/github.com/cli/go-gh/pkg/term) are determined by taking environment variables `GH_FORCE_TTY`, `NO_COLOR`, `CLICOLOR`, etc. into account.