Use 3 as the minimum width of formatted line numbers
[tig] / tigrc.5.txt
CommitLineData
cb7f42cd
JF
1tigrc(5)
2========
3
4NAME
5----
6tigrc - tig user configuration file
7
2bc4f7bd 8
cb7f42cd
JF
9SYNOPSIS
10--------
11[verse]
12.............................................................................
c3c24b0b
JF
13*set* 'variable' *=* 'value'
14*bind* 'keymap' 'key' 'action'
15*color* 'area' 'fgcolor' 'bgcolor' '[attributes]'
cb7f42cd
JF
16.............................................................................
17
2bc4f7bd 18
cb7f42cd
JF
19DESCRIPTION
20-----------
cb7f42cd 21
2bc4f7bd
JF
22You can permanently set an option by putting it in the `~/.tigrc` file. The
23file consists of a series of 'commands'. Each line of the file may contain
24only one command.
cb7f42cd 25
2bc4f7bd
JF
26The hash mark ('#') is used as a 'comment' character. All text after the
27comment character to the end of the line is ignored. You can use comments to
28annotate your initialization file.
cb7f42cd 29
cb7f42cd 30
2bc4f7bd
JF
31Set command
32-----------
cb7f42cd 33
2bc4f7bd
JF
34A few selective variables can be configured via the set command. The syntax
35is:
cb7f42cd 36
2bc4f7bd
JF
37[verse]
38..............................................................................
c3c24b0b 39*set* variables *=* value
2bc4f7bd 40..............................................................................
cb7f42cd 41
2bc4f7bd 42Examples:
cb7f42cd 43
2bc4f7bd 44--------------------------------------------------------------------------
8d762458
DV
45set show-author = yes # Show author?
46set show-date = yes # Show commit date?
c3c24b0b 47set show-rev-graph = yes # Show revision graph?
8d762458
DV
48set show-refs = yes # Show references?
49set show-line-numbers = no # Show line numbers?
c3c24b0b
JF
50set line-number-interval = 5 # Interval between line numbers
51set tab-size = 8 # Number of spaces per tab
52set encoding = "UTF-8" # Commit encoding
2bc4f7bd 53--------------------------------------------------------------------------
cb7f42cd 54
2bc4f7bd 55The type of variables are either bool, int, and string.
cb7f42cd 56
2bc4f7bd 57Valid bool values::
cb7f42cd 58
2bc4f7bd
JF
59 To set a bool variable to true use either "1", "true", or "yes".
60 Any other value will set the variable to false.
cb7f42cd 61
2bc4f7bd 62Valid int values::
cb7f42cd 63
2bc4f7bd 64 A non-negative integer.
cb7f42cd 65
2bc4f7bd 66Valid string values::
cb7f42cd 67
2bc4f7bd 68 A string of characters. Optionally, use either ' or " as delimiters.
cb7f42cd 69
2bc4f7bd
JF
70Variables
71~~~~~~~~~
cb7f42cd 72
2bc4f7bd 73The following variables can be set:
cb7f42cd 74
e97cce13
JF
75'show-author' (bool)::
76'show-date' (bool)::
2bc4f7bd 77'show-rev-graph' (bool)::
e97cce13 78'show-refs' (bool)::
cb7f42cd 79
e97cce13
JF
80 Whether to show author, date, revision graph, and references
81 (branches, tags, and remotes) in the main view on start-up. Can all be
82 toggled.
cb7f42cd 83
2bc4f7bd 84'line-number-interval' (int)::
cb7f42cd 85
2bc4f7bd
JF
86 Interval between line numbers. Note, you have to toggle on line
87 numbering with 'n' or the `-n` command line option. The default is to
88 number every line.
cb7f42cd 89
2bc4f7bd 90'tab-size' (int)::
cb7f42cd 91
2bc4f7bd 92 Number of spaces per tab. The default is 8 spaces.
cb7f42cd 93
2bc4f7bd 94'commit-encoding' (string)::
cb7f42cd 95
2bc4f7bd
JF
96 The encoding used for commits. The default is UTF-8. Not this option
97 is shadowed by the "i18n.commitencoding" option in `.git/config`.
cb7f42cd 98
cb7f42cd 99
2bc4f7bd
JF
100Bind command
101------------
cb7f42cd 102
2bc4f7bd
JF
103Using bind commands keys can be mapped to an action when pressed in a given
104key map. The syntax is:
cb7f42cd 105
2bc4f7bd
JF
106[verse]
107..............................................................................
c3c24b0b 108*bind* 'keymap' 'key' 'action'
2bc4f7bd
JF
109..............................................................................
110
111Examples:
112
113--------------------------------------------------------------------------
c3c24b0b
JF
114# A few keybindings
115bind main w scroll-line-up
116bind main s scroll-line-down
117bind main space enter
118bind diff a previous
119bind diff d next
120bind diff b move-first-line
121# 'unbind' the default quit key binding
122bind main Q none
123# An external command to update from upstream
124bind generic F !git fetch
125# Cherry-pick current commit unto current branch
126bind generic C !git cherry-pick %(commit)
2bc4f7bd
JF
127--------------------------------------------------------------------------
128
129Keys are mapped by first searching the keybindings for the current view, then
130the keybindings for the *generic* keymap, and last the default keybindings.
f7ffec06 131Thus, the view keybindings shadow the generic keybindings which Shadow the
2bc4f7bd
JF
132built-in keybindings.
133
134--
135
136Keymaps::
137
f9a044a4
JF
138Valid keymaps are: *main*, *diff*, *log*, *help*, *pager*, *status*, *stage*,
139and *generic*. Use *generic* to set key mapping in all keymaps.
2bc4f7bd
JF
140
141Key values::
142
143Key values should never be quoted. Use either the ASCII value or one of the
144following symbolic key names. Symbolic key names are case insensitive, Use
145*Hash* to bind to the `#` key, since the hash mark is used as a comment
146character.
147
148*Enter*, *Space*, *Backspace*, *Tab*, *Escape*, *Left*, *Right*, *Up*, *Down*,
149*Insert*, *Delete*, *Hash*, *Home*, *End*, *PageUp*, *PageDown*, *F1*, *F2*, *F3*,
150*F4*, *F5*, *F6*, *F7*, *F8*, *F9*, *F10*, *F11*, *F12*.
151
152Action names::
153
154Valid action names are described below. Note, all names are
155case-insensitive, and you may use '-', '_', and '.' interchangeably,
156e.g. "view-main", "View.Main", and "VIEW_MAIN" are the same.
157
158--
159
160Actions
161~~~~~~~
162
9eb14b72
JF
163Apart from the action names listed below, all actions starting with a '!' will
164be available as an external command. External commands can contain variable
165names that will be substituted before the command is run. Valid variable names
166are "%(head)", "%(commit)", and "%(blob)".
167
168As an example, the following external command will save the current commit as
169a patch file: "!git format-patch %(commit)^..%(commit)".
170
2bc4f7bd
JF
171ifdef::backend-xhtml11[]
172[frame="none"]
173`-----------------------`-----------------------------------------------------
174endif::backend-xhtml11[]
765595f3 175View switching:
2bc4f7bd
JF
176------------------------------------------------------------------------------
177view-main Show main view
178view-diff Show diff view
179view-log Show log view
9d6976b9
JF
180view-tree Show tree view
181view-blob Show blob view
8a680988 182view-blame Show blame view
173d76ea 183view-status Show status view
f9a044a4 184view-stage Show stage view
2bc4f7bd 185view-pager Show pager view
9d6976b9 186view-help Show help page
2bc4f7bd
JF
187------------------------------------------------------------------------------
188
189ifdef::backend-xhtml11[]
190[frame="none"]
191`-----------------------`-----------------------------------------------------
192endif::backend-xhtml11[]
765595f3 193View manipulation:
2bc4f7bd
JF
194------------------------------------------------------------------------------
195enter Enter current line and scroll
196next Move to next
197previous Move to previous
198view-next Move focus to next view
272818ea 199refresh Reload and refresh view
47dd652b 200maximize Maximize the current view
2bc4f7bd
JF
201view-close Close the current view
202quit Close all views and quit
203------------------------------------------------------------------------------
204
205ifdef::backend-xhtml11[]
206[frame="none"]
207`-----------------------`-----------------------------------------------------
208endif::backend-xhtml11[]
765595f3 209Cursor navigation:
2bc4f7bd
JF
210------------------------------------------------------------------------------
211move-up Move cursor one line up
212move-down Move cursor one line down
9d6976b9
JF
213move-page-down Move cursor one page down
214move-page-up Move cursor one page up
215move-first-line Move cursor to first line
216move-last-line Move cursor to last line
2bc4f7bd
JF
217------------------------------------------------------------------------------
218
219ifdef::backend-xhtml11[]
220[frame="none"]
221`-----------------------`-----------------------------------------------------
222endif::backend-xhtml11[]
765595f3 223Scrolling:
2bc4f7bd 224------------------------------------------------------------------------------
9d6976b9
JF
225scroll-line-up Scroll one line up
226scroll-line-down Scroll one line down
227scroll-page-eup Scroll one page up
228scroll-page-down Scroll one page down
2bc4f7bd
JF
229------------------------------------------------------------------------------
230
231ifdef::backend-xhtml11[]
232[frame="none"]
233`-----------------------`-----------------------------------------------------
234endif::backend-xhtml11[]
f9a044a4
JF
235Searching:
236------------------------------------------------------------------------------
237search Search the view
238search-back Search backwards in the view
239find-next Find next search match
240find-prev Find previous search match
241------------------------------------------------------------------------------
242
243ifdef::backend-xhtml11[]
244[frame="none"]
245`-----------------------`-----------------------------------------------------
246endif::backend-xhtml11[]
765595f3 247Misc:
2bc4f7bd 248------------------------------------------------------------------------------
1d754561 249none Do nothing
2bc4f7bd 250prompt Bring up the prompt
2bc4f7bd
JF
251screen-redraw Redraw the screen
252screen-resize Resize the screen
253show-version Show version information
254stop-loading Stop all loading views
255toggle-lineno Toggle line numbers
823057f4
DV
256toggle-date Toggle date display
257toggle-author Toggle author display
9d6976b9 258toggle-rev-graph Toggle revision graph visualization
823057f4 259toggle-refs Toggle reference display
ca1d71ea 260status-update Update file status
b5c18d9d 261status-merge Resolve unmerged file
c509eed2 262tree-parent Switch to parent directory in tree view
f9a044a4 263edit Open in editor
2bc4f7bd
JF
264------------------------------------------------------------------------------
265
266
267Color command
268-------------
cb7f42cd 269
2bc4f7bd
JF
270Color commands control highlighting and the user interface styles. If your
271terminal supports color, these commands can be used to assign foreground and
62c7d1a7
JF
272background combinations to certain areas. Optionally, an attribute can be
273given as the last parameter. The syntax is:
2bc4f7bd
JF
274
275[verse]
276..............................................................................
c3c24b0b 277*color* 'area' 'fgcolor' 'bgcolor' '[attributes]'
2bc4f7bd 278..............................................................................
cb7f42cd 279
2bc4f7bd 280Examples:
cb7f42cd 281
2bc4f7bd 282------------------------------------------------------------------------------
62c7d1a7
JF
283# Overwrite the default terminal colors to white on black.
284color default white black
c3c24b0b
JF
285# Diff colors
286color diff-header yellow default
287color diff-index blue default
288color diff-chunk magenta default
289# A strange looking cursor line
290color cursor red default underline
291# UI colors
292color title-blur white blue
293color title-focus white blue bold
2bc4f7bd
JF
294------------------------------------------------------------------------------
295
296Area names::
297
298 Valid area names are described below. Note, all names are
299 case-insensitive, and you may use '-', '_', and '.' interchangeably,
300 e.g. "Diff-Header", "DIFF_HEADER", and "diff.header" are the same.
301
302Color names::
303
304 Valid colors include: *white*, *black*, *green*, *magenta*, *blue*,
305 *cyan*, *yellow*, *red*, *default*. Use *default* to refer to the
306 default terminal colors.
307
308Attribute names::
309
310 Valid attributes include: *normal*, *blink*, *bold*, *dim*, *reverse*,
311 *standout*, and *underline*. Note, not all attributes may be supported
312 by the terminal.
313
2bc4f7bd
JF
314UI colors
315~~~~~~~~~
316
317--
318
62c7d1a7
JF
319Default terminal colors::
320
321The colors and attributes to be used for the text that is not highlighted or
322that specify the use of the default terminal colors can be controlled by
323setting the *default* color option.
324
325Use the *default* color to use the colors configured for the terminal. This is
326the default and recommended if you are using a terminal with a transparent
327background.
328
2bc4f7bd
JF
329Status window colors::
330
331Appearance of the bottom window showing info messages.
332
333*status*
334
335Title window colors::
336
f7ffec06 337Appearance of the title windows when they are attached
2bc4f7bd
JF
338to any backgrounded windows and the current window.
339
340*title-blur*, *title-focus*
341
2a67fb2a 342Misc colors::
2bc4f7bd 343
2a67fb2a
JF
344Colors for the cursor line, line numbers, and delimiter shown for truncated
345lines.
2bc4f7bd 346
2a67fb2a 347*cursor*, *delimiter*, *line-number*
de46362f 348
2bc4f7bd
JF
349Main view specific::
350
accccb2b
JF
351Appearance of the various columns in the main view, including labels for tag
352and branch references.
2bc4f7bd 353
accccb2b
JF
354*main-date*, *main-author*, *main-commit*, *main-tag*, *main-local-tag*,
355*main-ref*, *main-remote*, *main-head*, *main-revgraph*
2bc4f7bd 356
8a680988
JF
357Blame view colors::
358
359The colors used for the blame view are similar to those in the main view.
360The commit ID color can be colored using *blame-id*.
361
2a67fb2a 362*blame-date*, *blame-author*, *blame-commit*, *blame-id*
8a680988 363
2bc4f7bd
JF
364--
365
366Highlighting
367~~~~~~~~~~~~
368
2bc4f7bd
JF
369--
370
371Diff markup::
372
373Options concerning diff start, chunks and lines added and deleted.
374
375*diff-header*, *diff-chunk*, *diff-add*, *diff-del*
376
377Enhanced git diff markup::
378
379Extra diff information emitted by the git diff machinery, such as mode
380changes, rename detection, and similarity.
381
382*diff-oldmode*, *diff-newmode*, *diff-copy-from*, *diff-copy-to*,
7389c87e 383*diff-rename-from*, *diff-rename-to*, *diff-similarity*, *diff-dissimilarity*
2bc4f7bd
JF
384*diff-tree*, *diff-index*
385
386Pretty print commit headers::
387
388Commit diffs and the revision logs are usually formatted using pretty printed
389headers , unless `--pretty=raw` was given. This includes lines, such as merge
f7ffec06 390info, commit ID, and author and committer date.
2bc4f7bd 391
13f3482f
DV
392*pp-author*, *pp-commit*, *pp-merge*, *pp-date*, *pp-adate*, *pp-cdate*,
393*pp-refs*
2bc4f7bd
JF
394
395Raw commit header::
396
397Usually shown when `--pretty=raw` is given, however 'commit' is pretty much
398omnipresent.
399
400*commit*, *parent*, *tree*, *author*, *committer*
401
402Commit message::
403
d4d8de8f 404For now only `Signed-off-by` and `Acked-by` lines are colorized.
2bc4f7bd 405
d4d8de8f 406*signoff*, *acked*
2bc4f7bd 407
13f3482f
DV
408Tree markup::
409
410Colors for information of the tree view.
411
412*tree-dir*, *tree-file*
413
414Status markup::
415
f5a5e640
JF
416Colors used in the status view for coloring the "On branch"-line, sections,
417"no file" lines and the various file status groups.
13f3482f 418
f5a5e640
JF
419*stat-head*, *stat-section*, *stat-none*, *stat-staged*, *stat-unstaged*,
420*stat-untracked*
13f3482f 421
2bc4f7bd
JF
422--
423
424COPYRIGHT
425---------
f9a044a4 426Copyright (c) 2006-2007 Jonas Fonseca <fonseca@diku.dk>
2bc4f7bd
JF
427
428Licensed under the terms of the GNU General Public License.
cb7f42cd
JF
429
430SEE ALSO
431--------
e664e260 432gitlink:tig[1] and the http://jonas.nitro.dk/tig/manual.html[tig manual].