assume --format json when --jq is specified

[major0]

Describe the feature or problem you’d like to solve

Various commands support specifying an output format via --format json, which is very useful when one wants to process that output via another command on the CLI, or capturing the output into a json file.

Further more, these same commands support specifying a builtin jq query via the --jq argument.

What is a little curious is that the users is forced to specify --format json if passing a --jq argument. It seems to get into the realm of being a little redundant.

$ gh project field-list 10 --owner @me --jq '.fields[].name'
cannot use `--jq` without specifying `--format json`

Proposed solution

Considering --jq requires --format json, why not assume that output format when --jq is passed?

[williammartin]

Hey @major0 thanks for opening this issue. Totally understand what you're saying here.

History Lesson

So most commands that support the --jq flag require --json to be provided, where --json takes a comma delimited list of fields that we want to be included in the command output. However, for GQL requests, this also serves as a mechanism for not only the command output but also the request themself. See for example this invocation of issue list which expects to only include the author in the output:

➜  GH_DEBUG=api gh issue list --json author
[git remote -v]
[git config --get-regexp ^remote\..*\.gh-resolved$]
* Request at 2024-05-23 14:51:49.111823 +0200 CEST m=+0.095613042
* Request to https://api.github.com/graphql
> POST /graphql HTTP/1.1
> Host: api.github.com
> Accept: application/vnd.github.merge-info-preview+json, application/vnd.github.nebula-preview
> Authorization: token ████████████████████
> Content-Length: 739
> Content-Type: application/json; charset=utf-8
> Graphql-Features: merge_queue
> Time-Zone: Europe/Amsterdam
> User-Agent: GitHub CLI 2.49.0

GraphQL query:
fragment issue on Issue {author{login,...on User{id,name}}}
  query IssueList($owner: String!, $repo: String!, $limit: Int, $endCursor: String, $states: [IssueState!] = OPEN, $assignee: String, $author: String, $mention: String) {
    repository(owner: $owner, name: $repo) {
      hasIssuesEnabled
      issues(first: $limit, after: $endCursor, orderBy: {field: CREATED_AT, direction: DESC}, states: $states, filterBy: {assignee: $assignee, createdBy: $author, mentioned: $mention}) {
        totalCount
        nodes {
          ...issue
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
GraphQL variables: {"limit":30,"owner":"cli","repo":"cli","states":["OPEN"]}

We can see that the issue fragment is limited to the author:

fragment issue on Issue {author{login,...on User{id,name}}}

As this is GQL specific behaviour, for commands that hit REST endpoints, the filtering of fields is applied after the response has come back. In the case of projects, I believe the GQL API is used but the command itself was built using go structs to represent the GQL queries, so the previous approach was also not taken. However it's not clear to me why we didn't support --json <fields> anyway so I've asked the original PR @mntlty author about it.

In any case, with this history you can probably see why the typical case of --jq without --json isn't desirable due to the fact we support changing the query itself and this information would not be available via the --jq flag alone.

But the project command doesn't support filtering even at the command level

So yeh, as mentioned gh project ... suite of commands don't support --json <fields>. As such, I can't see any good reason not to infer this. I think I'll ask @mntlty to weigh in just in case he has any thoughts. I suspect we would want to apply the same logic to the --template flag as well. It's even less clear in that case what --format json --template {{...}} means when well..the format won't be JSON because it was templatized!

[mntlty]

@williammartin agree with everything you wrote! In terms of inferring --format json for project commands, the things I would consider are:

1. is it worth it to add special case logic here?
2. will this be an issue to update in the future if project commands support --format json with variable arguments like other commands do?

[williammartin]

will this be an issue to update in the future if project commands support --format json with variable arguments like other commands do?

My first instinct is that --jq would implicitly set --json to whatever fields exist today for the --format json flag, in order to ensure backwards compatability.

is it worth it to add special case logic here?

It also could be worth general casing it. However, I suspect there are cases in which --json is actually additive, not just selective, and I don't think we would want to make the assumption that --jq means "get all the fields" for data transfer reasons. I know Mislav repeatedly pushed back on the idea of --json *.