help: clean up kfmclient munging
[git/git.git] / builtin / help.c
1 /*
2 * Builtin help command
3 */
4 #include "cache.h"
5 #include "builtin.h"
6 #include "exec_cmd.h"
7 #include "parse-options.h"
8 #include "run-command.h"
9 #include "column.h"
10 #include "help.h"
11
12 #ifndef DEFAULT_HELP_FORMAT
13 #define DEFAULT_HELP_FORMAT "man"
14 #endif
15
16 static struct man_viewer_list {
17 struct man_viewer_list *next;
18 char name[FLEX_ARRAY];
19 } *man_viewer_list;
20
21 static struct man_viewer_info_list {
22 struct man_viewer_info_list *next;
23 const char *info;
24 char name[FLEX_ARRAY];
25 } *man_viewer_info_list;
26
27 enum help_format {
28 HELP_FORMAT_NONE,
29 HELP_FORMAT_MAN,
30 HELP_FORMAT_INFO,
31 HELP_FORMAT_WEB
32 };
33
34 static const char *html_path;
35
36 static int show_all = 0;
37 static int show_guides = 0;
38 static unsigned int colopts;
39 static enum help_format help_format = HELP_FORMAT_NONE;
40 static struct option builtin_help_options[] = {
41 OPT_BOOL('a', "all", &show_all, N_("print all available commands")),
42 OPT_BOOL('g', "guides", &show_guides, N_("print list of useful guides")),
43 OPT_SET_INT('m', "man", &help_format, N_("show man page"), HELP_FORMAT_MAN),
44 OPT_SET_INT('w', "web", &help_format, N_("show manual in web browser"),
45 HELP_FORMAT_WEB),
46 OPT_SET_INT('i', "info", &help_format, N_("show info page"),
47 HELP_FORMAT_INFO),
48 OPT_END(),
49 };
50
51 static const char * const builtin_help_usage[] = {
52 N_("git help [--all] [--guides] [--man | --web | --info] [<command>]"),
53 NULL
54 };
55
56 static enum help_format parse_help_format(const char *format)
57 {
58 if (!strcmp(format, "man"))
59 return HELP_FORMAT_MAN;
60 if (!strcmp(format, "info"))
61 return HELP_FORMAT_INFO;
62 if (!strcmp(format, "web") || !strcmp(format, "html"))
63 return HELP_FORMAT_WEB;
64 die(_("unrecognized help format '%s'"), format);
65 }
66
67 static const char *get_man_viewer_info(const char *name)
68 {
69 struct man_viewer_info_list *viewer;
70
71 for (viewer = man_viewer_info_list; viewer; viewer = viewer->next)
72 {
73 if (!strcasecmp(name, viewer->name))
74 return viewer->info;
75 }
76 return NULL;
77 }
78
79 static int check_emacsclient_version(void)
80 {
81 struct strbuf buffer = STRBUF_INIT;
82 struct child_process ec_process = CHILD_PROCESS_INIT;
83 const char *argv_ec[] = { "emacsclient", "--version", NULL };
84 int version;
85
86 /* emacsclient prints its version number on stderr */
87 ec_process.argv = argv_ec;
88 ec_process.err = -1;
89 ec_process.stdout_to_stderr = 1;
90 if (start_command(&ec_process))
91 return error(_("Failed to start emacsclient."));
92
93 strbuf_read(&buffer, ec_process.err, 20);
94 close(ec_process.err);
95
96 /*
97 * Don't bother checking return value, because "emacsclient --version"
98 * seems to always exits with code 1.
99 */
100 finish_command(&ec_process);
101
102 if (!starts_with(buffer.buf, "emacsclient")) {
103 strbuf_release(&buffer);
104 return error(_("Failed to parse emacsclient version."));
105 }
106
107 strbuf_remove(&buffer, 0, strlen("emacsclient"));
108 version = atoi(buffer.buf);
109
110 if (version < 22) {
111 strbuf_release(&buffer);
112 return error(_("emacsclient version '%d' too old (< 22)."),
113 version);
114 }
115
116 strbuf_release(&buffer);
117 return 0;
118 }
119
120 static void exec_woman_emacs(const char *path, const char *page)
121 {
122 if (!check_emacsclient_version()) {
123 /* This works only with emacsclient version >= 22. */
124 struct strbuf man_page = STRBUF_INIT;
125
126 if (!path)
127 path = "emacsclient";
128 strbuf_addf(&man_page, "(woman \"%s\")", page);
129 execlp(path, "emacsclient", "-e", man_page.buf, (char *)NULL);
130 warning(_("failed to exec '%s': %s"), path, strerror(errno));
131 }
132 }
133
134 static void exec_man_konqueror(const char *path, const char *page)
135 {
136 const char *display = getenv("DISPLAY");
137 if (display && *display) {
138 struct strbuf man_page = STRBUF_INIT;
139 const char *filename = "kfmclient";
140
141 /* It's simpler to launch konqueror using kfmclient. */
142 if (path) {
143 size_t len;
144 if (strip_suffix(path, "/konqueror", &len))
145 path = xstrfmt("%.*s/kfmclient", (int)len, path);
146 filename = basename((char *)path);
147 } else
148 path = "kfmclient";
149 strbuf_addf(&man_page, "man:%s(1)", page);
150 execlp(path, filename, "newTab", man_page.buf, (char *)NULL);
151 warning(_("failed to exec '%s': %s"), path, strerror(errno));
152 }
153 }
154
155 static void exec_man_man(const char *path, const char *page)
156 {
157 if (!path)
158 path = "man";
159 execlp(path, "man", page, (char *)NULL);
160 warning(_("failed to exec '%s': %s"), path, strerror(errno));
161 }
162
163 static void exec_man_cmd(const char *cmd, const char *page)
164 {
165 struct strbuf shell_cmd = STRBUF_INIT;
166 strbuf_addf(&shell_cmd, "%s %s", cmd, page);
167 execl(SHELL_PATH, SHELL_PATH, "-c", shell_cmd.buf, (char *)NULL);
168 warning(_("failed to exec '%s': %s"), cmd, strerror(errno));
169 }
170
171 static void add_man_viewer(const char *name)
172 {
173 struct man_viewer_list **p = &man_viewer_list;
174 size_t len = strlen(name);
175
176 while (*p)
177 p = &((*p)->next);
178 *p = xcalloc(1, (sizeof(**p) + len + 1));
179 strncpy((*p)->name, name, len);
180 }
181
182 static int supported_man_viewer(const char *name, size_t len)
183 {
184 return (!strncasecmp("man", name, len) ||
185 !strncasecmp("woman", name, len) ||
186 !strncasecmp("konqueror", name, len));
187 }
188
189 static void do_add_man_viewer_info(const char *name,
190 size_t len,
191 const char *value)
192 {
193 struct man_viewer_info_list *new = xcalloc(1, sizeof(*new) + len + 1);
194
195 strncpy(new->name, name, len);
196 new->info = xstrdup(value);
197 new->next = man_viewer_info_list;
198 man_viewer_info_list = new;
199 }
200
201 static int add_man_viewer_path(const char *name,
202 size_t len,
203 const char *value)
204 {
205 if (supported_man_viewer(name, len))
206 do_add_man_viewer_info(name, len, value);
207 else
208 warning(_("'%s': path for unsupported man viewer.\n"
209 "Please consider using 'man.<tool>.cmd' instead."),
210 name);
211
212 return 0;
213 }
214
215 static int add_man_viewer_cmd(const char *name,
216 size_t len,
217 const char *value)
218 {
219 if (supported_man_viewer(name, len))
220 warning(_("'%s': cmd for supported man viewer.\n"
221 "Please consider using 'man.<tool>.path' instead."),
222 name);
223 else
224 do_add_man_viewer_info(name, len, value);
225
226 return 0;
227 }
228
229 static int add_man_viewer_info(const char *var, const char *value)
230 {
231 const char *name, *subkey;
232 int namelen;
233
234 if (parse_config_key(var, "man", &name, &namelen, &subkey) < 0 || !name)
235 return 0;
236
237 if (!strcmp(subkey, "path")) {
238 if (!value)
239 return config_error_nonbool(var);
240 return add_man_viewer_path(name, namelen, value);
241 }
242 if (!strcmp(subkey, "cmd")) {
243 if (!value)
244 return config_error_nonbool(var);
245 return add_man_viewer_cmd(name, namelen, value);
246 }
247
248 return 0;
249 }
250
251 static int git_help_config(const char *var, const char *value, void *cb)
252 {
253 if (starts_with(var, "column."))
254 return git_column_config(var, value, "help", &colopts);
255 if (!strcmp(var, "help.format")) {
256 if (!value)
257 return config_error_nonbool(var);
258 help_format = parse_help_format(value);
259 return 0;
260 }
261 if (!strcmp(var, "help.htmlpath")) {
262 if (!value)
263 return config_error_nonbool(var);
264 html_path = xstrdup(value);
265 return 0;
266 }
267 if (!strcmp(var, "man.viewer")) {
268 if (!value)
269 return config_error_nonbool(var);
270 add_man_viewer(value);
271 return 0;
272 }
273 if (starts_with(var, "man."))
274 return add_man_viewer_info(var, value);
275
276 return git_default_config(var, value, cb);
277 }
278
279 static struct cmdnames main_cmds, other_cmds;
280
281 static int is_git_command(const char *s)
282 {
283 if (is_builtin(s))
284 return 1;
285
286 load_command_list("git-", &main_cmds, &other_cmds);
287 return is_in_cmdlist(&main_cmds, s) ||
288 is_in_cmdlist(&other_cmds, s);
289 }
290
291 static const char *cmd_to_page(const char *git_cmd)
292 {
293 if (!git_cmd)
294 return "git";
295 else if (starts_with(git_cmd, "git"))
296 return git_cmd;
297 else if (is_git_command(git_cmd))
298 return xstrfmt("git-%s", git_cmd);
299 else
300 return xstrfmt("git%s", git_cmd);
301 }
302
303 static void setup_man_path(void)
304 {
305 struct strbuf new_path = STRBUF_INIT;
306 const char *old_path = getenv("MANPATH");
307 char *git_man_path = system_path(GIT_MAN_PATH);
308
309 /* We should always put ':' after our path. If there is no
310 * old_path, the ':' at the end will let 'man' to try
311 * system-wide paths after ours to find the manual page. If
312 * there is old_path, we need ':' as delimiter. */
313 strbuf_addstr(&new_path, git_man_path);
314 strbuf_addch(&new_path, ':');
315 if (old_path)
316 strbuf_addstr(&new_path, old_path);
317
318 free(git_man_path);
319 setenv("MANPATH", new_path.buf, 1);
320
321 strbuf_release(&new_path);
322 }
323
324 static void exec_viewer(const char *name, const char *page)
325 {
326 const char *info = get_man_viewer_info(name);
327
328 if (!strcasecmp(name, "man"))
329 exec_man_man(info, page);
330 else if (!strcasecmp(name, "woman"))
331 exec_woman_emacs(info, page);
332 else if (!strcasecmp(name, "konqueror"))
333 exec_man_konqueror(info, page);
334 else if (info)
335 exec_man_cmd(info, page);
336 else
337 warning(_("'%s': unknown man viewer."), name);
338 }
339
340 static void show_man_page(const char *git_cmd)
341 {
342 struct man_viewer_list *viewer;
343 const char *page = cmd_to_page(git_cmd);
344 const char *fallback = getenv("GIT_MAN_VIEWER");
345
346 setup_man_path();
347 for (viewer = man_viewer_list; viewer; viewer = viewer->next)
348 {
349 exec_viewer(viewer->name, page); /* will return when unable */
350 }
351 if (fallback)
352 exec_viewer(fallback, page);
353 exec_viewer("man", page);
354 die(_("no man viewer handled the request"));
355 }
356
357 static void show_info_page(const char *git_cmd)
358 {
359 const char *page = cmd_to_page(git_cmd);
360 setenv("INFOPATH", system_path(GIT_INFO_PATH), 1);
361 execlp("info", "info", "gitman", page, (char *)NULL);
362 die(_("no info viewer handled the request"));
363 }
364
365 static void get_html_page_path(struct strbuf *page_path, const char *page)
366 {
367 struct stat st;
368 char *to_free = NULL;
369
370 if (!html_path)
371 html_path = to_free = system_path(GIT_HTML_PATH);
372
373 /* Check that we have a git documentation directory. */
374 if (!strstr(html_path, "://")) {
375 if (stat(mkpath("%s/git.html", html_path), &st)
376 || !S_ISREG(st.st_mode))
377 die("'%s': not a documentation directory.", html_path);
378 }
379
380 strbuf_init(page_path, 0);
381 strbuf_addf(page_path, "%s/%s.html", html_path, page);
382 free(to_free);
383 }
384
385 /*
386 * If open_html is not defined in a platform-specific way (see for
387 * example compat/mingw.h), we use the script web--browse to display
388 * HTML.
389 */
390 #ifndef open_html
391 static void open_html(const char *path)
392 {
393 execl_git_cmd("web--browse", "-c", "help.browser", path, (char *)NULL);
394 }
395 #endif
396
397 static void show_html_page(const char *git_cmd)
398 {
399 const char *page = cmd_to_page(git_cmd);
400 struct strbuf page_path; /* it leaks but we exec bellow */
401
402 get_html_page_path(&page_path, page);
403
404 open_html(page_path.buf);
405 }
406
407 static struct {
408 const char *name;
409 const char *help;
410 } common_guides[] = {
411 { "attributes", N_("Defining attributes per path") },
412 { "everyday", N_("Everyday Git With 20 Commands Or So") },
413 { "glossary", N_("A Git glossary") },
414 { "ignore", N_("Specifies intentionally untracked files to ignore") },
415 { "modules", N_("Defining submodule properties") },
416 { "revisions", N_("Specifying revisions and ranges for Git") },
417 { "tutorial", N_("A tutorial introduction to Git (for version 1.5.1 or newer)") },
418 { "workflows", N_("An overview of recommended workflows with Git") },
419 };
420
421 static void list_common_guides_help(void)
422 {
423 int i, longest = 0;
424
425 for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
426 if (longest < strlen(common_guides[i].name))
427 longest = strlen(common_guides[i].name);
428 }
429
430 puts(_("The common Git guides are:\n"));
431 for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
432 printf(" %s ", common_guides[i].name);
433 mput_char(' ', longest - strlen(common_guides[i].name));
434 puts(_(common_guides[i].help));
435 }
436 putchar('\n');
437 }
438
439 int cmd_help(int argc, const char **argv, const char *prefix)
440 {
441 int nongit;
442 char *alias;
443 enum help_format parsed_help_format;
444
445 argc = parse_options(argc, argv, prefix, builtin_help_options,
446 builtin_help_usage, 0);
447 parsed_help_format = help_format;
448
449 if (show_all) {
450 git_config(git_help_config, NULL);
451 printf(_("usage: %s%s"), _(git_usage_string), "\n\n");
452 load_command_list("git-", &main_cmds, &other_cmds);
453 list_commands(colopts, &main_cmds, &other_cmds);
454 }
455
456 if (show_guides)
457 list_common_guides_help();
458
459 if (show_all || show_guides) {
460 printf("%s\n", _(git_more_info_string));
461 /*
462 * We're done. Ignore any remaining args
463 */
464 return 0;
465 }
466
467 if (!argv[0]) {
468 printf(_("usage: %s%s"), _(git_usage_string), "\n\n");
469 list_common_cmds_help();
470 printf("\n%s\n", _(git_more_info_string));
471 return 0;
472 }
473
474 setup_git_directory_gently(&nongit);
475 git_config(git_help_config, NULL);
476
477 if (parsed_help_format != HELP_FORMAT_NONE)
478 help_format = parsed_help_format;
479 if (help_format == HELP_FORMAT_NONE)
480 help_format = parse_help_format(DEFAULT_HELP_FORMAT);
481
482 alias = alias_lookup(argv[0]);
483 if (alias && !is_git_command(argv[0])) {
484 printf_ln(_("`git %s' is aliased to `%s'"), argv[0], alias);
485 free(alias);
486 return 0;
487 }
488
489 switch (help_format) {
490 case HELP_FORMAT_NONE:
491 case HELP_FORMAT_MAN:
492 show_man_page(argv[0]);
493 break;
494 case HELP_FORMAT_INFO:
495 show_info_page(argv[0]);
496 break;
497 case HELP_FORMAT_WEB:
498 show_html_page(argv[0]);
499 break;
500 }
501
502 return 0;
503 }