1 tigrc(5)
2 ========
4 NAME
5 ----
6 tigrc - tig configuration file
9 SYNOPSIS
10 --------
11 [verse]
12 *set* 'variable' *=* 'value'
13 *bind* 'keymap' 'key' 'action'
14 *color* 'area' 'fgcolor' 'bgcolor' '[attributes]'
17 DESCRIPTION
18 -----------
20 You can permanently set an option by putting it in the `~/.tigrc` file. The
21 file consists of a series of 'commands'. Each line of the file may contain
22 only one command.
24 The hash mark ('#') is used as a 'comment' character. All text after the
25 comment character to the end of the line is ignored. You can use comments to
26 annotate your initialization file.
28 Alternatively, options can be set by putting them in one of the git
29 configuration files, which are read by tig on startup. See 'git-config(1)' for
30 which files to use.
32 Set command
33 -----------
35 A few selective variables can be configured via the set command. The syntax
36 is:
38 [verse]
39 *set* variables *=* value
41 Examples:
43 --------------------------------------------------------------------------
44 set show-author = yes # Show author?
45 set show-rev-graph = yes # Show revision graph?
46 set show-refs = yes # Show references?
47 set show-line-numbers = no # Show line numbers?
48 set line-number-interval = 5 # Interval between line numbers
49 set commit-encoding = "UTF-8" # Commit encoding
50 set horizontal-scroll = 33% # Scroll 33% of the view width
51 --------------------------------------------------------------------------
53 Or in the git configuration files:
55 --------------------------------------------------------------------------
56 [tig]
57 show-date = yes # Show commit date?
58 author-width = 10 # Set width of the author column
59 line-graphics = no # Disable graphics characters
60 tab-size = 8 # Number of spaces per tab
61 --------------------------------------------------------------------------
63 The type of variables are either bool, int, string, or mixed.
65 Valid bool values::
67 To set a bool variable to true use either "1", "true", or "yes".
68 Any other value will set the variable to false.
70 Valid int values::
72 A non-negative integer.
74 Valid string values::
76 A string of characters. Optionally, use either ' or " as delimiters.
78 Valid mixed values::
80 These values are composites of the above types. The valid values are
81 specified in the description.
83 Variables
84 ~~~~~~~~~
86 The following variables can be set:
88 'show-author' (bool)::
89 'show-date' (bool)::
90 'show-rev-graph' (bool)::
91 'show-refs' (bool)::
93 Whether to show author, date, revision graph, and references
94 (branches, tags, and remotes) in the main view on start-up. Can all be
95 toggled.
97 'author-width' (int)::
99 Width of the author column. When set to 5 or below, the author name
100 will be abbreviated to the author's initials.
102 'line-graphics' (bool)::
104 Whether to use graphic characters for line drawing.
106 'line-number-interval' (int)::
108 Interval between line numbers. Note, you have to toggle on line
109 numbering with 'n' or the `-n` command line option. The default is to
110 number every line.
112 'tab-size' (int)::
114 Number of spaces per tab. The default is 8 spaces.
116 'horizontal-scroll' (mixed)::
118 Interval to scroll horizontally in each step. Can be specified either
119 as the number of columns, e.g. '5', or as a percentage of the view
120 width, e.g. '33%', where the maximum is 100%. For percentages it is
121 always ensured that at least one column is scrolled. The default is to
122 scroll '50%' of the view width.
124 'split-view-height' (mixed)::
126 Height of the lower view in a split view. Can be specified either as
127 the number of rows, e.g. '5', or as a percentage of the view height,
128 e.g. '80%', where the maximum is 100%. It is always ensured that the
129 smaller of the views is at least four rows high. The default is a view
130 height of '66%'.
132 'commit-encoding' (string)::
134 The encoding used for commits. The default is UTF-8. Not this option
135 is shadowed by the "i18n.commitencoding" option in `.git/config`.
138 Bind command
139 ------------
141 Using bind commands keys can be mapped to an action when pressed in a given
142 key map. The syntax is:
144 [verse]
145 *bind* 'keymap' 'key' 'action'
147 Examples:
149 --------------------------------------------------------------------------
150 # A few keybindings
151 bind main w scroll-line-up
152 bind main s scroll-line-down
153 bind main space enter
154 bind diff a previous
155 bind diff d next
156 bind diff b move-first-line
157 # An external command to update from upstream
158 bind generic F !git fetch
159 --------------------------------------------------------------------------
161 Or in the git configuration files:
163 --------------------------------------------------------------------------
164 [tig "bind"]
165 # 'unbind' the default quit key binding
166 main = Q none
167 # Cherry-pick current commit onto current branch
168 generic = C !git cherry-pick %(commit)
169 --------------------------------------------------------------------------
171 Keys are mapped by first searching the keybindings for the current view, then
172 the keybindings for the *generic* keymap, and last the default keybindings.
173 Thus, the view keybindings shadow the generic keybindings which Shadow the
174 built-in keybindings.
176 --
178 Keymaps::
180 Valid keymaps are: *main*, *diff*, *log*, *help*, *pager*, *status*, *stage*,
181 *tree*, *blob*, *blame*, *branch*, and *generic*. Use *generic* to set key
182 mapping in all keymaps.
184 Key values::
186 Key values should never be quoted. Use either the ASCII value or one of the
187 following symbolic key names. Symbolic key names are case insensitive, Use
188 *Hash* to bind to the `#` key, since the hash mark is used as a comment
189 character.
191 *Enter*, *Space*, *Backspace*, *Tab*, *Escape*, *Left*, *Right*, *Up*, *Down*,
192 *Insert*, *Delete*, *Hash*, *Home*, *End*, *PageUp*, *PageDown*, *F1*, *F2*, *F3*,
193 *F4*, *F5*, *F6*, *F7*, *F8*, *F9*, *F10*, *F11*, *F12*.
195 Action names::
197 Valid action names are described below. Note, all names are
198 case-insensitive, and you may use '-', '_', and '.' interchangeably,
199 e.g. "view-main", "View.Main", and "VIEW_MAIN" are the same.
201 --
203 Actions
204 ~~~~~~~
206 Apart from the action names listed below, all actions starting with a '!' will
207 be available as an external command. External commands can contain variable
208 names that will be substituted before the command is run. Valid variable names
209 are:
211 ifdef::backend-xhtml11[]
212 [frame="none"]
213 `-----------------------`-----------------------------------------------------
214 endif::backend-xhtml11[]
215 Browsing state variables
216 ------------------------------------------------------------------------------
217 %(head) The currently viewed 'head' ID. Defaults to HEAD
218 %(commit) The currently selected commit ID.
219 %(blob) The currently selected blob ID.
220 %(directory) The current directory path in the tree view; \
221 empty for the root directory.
222 %(file) The currently selected file.
223 %(ref) The reference given to blame or HEAD if undefined.
224 ------------------------------------------------------------------------------
226 As an example, the following external command will save the current commit as
227 a patch file: "!git format-patch -1 %(commit)". If your external command
228 require use of dynamic features, such as subshells, expansion of environment
229 variables and process control, this can be achieved by using a combination of
230 git aliases and tig external commands. The following example entries can be
231 put in either the .gitconfig or .git/config file:
233 --------------------------------------------------------------------------
234 [alias]
235 gitk-bg = !"gitk HEAD --not $(git rev-parse --remotes) &"
236 publish = !"for i in origin public; do git push $i; done"
237 [tig "bind"]
238 generic = V !git gitk-bg
239 generic = > !git publish
240 --------------------------------------------------------------------------
242 ifdef::backend-xhtml11[]
243 [frame="none"]
244 `-----------------------`-----------------------------------------------------
245 endif::backend-xhtml11[]
246 View switching:
247 ------------------------------------------------------------------------------
248 view-main Show main view
249 view-diff Show diff view
250 view-log Show log view
251 view-tree Show tree view
252 view-blob Show blob view
253 view-blame Show blame view
254 view-branch Show branch view
255 view-status Show status view
256 view-stage Show stage view
257 view-pager Show pager view
258 view-help Show help page
259 ------------------------------------------------------------------------------
261 ifdef::backend-xhtml11[]
262 [frame="none"]
263 `-----------------------`-----------------------------------------------------
264 endif::backend-xhtml11[]
265 View manipulation:
266 ------------------------------------------------------------------------------
267 enter Enter current line and scroll
268 next Move to next
269 previous Move to previous
270 parent Move to parent
271 view-next Move focus to next view
272 refresh Reload and refresh view
273 maximize Maximize the current view
274 view-close Close the current view
275 quit Close all views and quit
276 ------------------------------------------------------------------------------
278 ifdef::backend-xhtml11[]
279 [frame="none"]
280 `-----------------------`-----------------------------------------------------
281 endif::backend-xhtml11[]
282 View specific actions:
283 ------------------------------------------------------------------------------
284 status-update Update file status
285 status-merge Resolve unmerged file
286 stage-next Find next chunk to stage
287 ------------------------------------------------------------------------------
289 ifdef::backend-xhtml11[]
290 [frame="none"]
291 `-----------------------`-----------------------------------------------------
292 endif::backend-xhtml11[]
293 Cursor navigation:
294 ------------------------------------------------------------------------------
295 move-up Move cursor one line up
296 move-down Move cursor one line down
297 move-page-down Move cursor one page down
298 move-page-up Move cursor one page up
299 move-first-line Move cursor to first line
300 move-last-line Move cursor to last line
301 ------------------------------------------------------------------------------
303 ifdef::backend-xhtml11[]
304 [frame="none"]
305 `-----------------------`-----------------------------------------------------
306 endif::backend-xhtml11[]
307 Scrolling:
308 ------------------------------------------------------------------------------
309 scroll-line-up Scroll one line up
310 scroll-line-down Scroll one line down
311 scroll-page-up Scroll one page up
312 scroll-page-down Scroll one page down
313 scroll-left Scroll one column left
314 scroll-right Scroll one column right
315 ------------------------------------------------------------------------------
317 ifdef::backend-xhtml11[]
318 [frame="none"]
319 `-----------------------`-----------------------------------------------------
320 endif::backend-xhtml11[]
321 Searching:
322 ------------------------------------------------------------------------------
323 search Search the view
324 search-back Search backwards in the view
325 find-next Find next search match
326 find-prev Find previous search match
327 ------------------------------------------------------------------------------
329 ifdef::backend-xhtml11[]
330 [frame="none"]
331 `-----------------------`-----------------------------------------------------
332 endif::backend-xhtml11[]
333 Misc:
334 ------------------------------------------------------------------------------
335 prompt Bring up the prompt
336 screen-redraw Redraw the screen
337 screen-resize Resize the screen
338 show-version Show version information
339 stop-loading Stop all loading views
340 options Open options menu
341 toggle-lineno Toggle line numbers
342 toggle-date Toggle date display
343 toggle-author Toggle author display
344 toggle-rev-graph Toggle revision graph visualization
345 toggle-refs Toggle reference display
346 edit Open in editor
347 none Do nothing
348 ------------------------------------------------------------------------------
351 Color command
352 -------------
354 Color commands control highlighting and the user interface styles. If your
355 terminal supports color, these commands can be used to assign foreground and
356 background combinations to certain areas. Optionally, an attribute can be
357 given as the last parameter. The syntax is:
359 [verse]
360 *color* 'area' 'fgcolor' 'bgcolor' '[attributes]'
362 Examples:
364 ------------------------------------------------------------------------------
365 # Overwrite the default terminal colors to white on black.
366 color default white black
367 # Diff colors
368 color diff-header yellow default
369 color diff-index blue default
370 color diff-chunk magenta default
371 --------------------------------------------------------------------------
373 Or in the git configuration files:
375 --------------------------------------------------------------------------
376 [tig "color"]
377 # A strange looking cursor line
378 cursor red default underline
379 # UI colors
380 title-blur white blue
381 title-focus white blue bold
382 ------------------------------------------------------------------------------
384 Area names::
386 Valid area names are described below. Note, all names are
387 case-insensitive, and you may use '-', '_', and '.' interchangeably,
388 e.g. "Diff-Header", "DIFF_HEADER", and "diff.header" are the same.
390 Color names::
392 Valid colors include: *white*, *black*, *green*, *magenta*, *blue*,
393 *cyan*, *yellow*, *red*, *default*. Use *default* to refer to the
394 default terminal colors. This is recommended for background colors if
395 you are using a terminal with a transparent background.
396 +
397 Colors can also be specified using the keywords color0, color1, ..., colorN-1
398 (N being the number of colors supported by your terminal). This is useful when
399 you remap the colors for your display or want to enable colors supported by
400 256-color terminals.
402 Attribute names::
404 Valid attributes include: *normal*, *blink*, *bold*, *dim*, *reverse*,
405 *standout*, and *underline*. Note, not all attributes may be supported
406 by the terminal.
408 UI colors
409 ~~~~~~~~~
411 The colors and attributes to be used for the text that is not highlighted or
412 that specify the use of the default terminal colors can be controlled by
413 setting the *default* color option.
415 ifdef::backend-xhtml11[]
416 [frame="none"]
417 `-----------------------`-----------------------------------------------------
418 endif::backend-xhtml11[]
419 General:
420 ------------------------------------------------------------------------------
421 default Overwrite default terminal colors (see above).
422 cursor The cursor line.
423 status The status window showing info messages.
424 title-focus The title window for the current view.
425 title-blur The title window of any backgrounded view.
426 delimiter Delimiter shown for truncated lines.
427 line-number Line numbers.
428 date The commit date.
429 author The commit author.
430 mode The file mode holding the permissions and type.
431 ------------------------------------------------------------------------------
433 ifdef::backend-xhtml11[]
434 [frame="none"]
435 `-----------------------`-----------------------------------------------------
436 endif::backend-xhtml11[]
437 Main view colors:
438 ------------------------------------------------------------------------------
439 main-revgraph The revision graph.
440 main-commit The commit comment.
441 main-head Label of the current branch.
442 main-remote Label of a remote.
443 main-tracked Label of the remote tracked by the current branch.
444 main-tag Label of a signed tag.
445 main-local-tag Label of a local tag.
446 main-ref Label of any other reference.
447 ------------------------------------------------------------------------------
449 ifdef::backend-xhtml11[]
450 [frame="none"]
451 `-----------------------`-----------------------------------------------------
452 endif::backend-xhtml11[]
453 Status view:
454 ------------------------------------------------------------------------------
455 stat-head The "On branch"-line.
456 stat-section Status section titles,
457 stat-staged Status flag of staged files.
458 stat-unstaged Status flag of unstaged files.
459 stat-untracked Status flag of untracked files.
460 ------------------------------------------------------------------------------
462 ifdef::backend-xhtml11[]
463 [frame="none"]
464 `-----------------------`-----------------------------------------------------
465 endif::backend-xhtml11[]
466 Blame view:
467 ------------------------------------------------------------------------------
468 blame-id The commit ID.
469 ------------------------------------------------------------------------------
471 ifdef::backend-xhtml11[]
472 [frame="none"]
473 `-----------------------`-----------------------------------------------------
474 endif::backend-xhtml11[]
475 Tree view:
476 ------------------------------------------------------------------------------
477 tree-head The "Directory /"-line
478 tree-dir The directory name.
479 tree-file The file name.
480 ------------------------------------------------------------------------------
482 Highlighting
483 ~~~~~~~~~~~~
485 --
487 Diff markup::
489 Options concerning diff start, chunks and lines added and deleted.
491 *diff-header*, *diff-chunk*, *diff-add*, *diff-del*
493 Enhanced git diff markup::
495 Extra diff information emitted by the git diff machinery, such as mode
496 changes, rename detection, and similarity.
498 *diff-oldmode*, *diff-newmode*, *diff-copy-from*, *diff-copy-to*,
499 *diff-rename-from*, *diff-rename-to*, *diff-similarity*, *diff-dissimilarity*
500 *diff-tree*, *diff-index*
502 Pretty print commit headers::
504 Commit diffs and the revision logs are usually formatted using pretty printed
505 headers , unless `--pretty=raw` was given. This includes lines, such as merge
506 info, commit ID, and author and committer date.
508 *pp-author*, *pp-commit*, *pp-merge*, *pp-date*, *pp-adate*, *pp-cdate*,
509 *pp-refs*
511 Raw commit header::
513 Usually shown when `--pretty=raw` is given, however 'commit' is pretty much
514 omnipresent.
516 *commit*, *parent*, *tree*, *author*, *committer*
518 Commit message::
520 For now only `Signed-off-by` and `Acked-by` lines are colorized.
522 *signoff*, *acked*
524 Tree markup::
526 Colors for information of the tree view.
528 *tree-dir*, *tree-file*
530 --
532 COPYRIGHT
533 ---------
534 Copyright (c) 2006-2009 Jonas Fonseca <fonseca@diku.dk>
536 Licensed under the terms of the GNU General Public License.
538 SEE ALSO
539 --------
540 manpage:tig[1], git-config(1),
541 and the http://jonas.nitro.dk/tig/manual.html[tig manual].