tigrc.5.txt

   1 tigrc(5)
   2 ========
   3
   4 NAME
   5 ----
   6 tigrc - tig configuration file
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 *set*   'variable' *=* 'value'
  13 *bind*  'keymap' 'key' 'action'
  14 *color* 'area' 'fgcolor' 'bgcolor' '[attributes]'
  15
  16
  17 DESCRIPTION
  18 -----------
  19
  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.
  23
  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.
  27
  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.
  31
  32 Set command
  33 -----------
  34
  35 A few selective variables can be configured via the set command. The syntax
  36 is:
  37
  38 [verse]
  39 *set* variables *=* value
  40
  41 Examples:
  42
  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 --------------------------------------------------------------------------
  52
  53 Or in the git configuration files:
  54
  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 --------------------------------------------------------------------------
  62
  63 The type of variables are either bool, int, string, or mixed.
  64
  65 Valid bool values::
  66
  67         To set a bool variable to true use either "1", "true", or "yes".
  68         Any other value will set the variable to false.
  69
  70 Valid int values::
  71
  72         A non-negative integer.
  73
  74 Valid string values::
  75
  76         A string of characters. Optionally, use either ' or " as delimiters.
  77
  78 Valid mixed values::
  79
  80         These values are composites of the above types. The valid values are
  81         specified in the description.
  82
  83 Variables
  84 ~~~~~~~~~
  85
  86 The following variables can be set:
  87
  88 'show-author' (bool)::
  89 'show-date' (bool)::
  90 'show-rev-graph' (bool)::
  91 'show-refs' (bool)::
  92
  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.
  96
  97 'author-width' (int)::
  98
  99         Width of the author column. When set to 5 or below, the author name
 100         will be abbreviated to the author's initials.
 101
 102 'line-graphics' (bool)::
 103
 104         Whether to use graphic characters for line drawing.
 105
 106 'line-number-interval' (int)::
 107
 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.
 111
 112 'tab-size' (int)::
 113
 114         Number of spaces per tab. The default is 8 spaces.
 115
 116 'horizontal-scroll' (mixed)::
 117
 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.
 123
 124 'split-view-height' (mixed)::
 125
 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%'.
 131
 132 'commit-encoding' (string)::
 133
 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`.
 136
 137
 138 Bind command
 139 ------------
 140
 141 Using bind commands keys can be mapped to an action when pressed in a given
 142 key map. The syntax is:
 143
 144 [verse]
 145 *bind* 'keymap' 'key' 'action'
 146
 147 Examples:
 148
 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 --------------------------------------------------------------------------
 160
 161 Or in the git configuration files:
 162
 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 --------------------------------------------------------------------------
 170
 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.
 175
 176 --
 177
 178 Keymaps::
 179
 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.
 183
 184 Key values::
 185
 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.
 190
 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*.
 194
 195 Action names::
 196
 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.
 200
 201 --
 202
 203 Actions
 204 ~~~~~~~
 205
 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:
 210
 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 ------------------------------------------------------------------------------
 225
 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:
 232
 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 --------------------------------------------------------------------------
 241
 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 ------------------------------------------------------------------------------
 260
 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 ------------------------------------------------------------------------------
 277
 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 ------------------------------------------------------------------------------
 288
 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 ------------------------------------------------------------------------------
 302
 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 ------------------------------------------------------------------------------
 316
 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 ------------------------------------------------------------------------------
 328
 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 ------------------------------------------------------------------------------
 349
 350
 351 Color command
 352 -------------
 353
 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:
 358
 359 [verse]
 360 *color* 'area' 'fgcolor' 'bgcolor' '[attributes]'
 361
 362 Examples:
 363
 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 --------------------------------------------------------------------------
 372
 373 Or in the git configuration files:
 374
 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 ------------------------------------------------------------------------------
 383
 384 Area names::
 385
 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.
 389
 390 Color names::
 391
 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.
 401
 402 Attribute names::
 403
 404         Valid attributes include: *normal*, *blink*, *bold*, *dim*, *reverse*,
 405         *standout*, and *underline*. Note, not all attributes may be supported
 406         by the terminal.
 407
 408 UI colors
 409 ~~~~~~~~~
 410
 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.
 414
 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 ------------------------------------------------------------------------------
 432
 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 ------------------------------------------------------------------------------
 448
 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 ------------------------------------------------------------------------------
 461
 462 ifdef::backend-xhtml11[]
 463 [frame="none"]
 464 `-----------------------`-----------------------------------------------------
 465 endif::backend-xhtml11[]
 466 Blame view:
 467 ------------------------------------------------------------------------------
 468 blame-id                The commit ID.
 469 ------------------------------------------------------------------------------
 470
 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 ------------------------------------------------------------------------------
 481
 482 Highlighting
 483 ~~~~~~~~~~~~
 484
 485 --
 486
 487 Diff markup::
 488
 489 Options concerning diff start, chunks and lines added and deleted.
 490
 491 *diff-header*, *diff-chunk*, *diff-add*, *diff-del*
 492
 493 Enhanced git diff markup::
 494
 495 Extra diff information emitted by the git diff machinery, such as mode
 496 changes, rename detection, and similarity.
 497
 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*
 501
 502 Pretty print commit headers::
 503
 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.
 507
 508 *pp-author*, *pp-commit*, *pp-merge*, *pp-date*, *pp-adate*, *pp-cdate*,
 509 *pp-refs*
 510
 511 Raw commit header::
 512
 513 Usually shown when `--pretty=raw` is given, however 'commit' is pretty much
 514 omnipresent.
 515
 516 *commit*, *parent*, *tree*, *author*, *committer*
 517
 518 Commit message::
 519
 520 For now only `Signed-off-by` and `Acked-by` lines are colorized.
 521
 522 *signoff*, *acked*
 523
 524 Tree markup::
 525
 526 Colors for information of the tree view.
 527
 528 *tree-dir*, *tree-file*
 529
 530 --
 531
 532 COPYRIGHT
 533 ---------
 534 Copyright (c) 2006-2009 Jonas Fonseca <fonseca@diku.dk>
 535
 536 Licensed under the terms of the GNU General Public License.
 537
 538 SEE ALSO
 539 --------
 540 manpage:tig[1], git-config(1),
 541 and the http://jonas.nitro.dk/tig/manual.html[tig manual].