Proposing a slight amendment to the `gh api` field docs to clarify the current limitation around "complex" field values, e.g. arrays/objects.
Related: #1484
Signed-off-by: Michael Gasch <mgasch@vmware.com>
With the `--format` flag, the value of the flag is parsed as a Go
template which is then evaluated against parsed response data.
https://golang.org/pkg/text/template
- Clarify that fields need to be in "key=value" format
- Headers need to be in "key:value" format
- Contrast POST vs GET requests with params in examples
- Add an example of how to add HTTP headers
- Use backticks where applicable
Accept the "HOST/OWNER/REPO" syntax or passing a full URL for both the
`--repo` flag and the GH_REPO environment variable and allow setting
GH_HOST environment variable to override just the hostname for
operations that assume "github.com" by default.
Examples:
$ gh repo clone example.org/owner/repo
$ GH_HOST=example.org gh repo clone repo
$ GH_HOST=example.org gh api user
$ GH_HOST=example.org gh gist create myfile.txt
$ gh issue list -R example.org/owner/repo
$ gh issue list -R https://example.org/owner/repo.git
$ GH_REPO=example.org/owner/repo gh issue list
GraphQL supports supplying multiple queries in the `query` parameter,
but an additional `operationName` parameter is then required to select
the query to execute.
Previously, it was impossible to pass `operationName` since it would get
serialized under `variables`, but it needs to be a top-level parameter.
With this change, `operationName` is a special GraphQL parameter name
just like `query` already is.
Most endpoints respect this parameter by default. Those that don't will
just ignore it. The `per_page=100` parameter is not added if there is
already a `per_page` parameter specified in the request.
When `{owner}` and `{repo}` strings are found in request path (for REST
requests) or `query` (for GraphQL), they are replaced with values from
the repository of the current working directory.
