Documentation update
[tig] / tigrc.5.txt
1 tigrc(5)
2 ========
3
4 NAME
5 ----
6 tigrc - tig user configuration file
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 .............................................................................
13 *set*   variable *=* value
14 *bind*  keymap key action
15 *color* area fgcolor bgcolor [attributes]
16 .............................................................................
17
18
19 DESCRIPTION
20 -----------
21
22 You can permanently set an option by putting it in the `~/.tigrc` file.  The
23 file consists of a series of 'commands'.  Each line of the file may contain
24 only one command.
25
26 The hash mark ('#') is used as a 'comment' character. All text after the
27 comment character to the end of the line is ignored. You can use comments to
28 annotate your initialization file.
29
30
31 Set command
32 -----------
33
34 A few selective variables can be configured via the set command. The syntax
35 is:
36
37 [verse]
38 ..............................................................................
39         *set* variables *=* value
40 ..............................................................................
41
42 Examples:
43
44 --------------------------------------------------------------------------
45         set show-rev-graph = yes        # Show revision graph?
46         set line-number-interval = 5    # Interval between line numbers
47         set tab-size = 8                # Number of spaces pr tab 
48         set encoding = "UTF-8"          # Commit encoding
49 --------------------------------------------------------------------------
50
51 The type of variables are either bool, int, and string.
52
53 Valid bool values::
54
55         To set a bool variable to true use either "1", "true", or "yes".
56         Any other value will set the variable to false.
57
58 Valid int values::
59
60         A non-negative integer.
61
62 Valid string values::
63
64         A string of characters. Optionally, use either ' or " as delimiters.
65
66 Variables
67 ~~~~~~~~~
68
69 The following variables can be set:
70
71 'show-rev-graph' (bool)::
72
73         Show revision graph in the main view on startup. Can be toggled with
74         'g'.
75
76 'line-number-interval' (int)::
77
78         Interval between line numbers. Note, you have to toggle on line
79         numbering with 'n' or the `-n` command line option.  The default is to
80         number every line.
81
82 'tab-size' (int)::
83
84         Number of spaces per tab. The default is 8 spaces.
85
86 'commit-encoding' (string)::
87
88         The encoding used for commits. The default is UTF-8. Not this option
89         is shadowed by the "i18n.commitencoding" option in `.git/config`.
90
91
92 Bind command
93 ------------
94
95 Using bind commands keys can be mapped to an action when pressed in a given
96 key map. The syntax is:
97
98 [verse]
99 ..............................................................................
100         *bind* 'keymap' 'key' 'action'
101 ..............................................................................
102
103 Examples:
104
105 --------------------------------------------------------------------------
106         # A few keybindings
107         bind main w scroll-line-up
108         bind main s scroll-line-down
109         bind main space enter
110         bind diff a previous
111         bind diff d next
112         bind diff b move-first-line
113 --------------------------------------------------------------------------
114
115 Keys are mapped by first searching the keybindings for the current view, then
116 the keybindings for the *generic* keymap, and last the default keybindings.
117 Thus, the view keybindings shaddow the generic keybindings which shaddow the
118 built-in keybindings.
119
120 --
121
122 Keymaps::
123
124 Valid keymaps are: *main*, *diff*, *log*, *help*, *pager*, and *generic*.  Use
125 *generic* to set key mapping in all keymaps.
126
127 Key values::
128
129 Key values should never be quoted. Use either the ASCII value or one of the
130 following symbolic key names. Symbolic key names are case insensitive, Use
131 *Hash* to bind to the `#` key, since the hash mark is used as a comment
132 character.
133
134 *Enter*, *Space*, *Backspace*, *Tab*, *Escape*, *Left*, *Right*, *Up*, *Down*,
135 *Insert*, *Delete*, *Hash*, *Home*, *End*, *PageUp*, *PageDown*, *F1*, *F2*, *F3*,
136 *F4*, *F5*, *F6*, *F7*, *F8*, *F9*, *F10*, *F11*, *F12*.
137
138 Action names::
139
140 Valid action names are described below. Note, all names are
141 case-insensitive, and you may use '-', '_', and '.' interchangeably,
142 e.g. "view-main", "View.Main", and "VIEW_MAIN" are the same.
143
144 --
145
146 Actions
147 ~~~~~~~
148
149 ifdef::backend-xhtml11[]
150 [frame="none"]
151 `-----------------------`-----------------------------------------------------
152 endif::backend-xhtml11[]
153 View switching::
154 ------------------------------------------------------------------------------
155 view-main               Show main view
156 view-diff               Show diff view
157 view-log                Show log view
158 view-help               Show help page
159 view-pager              Show pager view
160 ------------------------------------------------------------------------------
161
162 ifdef::backend-xhtml11[]
163 [frame="none"]
164 `-----------------------`-----------------------------------------------------
165 endif::backend-xhtml11[]
166 View manipulation::
167 ------------------------------------------------------------------------------
168 enter                   Enter current line and scroll
169 next                    Move to next
170 previous                Move to previous
171 view-next               Move focus to next view
172 view-close              Close the current view
173 quit                    Close all views and quit
174 ------------------------------------------------------------------------------
175
176 ifdef::backend-xhtml11[]
177 [frame="none"]
178 `-----------------------`-----------------------------------------------------
179 endif::backend-xhtml11[]
180 Cursor navigation::
181 ------------------------------------------------------------------------------
182 move-up                 Move cursor one line up
183 move-down               Move cursor one line down
184 move-page_down          Move cursor one page down
185 move-page_up            Move cursor one page up
186 move-first_line         Move cursor to first line
187 move-last_line          Move cursor to last line
188 ------------------------------------------------------------------------------
189
190 ifdef::backend-xhtml11[]
191 [frame="none"]
192 `-----------------------`-----------------------------------------------------
193 endif::backend-xhtml11[]
194 Scrolling::
195 ------------------------------------------------------------------------------
196 scroll-line_up          Scroll one line up
197 scroll-line_down        Scroll one line down
198 scroll-page_up          Scroll one page up
199 scroll-page_down        Scroll one page down
200 ------------------------------------------------------------------------------
201
202 ifdef::backend-xhtml11[]
203 [frame="none"]
204 `-----------------------`-----------------------------------------------------
205 endif::backend-xhtml11[]
206 Misc::
207 ------------------------------------------------------------------------------
208 prompt                  Bring up the prompt
209 screen-update           Update the screen
210 screen-redraw           Redraw the screen
211 screen-resize           Resize the screen
212 show-version            Show version information
213 stop-loading            Stop all loading views
214 toggle-lineno           Toggle line numbers
215 toggle-rev_graph        Toggle revision graph visualization
216 ------------------------------------------------------------------------------
217
218
219 Color command
220 -------------
221
222 Color commands control highlighting and the user interface styles. If your
223 terminal supports color, these commands can be used to assign foreground and
224 backgound combinations to certain areas. Optionally, an attribute can be given
225 as the last parameter. The syntax is:
226
227 [verse]
228 ..............................................................................
229         *color* 'area' 'fgcolor' 'bgcolor' '[attributes]'
230 ..............................................................................
231
232 Examples:
233
234 ------------------------------------------------------------------------------
235         # Diff colors
236         color diff-header       yellow  default
237         color diff-index        blue    default
238         color diff-chunk        magenta default
239         # A strange looking cursor line
240         color cursor            red     default underline
241         # UI colors
242         color title-blur        white   blue
243         color title-focus       white   blue    bold
244 ------------------------------------------------------------------------------
245
246 Area names::
247
248         Valid area names are described below. Note, all names are
249         case-insensitive, and you may use '-', '_', and '.' interchangeably,
250         e.g. "Diff-Header", "DIFF_HEADER", and "diff.header" are the same.
251
252 Color names::
253
254         Valid colors include: *white*, *black*, *green*, *magenta*, *blue*,
255         *cyan*, *yellow*, *red*, *default*. Use *default* to refer to the
256         default terminal colors.
257
258 Attribute names::
259
260         Valid attributes include: *normal*, *blink*, *bold*, *dim*, *reverse*,
261         *standout*, and *underline*. Note, not all attributes may be supported
262         by the terminal.
263
264
265 UI colors
266 ~~~~~~~~~
267
268 --
269
270 Status window colors::
271
272 Appearance of the bottom window showing info messages.
273
274 *status*
275
276 Title window colors::
277
278 Appearence of the title windows when they are attached
279 to any backgrounded windows and the current window.
280
281 *title-blur*, *title-focus*
282
283 Cursor line colors::
284
285 *cursor*
286
287 Main view specific::
288
289 Appearance of the various columns in the main view, including the '~' used for
290 delimiting long author names and labels for tag and branch references.
291
292 *main-date*, *main-author*, *main-commit*, *main-delim*, *main-tag*,
293 *main-ref*
294
295 --
296
297 Highlighting
298 ~~~~~~~~~~~~
299
300 The colors and attributes for text that is not highlighted can be controlled
301 by changing the *default* color option.
302
303 --
304
305 Diff markup::
306
307 Options concerning diff start, chunks and lines added and deleted.
308
309 *diff-header*, *diff-chunk*, *diff-add*, *diff-del*
310
311 Enhanced git diff markup::
312
313 Extra diff information emitted by the git diff machinery, such as mode
314 changes, rename detection, and similarity.
315
316 *diff-oldmode*, *diff-newmode*, *diff-copy-from*, *diff-copy-to*,
317 *diff-rename-from*, *diff-rename-to*, *diff-similarity* *diff-dissimilarity*
318 *diff-tree*, *diff-index*
319
320 Pretty print commit headers::
321
322 Commit diffs and the revision logs are usually formatted using pretty printed
323 headers , unless `--pretty=raw` was given. This includes lines, such as merge
324 info, commit ID, and author and comitter date.
325
326 *pp-author*, *pp-commit*, *pp-merge*, *pp-date*, *pp-adate*, *pp-cdate*
327
328 Raw commit header::
329
330 Usually shown when `--pretty=raw` is given, however 'commit' is pretty much
331 omnipresent.
332
333 *commit*, *parent*, *tree*, *author*, *committer*
334
335 Commit message::
336
337 For now only `Signed-off-by` lines are colorized.
338
339 *signoff*
340
341 --
342
343 COPYRIGHT
344 ---------
345 Copyright (c) 2006 Jonas Fonseca <fonseca@diku.dk>
346
347 Licensed under the terms of the GNU General Public License.
348
349 SEE ALSO
350 --------
351 gitlink:tig[1] and the http://jonas.nitro.dk/tig/tig.html[tig manual].