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