Skip to content

CLI Help Display Parity - Batch 11 (51-55)

The CLI and HTML versions of our command help are built from the same source, but we don't have parity in how the display is formatted. The Example sections of cobra.Command calls often have a mix of non-semantic and non-standard markup that can look strange in Markdown. Going forward, we would like to use this style guide for any Example fields:

Implementation Plan:

  • Commands, like examples of glab usage, should start with a $
    • Ex: $ glab mr view --web
  • Results, showing the result of these commands, should start with a >
    • Ex: > ✓ Logged in to gitlab.com as garyh (/Users/gary/.config/glab-cli/config.yml)
  • Comments, which are really lines that are not commands or results, should start with a #
    • Ex: # Here is a neat thing you can do with glab

Lets use the command for glab duo ask as an example:

	duoAskCmd := &cobra.Command{
		Use:   "ask <prompt>",
		Short: "Generate Git commands from natural language.",
		Long: heredoc.Doc(`
			Generate Git commands from natural language.
		`),
		Example: heredoc.Doc(`
			$ glab duo ask list last 10 commit titles

			# => A list of Git commands to show the titles of the latest 10 commits with an explanation and an option to execute the commands.
		`),

The Example attribute here has the correct format for an example command, but the result is formatted as a comment and has an extra =>. Let's correct this as:

	duoAskCmd := &cobra.Command{
		Use:   "ask <prompt>",
		Short: "Generate Git commands from natural language.",
		Long: heredoc.Doc(`
			Generate Git commands from natural language.
		`),
		Example: heredoc.Doc(`
            # Get a list of Git commands to show the titles of the latest 10 commits
			$ glab duo ask list last 10 commit titles
			> A list of Git commands to show the titles of the latest 10 commits with an explanation and an option to execute the commands.
		`),

To keep merge request size down, we'd like to keep this to 5 files at a time. There may be a batch of files that don't need any changes! Please just mention that in the issue and we can close it.

Files to review:

Edited by Gary Holtz
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information