Repository navigation
Extend gh release list to add --json flag #4572
Description
Activity
The issue is that the current
gh release listcommand has no way of getting the latest version, defining the sort order or filtering by release name. This is made even harder to implement by the lack of JSON output from thegh release listcommand.All true, however: if the main goal is to get the latest version, it's easy to do so with
gh release view, including JSON output:$ gh release view -R cli/cli --json assets --jq '.assets[].url' https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_checksums.txt https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_linux_386.deb https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_linux_386.rpm https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_linux_386.tar.gz https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_linux_amd64.deb https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_linux_amd64.rpm https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_linux_amd64.tar.gz https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_linux_arm64.deb https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_linux_arm64.rpm https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_linux_arm64.tar.gz https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_linux_armv6.deb https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_linux_armv6.rpm https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_linux_armv6.tar.gz https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_macOS_amd64.tar.gz https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_windows_386.zip https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_windows_amd64.msi https://github.com/cli/cli/releases/download/v2.1.0/gh_2.1.0_windows_amd64.zipWhat would you like to sort the
gh release listoutput by? Also, what exactly do you mean by filtering by release name—can you provide some examples?Reacted by Brice DutheilReacted by Brice Dutheil@mislav thanks for your example for using
gh release view.In answer to your questions. The last release isn't necessarily the latest release in respect to versioning (the latest tag is a whole new issue for another repo), so being able to sort by the release name or part of it is important. Some releases have a release name before the version so zulu-zebra-1.0.0 would alpha sort later than active-aardvark-2.0.0 despite being an older version, so this needs to be handled. Filtering is required for repos with multiple release types, e.g. Helm charts, where you might only be interested in releases following the format
v*or release without the formathelm-chart-*.The last release isn't necessarily the latest release in respect to versioning
You're right. Currently what GitHub calls a "latest" release isn't necessary latest by version number, but it's the latest published release by date. I don't think that's ideal, but it's something to be potentially fixed on the GitHub platform, not in the CLI itself.
so being able to sort by the release name or part of it is important.
By release name, do you mean the tag name? And by sorting by tag name, which exact sorting algorithm are you referring to? I'm not familiar with a version scheme like
active-aardvark-2.0.0; how would a user describe to the CLI that theactive-aardvark-portion should be discarded when sorting versions?Filtering is required for repos with multiple release types
Similar question to above: if someone needs to implement release filtering based on arbitrary criteria, why and how would we implement that as a flag to
gh release list? Isn't it a better idea that someone takes the output ofgh release listas it is right now and implements their own filtering however they want? Or are you simply asking for a flag that takes in a glob-like pattern (e.g.v*) and only outputs releases that match the pattern?Reacted by Sorin Sbarnea@mislav I think I've misread the output, it looks like you get name and tag separately, the active-aardvark-2.0.0 release would be a name on a
2.0.0tag.I'm under the impression that the
--jqfunctionality would allow filtering and sorting so it looks likegh release viewmight be the solution? If this is the case did I miss something in the docs? I would like to see an easier way to get all fields via the--jsonflag as that would help discovery.I would like to see an easier way to get all fields via the
--jsonflag as that would help discovery.gh release view --jsonwill list all available JSON fields.Note, however, that
gh release viewcan only show information about a single release at a time. For generic filtering needs, you can usegh release listto filter through all releases. For example, this simple script grabs the 3rd column ofgh release list(the tag name) and outputs only ones that start withv1.12.:$ gh release list -R cli/cli --limit 999 | awk -F '\t' '{if (match($3, "^v1\.12\.")) print $3}' v1.12.1 v1.12.1-pre.0 v1.12.0 v1.12.0-pre.4 v1.12.0-pre.2 v1.12.0-pre.1 v1.12.0-pre.0Personally I'd like (an expected when looking to use this)
gh release view --repo <repo> --jsonto return the whole objects not a list of fields.I think adding a
--jsonflag togh release listwould be the best way forward.I think adding a
--jsonflag togh release listwould be the best way forward.Agreed! Should I rename this issue to be about adding the
relase list --jsonfunctionality then?Personally I'd like (an expected when looking to use this)
gh release view --repo <repo> --jsonto return the whole objects not a list of fields.That's a valid remark, but we generally cannot show a "whole" object for JSON output because the underlying API requests are mostly GraphQL requests, and GraphQL requests always require you to explicitly list all the fields that you want to see in the response. Hence we always require users to enumerate the kind of data they want to see in the JSON result.
@mislav I'll rename the issue as suggested.
That's a valid remark, but we generally cannot show a "whole" object for JSON output because the underlying API requests are mostly GraphQL requests, and GraphQL requests always require you to explicitly list all the fields that you want to see in the response. Hence we always require users to enumerate the kind of data they want to see in the JSON result.
I get that implementing
--jsonwithout a value would require two GraphQL calls, but that's an implementation detail (you can implement a catch all parameter in you GraphQL server code using the same logic as you use for listing the available fields). As a user I don't want to know about the implementation, I want to know abut the data. If the fields are dynamic as you say there is even more reason to support the empty--jsonflag, otherwise every time I want to investigate this tool I need to call the command to return all possible fields and then manually concatenate them into the--jsonflag values to get the full data context.Reacted by Clyde Tedrick- changed the title
[-]Extend `gh release list` to support ordering and filtering[/-][+]Extend `gh release list` to add `--json` flag[/+]on Oct 21, 2021 - added 2 commits that reference this issue
on Nov 3, 2021 - added and removed
on Feb 28, 2022 13 remaining items
json should be the default and
--output tableshould be required to get a non-json view.Reacted by benany progress on this?
Reacted by Rasmey SARETHThis is something that I need too.
@mislav I'm picking this up to work on this week and part of my attempt to learn some Go. I've already got the basic
--jsonargument working that prints the available fields. I've even got support for a list of fields (tagName, etc), however, it only works withtagNameand panics with anything else 🙃. I'd love to get a draft PR open to elicit some early feedback. Is that something that's OK in this repo?@mislav I recall seeing some discussion about needing to migrate the release list code over to REST. Is that still the case and would you like that done in a separate PR to the
--jsonwork? I do think the change would have an impact on the output for the currentlistcommand (without JSON) in that the REST API does not return alatestproperty.EDIT:
I found the original quote from above and I have it backwards. You want to standardize both Release commands on GraphQL. Right now,listis GraphQL whileviewis REST.To reach gh release list --json parity with gh release view --json, we might have to significantly restructure how gh release list API calls are implemented: right now they are REST but I think we should move to GraphQL. If we continue to use two different API flavors to implement two related gh commands, I think we may run into inconsistencies.
@jakeatoms Unfortunately Mislav is no longer working at GitHub.
Regarding this work, it sounds like you are on the right track as we are looking to standardize on using the GraphQL endpoint for both
release listandrelease view. I would be in favor of breaking this work up into two separate PRs. The first to do the switch to the GraphQL endpoint and the second to actually add in the--jsonflag feature. How does that sound?@samcoe There are potentially a number of API-breaking changes moving to GraphQL for
view:
The current--jsonargument supports returning the following fields that don't exist via GQL:apiUrl(eg "https://api.github.com/repos/octocat/Hello-World/releases/1")uploadUrl(eg "https://uploads.github.com/repos/octocat/Hello-World/releases/1/assets{?name,label}")targetCommitish(eg "master")
Additionally, there are top-level fields on
Releasevia REST that don't exist in GQL, but can be found within the individualAssets:tarballUrl(eg "https://api.github.com/repos/octocat/Hello-World/tarball/v1.0.0")zipballUrl(eg "https://api.github.com/repos/octocat/Hello-World/zipball/v1.0.0")
So my question is, is maintaining backwards compability important here? Removing these could break any existing scripts that are handling their own uploads or API interactions for a given release. An alternative would be to point users to the other subcommands like
uploadin order to facilitate additional API actions.Side note: The various other
releasecommands likeuploadcan continue to make use of the existing shared code to fetch a release via the REST API, so things like theuploadUrlwill still be present.Can you emit a warning to stderr that said something along the lines of "to retrieve these deprecated fields use the
gh rest...orgh release upload...commands instead".Also arguably, it would be nice if the user could specify optional subgraphs, since its gql by adding something like
--subbraphs assets,uploadsor whatever.@jakeatoms Thanks for the investigation. I should have double checked what Mislav had stated before giving the go-ahead here. We really care about maintaining backwards compatibility and having this feature cause a breaking change is not something we can move forwards with.
I am going to propose a different path forward here and that is to instead move
gh release listto use the REST API so that bothgh release viewandgh release listcan support the same list of--jsonfields. There is only one caveat and that is currentlygh release listdisplays an indicator of the latest release, that is not something returned by the REST endpoint so we will have to make on extra API call to retrieve that. I feel like that one extra API call is not a huge deal and allows us to move forward with this work. I suspect that this direction makes #8288 mostly irrelevant now, apologies for that 🙇Reacted by Jake Adams@jakeatoms Thanks for the investigation. I should have double checked what Mislav had stated before giving the go-ahead here. We really care about maintaining backwards compatibility and having this feature cause a breaking change is not something we can move forwards with.
I am going to propose a different path forward here and that is to instead move
gh release listto use the REST API so that bothgh release viewandgh release listcan support the same list of--jsonfields. There is only one caveat and that is currentlygh release listdisplays an indicator of the latest release, that is not something returned by the REST endpoint so we will have to make on extra API call to retrieve that. I feel like that one extra API call is not a huge deal and allows us to move forward with this work. I suspect that this direction makes #8288 mostly irrelevant now, apologies for that 🙇sounds good! I'll close that other PR and begin work on this design!
This might help if you need to get the tag name:
gh release ls | awk '{print $(NF-1)}'
I want to share my solution (https://cli.github.com/manual/gh_api):
# get all the release data in JSON gh api repos/cli/cli/releases # get all the tag_names gh api repos/cli/cli/releases | jq -r '.[].tag_name' # get the most recent tag name gh api repos/cli/cli/releases | jq -r '.[0].tag_name'
Describe the feature or problem you’d like to solve
With GitHub being the primary source of OSS software it's a pretty common requirement to install the latest version from GitHub releases. The issue is that the current
gh release listcommand has no way of getting the latest version, defining the sort order or filtering by release name. This is made even harder to implement by the lack of JSON output from thegh release listcommand.Proposed solution
Support the
--jsonand--jqflags that are ingh release view. It would be great is the--jsonflag worked without a value or with a catch-all such as--json ALLto return all fields.Additional context
n/a