Merge branch 'cc/help'
[git/git.git] / Documentation / git-help.txt
CommitLineData
0f6f195b 1git-help(1)
dada0c12 2===========
0f6f195b
CC
3
4NAME
5----
6git-help - display help information about git
7
8SYNOPSIS
9--------
70087cdb 10'git help' [-a|--all|-i|--info|-m|--man|-w|--web] [COMMAND]
0f6f195b
CC
11
12DESCRIPTION
13-----------
14
15With no options and no COMMAND given, the synopsis of the 'git'
16command and a list of the most commonly used git commands are printed
17on the standard output.
18
19If the option '--all' or '-a' is given, then all available commands are
20printed on the standard output.
21
22If a git command is named, a manual page for that command is brought
45533d26 23up. The 'man' program is used by default for this purpose, but this
02ff6250 24can be overridden by other options or configuration variables.
0f6f195b
CC
25
26Note that 'git --help ...' is identical as 'git help ...' because the
27former is internally converted into the latter.
28
29OPTIONS
30-------
31-a|--all::
0f6f195b 32 Prints all the available commands on the standard output. This
02ff6250 33 option supersedes any other option.
0f6f195b 34
45533d26 35-i|--info::
b5578f33
CC
36 Display manual page for the command in the 'info' format. The
37 'info' program will be used for that purpose.
45533d26 38
70087cdb 39-m|--man::
b5578f33
CC
40 Display manual page for the command in the 'man' format. This
41 option may be used to override a value set in the
42 'help.format' configuration variable.
43+
44By default the 'man' program will be used to display the manual page,
45but the 'man.viewer' configuration variable may be used to choose
b8322ea8 46other display programs (see below).
70087cdb 47
c07a07c5 48-w|--web::
b5578f33
CC
49 Display manual page for the command in the 'web' (HTML)
50 format. A web browser will be used for that purpose.
c07a07c5
CC
51+
52The web browser can be specified using the configuration variable
53'help.browser', or 'web.browser' if the former is not set. If none of
5884f1fe 54these config variables is set, the 'git-web--browse' helper script
cb45f83c
CC
55(called by 'git-help') will pick a suitable default. See
56linkgit:git-web--browse[1] for more information about this.
c07a07c5 57
70087cdb
CC
58CONFIGURATION VARIABLES
59-----------------------
60
b8322ea8
CC
61help.format
62~~~~~~~~~~~
63
70087cdb
CC
64If no command line option is passed, the 'help.format' configuration
65variable will be checked. The following values are supported for this
66variable; they make 'git-help' behave as their corresponding command
67line option:
68
69* "man" corresponds to '-m|--man',
70* "info" corresponds to '-i|--info',
b5578f33 71* "web" or "html" correspond to '-w|--web'.
70087cdb 72
b8322ea8
CC
73help.browser, web.browser and browser.<tool>.path
74~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75
70087cdb 76The 'help.browser', 'web.browser' and 'browser.<tool>.path' will also
02ff6250 77be checked if the 'web' format is chosen (either by command line
70087cdb 78option or configuration variable). See '-w|--web' in the OPTIONS
cb45f83c 79section above and linkgit:git-web--browse[1].
70087cdb 80
b8322ea8
CC
81man.viewer
82~~~~~~~~~~
83
b5578f33 84The 'man.viewer' config variable will be checked if the 'man' format
0bb64009 85is chosen. The following values are currently supported:
b5578f33
CC
86
87* "man": use the 'man' program as usual,
88* "woman": use 'emacsclient' to launch the "woman" mode in emacs
89(this only works starting with emacsclient versions 22),
0bb64009
CC
90* "konqueror": use 'kfmclient' to open the man page in a new konqueror
91tab (see 'Note about konqueror' below).
b5578f33 92
0bb64009
CC
93Values for other tools can be used if there is a corresponding
94'man.<tool>.cmd' configuration entry (see below).
95
96Multiple values may be given to the 'man.viewer' configuration
97variable. Their corresponding programs will be tried in the order
98listed in the configuration file.
b8322ea8
CC
99
100For example, this configuration:
101
0bb64009 102------------------------------------------------
b8322ea8
CC
103 [man]
104 viewer = konqueror
105 viewer = woman
0bb64009 106------------------------------------------------
b8322ea8
CC
107
108will try to use konqueror first. But this may fail (for example if
109DISPLAY is not set) and in that case emacs' woman mode will be tried.
110
63f671a4 111If everything fails the 'man' program will be tried anyway.
b8322ea8 112
7e8114c0
CC
113man.<tool>.path
114~~~~~~~~~~~~~~~
115
116You can explicitly provide a full path to your preferred man viewer by
117setting the configuration variable 'man.<tool>.path'. For example, you
118can configure the absolute path to konqueror by setting
119'man.konqueror.path'. Otherwise, 'git help' assumes the tool is
120available in PATH.
121
0bb64009
CC
122man.<tool>.cmd
123~~~~~~~~~~~~~~
124
125When the man viewer, specified by the 'man.viewer' configuration
126variables, is not among the supported ones, then the corresponding
127'man.<tool>.cmd' configuration variable will be looked up. If this
128variable exists then the specified tool will be treated as a custom
129command and a shell eval will be used to run the command with the man
130page passed as arguments.
131
132Note about konqueror
133~~~~~~~~~~~~~~~~~~~~
134
135When 'konqueror' is specified in the 'man.viewer' configuration
136variable, we launch 'kfmclient' to try to open the man page on an
137already opened konqueror in a new tab if possible.
138
139For consistency, we also try such a trick if 'man.konqueror.path' is
140set to something like 'A_PATH_TO/konqueror'. That means we will try to
141launch 'A_PATH_TO/kfmclient' instead.
142
143If you really want to use 'konqueror', then you can use something like
144the following:
145
146------------------------------------------------
147 [man]
148 viewer = konq
149
150 [man "konq"]
151 cmd = A_PATH_TO/konqueror
152------------------------------------------------
153
b8322ea8
CC
154Note about git config --global
155~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
156
b5578f33
CC
157Note that all these configuration variables should probably be set
158using the '--global' flag, for example like this:
70087cdb
CC
159
160------------------------------------------------
161$ git config --global help.format web
162$ git config --global web.browser firefox
163------------------------------------------------
164
165as they are probably more user specific than repository specific.
5162e697 166See linkgit:git-config[1] for more information about this.
70087cdb 167
0f6f195b
CC
168Author
169------
170Written by Junio C Hamano <gitster@pobox.com> and the git-list
171<git@vger.kernel.org>.
172
173Documentation
174-------------
5162e697 175Initial documentation was part of the linkgit:git[7] man page.
0f6f195b
CC
176Christian Couder <chriscool@tuxfamily.org> extracted and rewrote it a
177little. Maintenance is done by the git-list <git@vger.kernel.org>.
178
179GIT
180---
5162e697 181Part of the linkgit:git[7] suite