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