Improve run list doc with available --json fields - #8934
Conversation
There was a problem hiding this comment.
Thanks for this PR @babakks. I'm hesitant to accept this as is because as you call out in #8588 (comment) the same problem exists for every list command, but not only that, it also exists for other commands like issue view.
My concern with documenting them like this is that there is a good chance we either forget to document this, or they get out of date as fields are added. It makes me think there are two options:
- We indicate that this list of fields can be produced by providing the
--jsonflag and no argument:
➜ cli git:(merge-json) gh issue view --json
Specify one or more comma-separated fields for `--json`:
assignees
author
body
closed
closedAt
comments
createdAt
id
labels
milestone
number
projectCards
projectItems
reactionGroups
state
title
updatedAt
url
- We build something so that at the time of execution we execute the same code path and include the output in the generated docs.
The first option is clearly much easier to achieve but the second might be more friendly in the long run.
|
@williammartin Thanks for the comment. I agree with the second approach being more useful. I came up with this simple string formatting function, named Now the doc looks like this: |
|
@williammartin I checked all references of
If you're okay with the changes in this PR, I can apply the same change for the above commands as well. |
There was a problem hiding this comment.
Thanks a lot for trying this out. I'm in two minds about this change. Here's what it looks like to me:
It seems like a lot of help real estate for what the user can discover by providing `--json` with no args, as is documented in [`gh help formatting`](https://cli.github.com/manual/gh_help_formatting):
The --json flag requires a comma separated list of fields to fetch. To view the possible JSON field names for a command omit the string argument to the --json flag when you run the command
This is linked to from the --template flag usage:
-t, --template string Format JSON output using a Go template; see "gh help formatting"
Maybe we should just include "; see "gh help formatting on the usage of --jq and --json?
On the other hand, being able to see the available fields at a glance in the manual or help is also quite nice for ctrl+F and if you don't have the CLI to hand right at that moment.
I think I'd like @andyfeller to chime in here to choose a direction.
Finally, if we did proceed with this, I also had a slightly different approach in mind. In my idea, when we pass the cmd to AddJSONFlags, it would update the Long field with this text concatenated. This way there's no way for us to either forget to add this content to a command that has the JSON flags, or to provide different slices by accident (e.g. when copying and pasting commands).
It would also mean that every command you listed above and in future get the behaviour with no further changes needed.
|
@williammartin Thanks. I, too, agree that it should only be seen in the long doc. And also I liked the idea of doing it in the One more argument in favor of listing available fields in the docs is that the online CLI manual would also benefit from it. I'll wait for @andyfeller's opinion on this and will then update the requested changes. |
I love how we both came to the same conclusion as I really prefer minimizing additional changes needed by commands that can fall out of sync. However, I'd prefer a separate section lower in the help usage for JSON fields over tacking it onto
Mock up of
|
|
@andyfeller and I discussed this on Slack and we agree that including it in a separate section of the help is the best option here. However, we think it would be better to provide a compressed form as you have done to avoid annoying users by scrolling past the most important sections when there are a lot of fields. |
Signed-off-by: Babak K. Shandiz <babak.k.shandiz@gmail.com>
Signed-off-by: Babak K. Shandiz <babak.k.shandiz@gmail.com>
Signed-off-by: Babak K. Shandiz <babak.k.shandiz@gmail.com>
Signed-off-by: Babak K. Shandiz <babak.k.shandiz@gmail.com>
Signed-off-by: Babak K. Shandiz <babak.k.shandiz@gmail.com>
Signed-off-by: Babak K. Shandiz <babak.k.shandiz@gmail.com>
Signed-off-by: Babak K. Shandiz <babak.k.shandiz@gmail.com>
Signed-off-by: Babak K. Shandiz <babak.k.shandiz@gmail.com>
Signed-off-by: Babak K. Shandiz <babak.k.shandiz@gmail.com>
7c15e62 to
05a87b9
Compare
|
@williammartin @andyfeller Thanks for clarifying this. Since this PR is no longer just about the The "JSON Fields" section is now included in Markdown (website format), man pages, and For this to work, within the I've also moved the newly created Different docs (for
|
Signed-off-by: Babak K. Shandiz <babak.k.shandiz@gmail.com>
|
@andyfeller I couldn't ask for your review from the sidebar. Could you please have a look? |
Thank you for your patience, @babakks, going to get this done now 🙇 |
andyfeller
left a comment
There was a problem hiding this comment.
@babakks : once again, thank you for improving the GitHub CLI user experiences ❤️
Capturing examples of the updated output looks good:
... --help
$ ./bin/gh repo list --help
List repositories owned by a user or organization.
Note that the list will only include repositories owned by the provided argument,
and the `--fork` or `--source` flags will not traverse ownership boundaries. For example,
when listing the forks in an organization, the output would not include those owned by individual users.
For more information about output formatting flags, see `gh help formatting`.
USAGE
gh repo list [<owner>] [flags]
ALIASES
ls
FLAGS
--archived Show only archived repositories
--fork Show only forks
-q, --jq expression Filter JSON output using a jq expression
--json fields Output JSON with the specified fields
-l, --language string Filter by primary coding language
-L, --limit int Maximum number of repositories to list (default 30)
--no-archived Omit archived repositories
--source Show only non-forks
-t, --template string Format JSON output using a Go template; see "gh help formatting"
--topic strings Filter by topic
--visibility string Filter by repository visibility: {public|private|internal}
INHERITED FLAGS
--help Show help for command
JSON FIELDS
assignableUsers, codeOfConduct, contactLinks, createdAt, defaultBranchRef,
deleteBranchOnMerge, description, diskUsage, forkCount, fundingLinks,
hasDiscussionsEnabled, hasIssuesEnabled, hasProjectsEnabled, hasWikiEnabled,
homepageUrl, id, isArchived, isBlankIssuesEnabled, isEmpty, isFork,
isInOrganization, isMirror, isPrivate, isSecurityPolicyEnabled, isTemplate,
isUserConfigurationRepository, issueTemplates, issues, labels, languages,
latestRelease, licenseInfo, mentionableUsers, mergeCommitAllowed, milestones,
mirrorUrl, name, nameWithOwner, openGraphImageUrl, owner, parent,
primaryLanguage, projects, projectsV2, pullRequestTemplates, pullRequests,
pushedAt, rebaseMergeAllowed, repositoryTopics, securityPolicyUrl,
squashMergeAllowed, sshUrl, stargazerCount, templateRepository, updatedAt, url,
usesCustomOpenGraphImage, viewerCanAdminister, viewerDefaultCommitEmail,
viewerDefaultMergeMethod, viewerHasStarred, viewerPermission,
viewerPossibleCommitEmails, viewerSubscription, visibility, watchers
LEARN MORE
Use `gh <command> <subcommand> --help` for more information about a command.
Read the manual at https://cli.github.com/manual$ ./bin/gh issue view --help
Display the title, body, and other information about an issue.
With `--web` flag, open the issue in a web browser instead.
For more information about output formatting flags, see `gh help formatting`.
USAGE
gh issue view {<number> | <url>} [flags]
FLAGS
-c, --comments View issue comments
-q, --jq expression Filter JSON output using a jq expression
--json fields Output JSON with the specified fields
-t, --template string Format JSON output using a Go template; see "gh help formatting"
-w, --web Open an issue in the browser
INHERITED FLAGS
--help Show help for command
-R, --repo [HOST/]OWNER/REPO Select another repository using the [HOST/]OWNER/REPO format
JSON FIELDS
assignees, author, body, closed, closedAt, comments, createdAt, id, labels,
milestone, number, projectCards, projectItems, reactionGroups, state, title,
updatedAt, url
LEARN MORE
Use `gh <command> <subcommand> --help` for more information about a command.
Read the manual at https://cli.github.com/manual| if _, ok := command.Annotations["help:json-fields"]; ok { | ||
| fields := strings.Split(command.Annotations["help:json-fields"], ",") | ||
| helpEntries = append(helpEntries, helpEntry{"JSON FIELDS", text.FormatSlice(fields, 80, 0, "", "", true)}) | ||
| } | ||
| if _, ok := command.Annotations["help:arguments"]; ok { | ||
| helpEntries = append(helpEntries, helpEntry{"ARGUMENTS", command.Annotations["help:arguments"]}) | ||
| } |
There was a problem hiding this comment.
Realizing I don't know many commands where ARGUMENTS section would show up to say definitively if JSON fields should come before or after 🤔 ... my gut says JSON fields after arguments but will keep looking for an example as not the end of the world
There was a problem hiding this comment.
I agree that arguments should be printed before the JSON fields, since they're more like an appendix section. Since this is already merged, I can submit another PR for that if you say so.
This PR adds the name of available JSON fields to the command doc.
Fixes #8588