1package root 2 3import ( 4 "github.com/MakeNowJust/heredoc" 5 "github.com/cli/cli/v2/pkg/text" 6 "github.com/spf13/cobra" 7) 8 9var HelpTopics = map[string]map[string]string{ 10 "mintty": { 11 "short": "Information about using gh with MinTTY", 12 "long": heredoc.Doc(` 13 MinTTY is the terminal emulator that comes by default with Git 14 for Windows. It has known issues with gh's ability to prompt a 15 user for input. 16 17 There are a few workarounds to make gh work with MinTTY: 18 19 - Reinstall Git for Windows, checking "Enable experimental support for pseudo consoles". 20 21 - Use a different terminal emulator with Git for Windows like Windows Terminal. 22 You can run "C:\Program Files\Git\bin\bash.exe" from any terminal emulator to continue 23 using all of the tooling in Git For Windows without MinTTY. 24 25 - Prefix invocations of gh with winpty, eg: "winpty gh auth login". 26 NOTE: this can lead to some UI bugs. 27 `), 28 }, 29 "environment": { 30 "short": "Environment variables that can be used with gh", 31 "long": heredoc.Doc(` 32 GH_TOKEN, GITHUB_TOKEN (in order of precedence): an authentication token for github.com 33 API requests. Setting this avoids being prompted to authenticate and takes precedence over 34 previously stored credentials. 35 36 GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN (in order of precedence): an authentication 37 token for API requests to GitHub Enterprise. When setting this, also set GH_HOST. 38 39 GH_HOST: specify the GitHub hostname for commands that would otherwise assume the 40 "github.com" host when not in a context of an existing repository. 41 42 GH_REPO: specify the GitHub repository in the "[HOST/]OWNER/REPO" format for commands 43 that otherwise operate on a local repository. 44 45 GH_EDITOR, GIT_EDITOR, VISUAL, EDITOR (in order of precedence): the editor tool to use 46 for authoring text. 47 48 GH_BROWSER, BROWSER (in order of precedence): the web browser to use for opening links. 49 50 DEBUG: set to any value to enable verbose output to standard error. Include values "api" 51 or "oauth" to print detailed information about HTTP requests or authentication flow. 52 53 GH_PAGER, PAGER (in order of precedence): a terminal paging program to send standard output 54 to, e.g. "less". 55 56 GLAMOUR_STYLE: the style to use for rendering Markdown. See 57 <https://github.com/charmbracelet/glamour#styles> 58 59 NO_COLOR: set to any value to avoid printing ANSI escape sequences for color output. 60 61 CLICOLOR: set to "0" to disable printing ANSI colors in output. 62 63 CLICOLOR_FORCE: set to a value other than "0" to keep ANSI colors in output 64 even when the output is piped. 65 66 GH_FORCE_TTY: set to any value to force terminal-style output even when the output is 67 redirected. When the value is a number, it is interpreted as the number of columns 68 available in the viewport. When the value is a percentage, it will be applied against 69 the number of columns available in the current viewport. 70 71 GH_NO_UPDATE_NOTIFIER: set to any value to disable update notifications. By default, gh 72 checks for new releases once every 24 hours and displays an upgrade notice on standard 73 error if a newer version was found. 74 75 GH_CONFIG_DIR: the directory where gh will store configuration files. Default: 76 "$XDG_CONFIG_HOME/gh" or "$HOME/.config/gh". 77 `), 78 }, 79 "reference": { 80 "short": "A comprehensive reference of all gh commands", 81 }, 82 "formatting": { 83 "short": "Formatting options for JSON data exported from gh", 84 "long": heredoc.Docf(` 85 Some gh commands support exporting the data as JSON as an alternative to their usual 86 line-based plain text output. This is suitable for passing structured data to scripts. 87 The JSON output is enabled with the %[1]s--json%[1]s option, followed by the list of fields 88 to fetch. Use the flag without a value to get the list of available fields. 89 90 The %[1]s--jq%[1]s option accepts a query in jq syntax and will print only the resulting 91 values that match the query. This is equivalent to piping the output to %[1]sjq -r%[1]s, 92 but does not require the jq utility to be installed on the system. To learn more 93 about the query syntax, see: <https://stedolan.github.io/jq/manual/v1.6/> 94 95 With %[1]s--template%[1]s, the provided Go template is rendered using the JSON data as input. 96 For the syntax of Go templates, see: <https://golang.org/pkg/text/template/> 97 98 The following functions are available in templates: 99 - %[1]sautocolor%[1]s: like %[1]scolor%[1]s, but only emits color to terminals 100 - %[1]scolor <style> <input>%[1]s: colorize input using <https://github.com/mgutz/ansi> 101 - %[1]sjoin <sep> <list>%[1]s: joins values in the list using a separator 102 - %[1]spluck <field> <list>%[1]s: collects values of a field from all items in the input 103 - %[1]stablerow <fields>...%[1]s: aligns fields in output vertically as a table 104 - %[1]stablerender%[1]s: renders fields added by tablerow in place 105 - %[1]stimeago <time>%[1]s: renders a timestamp as relative to now 106 - %[1]stimefmt <format> <time>%[1]s: formats a timestamp using Go's Time.Format function 107 - %[1]struncate <length> <input>%[1]s: ensures input fits within length 108 `, "`"), 109 "example": heredoc.Doc(` 110 # format issues as table 111 $ gh issue list --json number,title --template \ 112 '{{range .}}{{tablerow (printf "#%v" .number | autocolor "green") .title}}{{end}}' 113 114 # format a pull request using multiple tables with headers 115 $ gh pr view 3519 --json number,title,body,reviews,assignees --template \ 116 '{{printf "#%v" .number}} {{.title}} 117 118 {{.body}} 119 120 {{tablerow "ASSIGNEE" "NAME"}}{{range .assignees}}{{tablerow .login .name}}{{end}}{{tablerender}} 121 {{tablerow "REVIEWER" "STATE" "COMMENT"}}{{range .reviews}}{{tablerow .author.login .state .body}}{{end}} 122 ' 123 `), 124 }, 125} 126 127func NewHelpTopic(topic string) *cobra.Command { 128 cmd := &cobra.Command{ 129 Use: topic, 130 Short: HelpTopics[topic]["short"], 131 Long: HelpTopics[topic]["long"], 132 Example: HelpTopics[topic]["example"], 133 Hidden: true, 134 Annotations: map[string]string{ 135 "markdown:generate": "true", 136 "markdown:basename": "gh_help_" + topic, 137 }, 138 } 139 140 cmd.SetHelpFunc(helpTopicHelpFunc) 141 cmd.SetUsageFunc(helpTopicUsageFunc) 142 143 return cmd 144} 145 146func helpTopicHelpFunc(command *cobra.Command, args []string) { 147 command.Print(command.Long) 148 if command.Example != "" { 149 command.Printf("\n\nEXAMPLES\n") 150 command.Print(text.Indent(command.Example, " ")) 151 } 152} 153 154func helpTopicUsageFunc(command *cobra.Command) error { 155 command.Printf("Usage: gh help %s", command.Use) 156 return nil 157} 158