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