Inconsistent use of curly braces and square brackets for command args syntax e.g. {args} and [args] respectively

Describe the bug

As mentioned in the title, the command args syntax is inconsistent.

Affected version

$ gh --version 
gh version 2.67.0 (2025-02-11)
https://github.com/cli/cli/releases/tag/v2.67.0

Steps to reproduce the behavior

Use regex Use:\s+".* \{.*\}.*" to find occurrences with curly braces

Here's a list of such occurrences from VSCode:

20 results - 19 files

pkg/cmd/alias/delete/delete.go:
  28: Use:   "delete {<alias> | --all}",

pkg/cmd/extension/command.go:
  423: 		Use:   "upgrade {<name> | --all}",

pkg/cmd/gist/delete/delete.go:
  38: Use:   "delete {<id> | <url>}",

pkg/cmd/gist/edit/edit.go:
  59: Use:   "edit {<id> | <url>} [<filename>]",

pkg/cmd/gist/rename/rename.go:
  38: Use:   "rename {<id> | <url>} <oldFilename> <newFilename>",

pkg/cmd/issue/close/close.go:
  38: Use:   "close {<number> | <url>}",

pkg/cmd/issue/comment/comment.go:
  25: Use:   "comment {<number> | <url>}",

pkg/cmd/issue/delete/delete.go:
  41: Use:   "delete {<number> | <url>}",

pkg/cmd/issue/develop/develop.go:
  45: Use:   "develop {<number> | <url>}",

pkg/cmd/issue/edit/edit.go:
  52: Use:   "edit {<numbers> | <urls>}",

pkg/cmd/issue/lock/lock.go:
  128: Use:   "lock {<number> | <url>}",
  171: Use:   "unlock {<number> | <url>}",

pkg/cmd/issue/pin/pin.go:
  35: Use:   "pin {<number> | <url>}",

pkg/cmd/issue/reopen/reopen.go:
  36: Use:   "reopen {<number> | <url>}",

pkg/cmd/issue/transfer/transfer.go:
  35: Use:   "transfer {<number> | <url>} <destination-repo>",

pkg/cmd/issue/unpin/unpin.go:
  35: Use:   "unpin {<number> | <url>}",

pkg/cmd/issue/view/view.go:
  49: Use:   "view {<number> | <url>}",

pkg/cmd/pr/close/close.go:
  40: Use:   "close {<number> | <url> | <branch>}",

pkg/cmd/pr/reopen/reopen.go:
  32: Use:   "reopen {<number> | <url> | <branch>}",

pkg/cmd/repo/license/view/view.go:
  37: Use:   "view {<license-key> | <SPDX-ID>}",

The majority of the commands are using square brackets syntax:

curly braces (Use:\s+".* \{.*\}.*") (20 results)
square brackets (Use:\s+".* \[.*\].*") (75 results)

Expected vs actual behavior

The syntax should be consistent.

Logs

N/A

@iamazeem

Hey @iamazeem,

Our Primer Style Guidelines go into some detail on the different formats.

The gist is that:

Placeholders the user must replace are delimited by angled brackets gh pr view <issue-number>
Optional arguments are delimited by square brackets gh pr checkout [--web]
Optional mutually exclusive arguments are delimited by square brackets and separated by pipes gh pr view [<number> | <url>]
Required mutually exclusive arguments are delimited by curly braces and separated by pipes gh pr {view | create}

From your output the only obviously incorrect example is:

  38: Use:   "rename {<id> | <url>} <oldFilename> <newFilename>",

Where variable names are expected to be kebab cased e.g. rename {<id> | <url>} <old-filename> <new-filename>.

Are there any other examples you've spotted that violate the guidelines?

@williammartin

Hey @williammartin,

Thank you for your detailed comment! 👍

Found these cases violating Variable naming along with rename (as you pointed out above):

pkg/cmd/repo/license/view/view.go:
  37: Use:   "view {<license-key> | <SPDX-ID>}",

pkg/cmd/browse/browse.go:
  72: 		Use:  "browse [<number> | <path> | <commit-SHA>]",

The rest looks fine according to the guidelines.
I'll open dedicated issues if I notice anything.

Those are interesting cases since they are actually acronyms and maybe the casing isn't so bad.

However, I think we should just make them lower case anyway.

Acceptance Criteria

When I run gh repo license view --help
Then The usage uses lower-kebab-case

When I run gh browser --help
Then The usage uses lower-kebab-case

When I run gh gist rename --help
Then The usage uses lower-kebab-case

@williammartin

@williammartin: AC looks good. 👍
Just a typo: browser => browse

Navigation Menu

Repository navigation

Inconsistent use of curly braces and square brackets for command args syntax e.g. `{args}` and `[args]` respectively #10432

Describe the bug

Affected version

Steps to reproduce the behavior

Expected vs actual behavior

Logs

Acceptance Criteria

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Inconsistent use of curly braces and square brackets for command args syntax e.g. {args} and [args] respectively #10432

Description

Describe the bug

Affected version

Steps to reproduce the behavior

Expected vs actual behavior

Logs

Activity

williammartin commented on Feb 13, 2025

iamazeem commented on Feb 13, 2025

williammartin commented on Feb 14, 2025

Acceptance Criteria

iamazeem commented on Feb 14, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Inconsistent use of curly braces and square brackets for command args syntax e.g. `{args}` and `[args]` respectively #10432