manual.txt

   1 The tig Manual
   2 ==============
   3 Jonas Fonseca <fonseca@diku.dk>
   4
   5 This is the manual for tig, the ncurses-based text-mode interface for git.
   6 Tig allows you to browse changes in a git repository and can additionally act
   7 as a pager for output of various git commands. When used as a pager, it will
   8 display input from stdin and colorize it.
   9
  10 When browsing repositories, tig uses the underlying git commands to present
  11 the user with various views, such as summarized commit log and showing the
  12 commit with the log message, diffstat, and the diff.
  13
  14 ifndef::backend-docbook[]
  15 *Table of Contents*
  16
  17 include::manual.toc[]
  18 endif::backend-docbook[]
  19
  20 [[calling-conventions]]
  21 Calling Conventions
  22 -------------------
  23
  24 [[pager-mode]]
  25 Pager Mode
  26 ~~~~~~~~~~
  27
  28 If stdin is a pipe, any log or diff options will be ignored and the pager view
  29 will be opened loading data from stdin. The pager mode can be used for
  30 colorizing output from various git commands.
  31
  32 Example on how to colorize the output of git-show(1):
  33
  34 -----------------------------------------------------------------------------
  35 $ git show | tig
  36 -----------------------------------------------------------------------------
  37
  38 [[cmd-options]]
  39 Git Command Options
  40 ~~~~~~~~~~~~~~~~~~~
  41
  42 All git command options specified on the command line will be passed to the
  43 given command and all will be shell quoted before they are passed to the
  44 shell.
  45
  46 NOTE: If you specify options for the main view, you should not use the
  47 `\--pretty` option as this option will be set automatically to the format
  48 expected by the main view.
  49
  50 Example on how to view a commit and show both author and committer
  51 information:
  52
  53 -----------------------------------------------------------------------------
  54 $ tig show --pretty=fuller
  55 -----------------------------------------------------------------------------
  56
  57 See the section on <<refspec, specifying revisions>> for an introduction to
  58 revision options supported by the git commands. For details on specific git
  59 command options, refer to the man page of the command in question.
  60
  61 [[viewer]]
  62 The Viewer
  63 ----------
  64
  65 The display consists of a status window on the last line of the screen and one
  66 or more views. The default is to only show one view at the time but it is
  67 possible to split both the main and log view to also show the commit diff.
  68
  69 If you are in the log view and press 'Enter' when the current line is a commit
  70 line, such as:
  71
  72 -----------------------------------------------------------------------------
  73 commit 4d55caff4cc89335192f3e566004b4ceef572521
  74 -----------------------------------------------------------------------------
  75
  76 You will split the view so that the log view is displayed in the top window
  77 and the diff view in the bottom window. You can switch between the two views
  78 by pressing 'Tab'. To maximize the log view again, simply press 'l'.
  79
  80 [[views]]
  81 Views
  82 ~~~~~
  83
  84 Various 'views' of a repository is presented. Each view is based on output
  85 from an external command, most often 'git log', 'git diff', or 'git show'.
  86
  87 The main view::
  88         Is the default view, and it shows a one line summary of each commit
  89         in the chosen list of revisions. The summary includes commit date,
  90         author, and the first line of the log message. Additionally, any
  91         repository references, such as tags, will be shown.
  92
  93 The log view::
  94         Presents a more rich view of the revision log showing the whole log
  95         message and the diffstat.
  96
  97 The diff view::
  98         Shows either the diff of the current working tree, that is, what
  99         has changed since the last commit, or the commit diff complete
 100         with log message, diffstat and diff.
 101
 102 The tree view::
 103         Lists directory trees associated with the current revision allowing
 104         subdirectories to be descended or ascended and file blobs to be
 105         viewed.
 106
 107 The blob view::
 108         Displays the file content or "blob" of data associated with a file
 109         name.
 110
 111 The blame view::
 112         Displays the file content annotated or blamed by commits.
 113
 114 The status view::
 115         Displays status of files in the working tree and allows changes to be
 116         staged/unstaged as well as adding of untracked files.
 117
 118 The stage view::
 119         Displays diff changes for staged or unstanged files being tracked or
 120         file content of untracked files.
 121
 122 The pager view::
 123         Is used for displaying both input from stdin and output from git
 124         commands entered in the internal prompt.
 125
 126 The help view::
 127         Displays a quick reference of key bindings.
 128
 129 [[commit-id]]
 130 Browsing State and User-defined Commands
 131 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 132
 133 The viewer keeps track of both what head and commit ID you are currently
 134 viewing. The commit ID will follow the cursor line and change every time you
 135 highlight a different commit. Whenever you reopen the diff view it will be
 136 reloaded, if the commit ID changed. The head ID is used when opening the main
 137 and log view to indicate from what revision to show history.
 138
 139 Some of the commands used or provided by tig can be configured. This goes for
 140 the <<external-commands, external commands>>. These user-defined commands can
 141 use arguments that refer to the current browsing state by using one of the
 142 following variables.
 143
 144 `-----------------------`-----------------------------------------------------
 145 Browsing state variables
 146 ------------------------------------------------------------------------------
 147 %(head)                 The currently viewed 'head' ID. Defaults to HEAD
 148 %(commit)               The currently selected commit ID.
 149 %(blob)                 The currently selected blob ID.
 150 %(directory)            The current directory path in the tree view; \
 151                         empty for the root directory.
 152 %(file)                 The currently selected file.
 153 %(ref)                  The reference given to blame or HEAD if undefined.
 154 ------------------------------------------------------------------------------
 155
 156 [[title-window]]
 157 Title Windows
 158 ~~~~~~~~~~~~~
 159
 160 Each view has a title window which shows the name of the view, current commit
 161 ID if available, and where the view is positioned:
 162
 163 -----------------------------------------------------------------------------
 164 [main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
 165 -----------------------------------------------------------------------------
 166
 167 By default, the title of the current view is highlighted using bold font.  For
 168 long loading views (taking over 3 seconds) the time since loading started will
 169 be appended:
 170
 171 -----------------------------------------------------------------------------
 172 [main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
 173 -----------------------------------------------------------------------------
 174
 175 [[env-variables]]
 176 Environment Variables
 177 ---------------------
 178
 179 Several options related to the interface with git can be configured via
 180 environment options.
 181
 182 [[configuration-files]]
 183 Configuration Files
 184 ~~~~~~~~~~~~~~~~~~~
 185
 186 Upon startup, tig first reads the system wide configuration file
 187 (`{sysconfdir}/tigrc` by default) and then proceeds to read the user's
 188 configuration file (`~/.tigrc` by default). The paths to either of these files
 189 can be overridden through the following environment variables:
 190
 191 TIGRC_USER::
 192         Path of the user configuration file.
 193
 194 TIGRC_SYSTEM::
 195         Path of the system wide configuration file.
 196
 197 [[repo-refs]]
 198 Repository References
 199 ~~~~~~~~~~~~~~~~~~~~~
 200
 201 Commits that are referenced by tags and branch heads will be marked by the
 202 reference name surrounded by '[' and ']':
 203
 204 -----------------------------------------------------------------------------
 205 2006-03-26 19:42 Petr Baudis         | [cogito-0.17.1] Cogito 0.17.1
 206 -----------------------------------------------------------------------------
 207
 208 If you want to filter what branches gets shown, say limit to only show
 209 branches named `master` or which starts with the `jf/` prefix, you can
 210 do it by setting the following variable:
 211
 212 -----------------------------------------------------------------------------
 213 $ TIG_LS_REMOTE="git ls-remote . master jf/*" tig
 214 -----------------------------------------------------------------------------
 215
 216 Or set the variable permanently in your environment.
 217
 218 --
 219
 220 TIG_LS_REMOTE::
 221
 222         Set command for retrieving all repository references. The command
 223         should output data in the same format as git-ls-remote(1). Defaults
 224         to:
 225 -----------------------------------------------------------------------------
 226 git ls-remote .
 227 -----------------------------------------------------------------------------
 228
 229 --
 230
 231 [[history-commands]]
 232 History Commands
 233 ~~~~~~~~~~~~~~~~
 234
 235 It is possible to alter which commands are used for the different views.  If
 236 for example you prefer commits in the main view to be sorted by date and only
 237 show 500 commits, use:
 238
 239 -----------------------------------------------------------------------------
 240 $ TIG_MAIN_CMD="git log --date-order -n500 --pretty=raw %s" tig
 241 -----------------------------------------------------------------------------
 242
 243 Or set the variable permanently in your environment.
 244
 245 Notice, how `%s` is used to specify the commit reference. There can be a
 246 maximum of 5 `%s` ref specifications.
 247
 248 --
 249
 250 TIG_DIFF_CMD::
 251
 252         The command used for the diff view. Defaults to:
 253 -----------------------------------------------------------------------------
 254 git show --pretty=fuller --no-color --root
 255          --patch-with-stat --find-copies-harder -C %s
 256 -----------------------------------------------------------------------------
 257
 258 TIG_LOG_CMD::
 259
 260         The command used for the log view. If you prefer to have both
 261         author and committer shown in the log view be sure to pass
 262         `\--pretty=fuller` to git log. Defaults to:
 263 -----------------------------------------------------------------------------
 264 git log --no-color --cc --stat -n100 %s
 265 -----------------------------------------------------------------------------
 266
 267 TIG_MAIN_CMD::
 268
 269         The command used for the main view. Note, you must always specify
 270         the option: `\--pretty=raw` since the main view parser expects to
 271         read that format.
 272 -----------------------------------------------------------------------------
 273 git log --no-color --pretty=raw --parents --topo-order %s
 274 -----------------------------------------------------------------------------
 275
 276 --
 277
 278 [[tree-commands]]
 279 Tree Commands
 280 ~~~~~~~~~~~~~
 281
 282 --
 283
 284 TIG_TREE_CMD::
 285
 286         The command used for the tree view. Takes two arguments, the first is
 287         the revision ID and the second is the path of the directory tree,
 288         empty for the root directory. Defaults to:
 289 -----------------------------------------------------------------------------
 290 git ls-tree %s %s
 291 -----------------------------------------------------------------------------
 292
 293 TIG_BLOB_CMD::
 294
 295         The command used for the blob view. Takes one argument which is the
 296         blob ID. Defaults to:
 297 -----------------------------------------------------------------------------
 298 git cat-file blob %s
 299 -----------------------------------------------------------------------------
 300
 301 --
 302
 303 [[keys]]
 304 Default Keybindings
 305 -------------------
 306 Below the default key bindings are shown.
 307
 308 [[view-switching]]
 309 View Switching
 310 ~~~~~~~~~~~~~~
 311
 312 `-------`--------------------------------------------------------------------
 313 Key     Action
 314 -----------------------------------------------------------------------------
 315 m       Switch to main view.
 316 d       Switch to diff view.
 317 l       Switch to log view.
 318 p       Switch to pager view.
 319 t       Switch to (directory) tree view.
 320 f       Switch to (file) blob view.
 321 B       Switch to blame view.
 322 h       Switch to help view
 323 S       Switch to status view
 324 c       Switch to stage view
 325 -----------------------------------------------------------------------------
 326
 327 [[view-manipulation]]
 328 View Manipulation
 329 ~~~~~~~~~~~~~~~~~
 330
 331 `-------`--------------------------------------------------------------------
 332 Key     Action
 333 -----------------------------------------------------------------------------
 334 q       Close view, if multiple views are open it will jump back to the \
 335         previous view in the view stack. If it is the last open view it \
 336         will quit. Use 'Q' to quit all views at once.
 337 Enter   This key is "context sensitive" depending on what view you are \
 338         currently in. When in log view on a commit line or in the main \
 339         view, split the view and show the commit diff. In the diff view \
 340         pressing Enter will simply scroll the view one line down.
 341 Tab     Switch to next view.
 342 R       Reload and refresh the current view.
 343 M       Maximize the current view to fill the whole display.
 344 Up      This key is "context sensitive" and will move the cursor one \
 345         line up. However, if you opened a diff view from the main view \
 346         (split- or full-screen) it will change the cursor to point to \
 347         the previous commit in the main view and update the diff view \
 348         to display it.
 349 Down    Similar to 'Up' but will move down.
 350 -----------------------------------------------------------------------------
 351
 352 [[cursor-nav]]
 353 Cursor Navigation
 354 ~~~~~~~~~~~~~~~~~
 355
 356 `-------`--------------------------------------------------------------------
 357 Key     Action
 358 -----------------------------------------------------------------------------
 359 j       Move cursor one line up.
 360 k       Move cursor one line down.
 361 PgUp,\
 362 -,a     Move cursor one page up.
 363 PgDown  Space   Move cursor one page down.
 364 Home    Jump to first line.
 365 End     Jump to last line.
 366 -----------------------------------------------------------------------------
 367
 368 [[view-scrolling]]
 369 Scrolling
 370 ~~~~~~~~~
 371
 372 `-------`--------------------------------------------------------------------
 373 Key     Action
 374 -----------------------------------------------------------------------------
 375 Insert  Scroll view one line up.
 376 Delete  Scroll view one line down.
 377 w       Scroll view one page up.
 378 s       Scroll view one page down.
 379 -----------------------------------------------------------------------------
 380
 381 [[searching]]
 382 Searching
 383 ~~~~~~~~~
 384
 385 `-------`--------------------------------------------------------------------
 386 Key     Action
 387 -----------------------------------------------------------------------------
 388 /       Search the view. Opens a prompt for entering search regex to use.
 389 ?       Search backwards in the view. Also prompts for regex.
 390 n       Find next match for the current search regex.
 391 N       Find previous match for the current search regex.
 392 -----------------------------------------------------------------------------
 393
 394 [[misc-keys]]
 395 Misc
 396 ~~~~
 397
 398 `-------`--------------------------------------------------------------------
 399 Key     Action
 400 -----------------------------------------------------------------------------
 401 Q       Quit.
 402 r       Redraw screen.
 403 z       Stop all background loading. This can be useful if you use \
 404         tig in a repository with a long history without limiting \
 405         the revision log.
 406 v       Show version.
 407 '.'     Toggle line numbers on/off.
 408 D       Toggle date display on/off.
 409 A       Toggle author display on/off.
 410 g       Toggle revision graph visualization on/off.
 411 F       Toggle reference display on/off (tag and branch names).
 412 ':'     Open prompt. This allows you to specify what git command \
 413         to run. Example `:log -p`
 414 u       Update status of file. In the status view, this allows you to add an \
 415         untracked file or stage changes to a file for next commit (similar to \
 416         running git-add <filename>). In the stage view, when pressing this on \
 417         a diff chunk line stages only that chunk for next commit, when not on \
 418         a diff chunk line all changes in the displayed diff is staged.
 419 M       Resolve unmerged file by launching git-mergetool(1). Note, to work \
 420         correctly this might require some initial configuration of your \
 421         preferred merge tool. See the manpage of git-mergetool(1).
 422 !       Checkout file with unstaged changes. This will reset the file to \
 423         contain the content it had at last commit.
 424 @       Move to next chunk in the stage view.
 425 ','     Move tree view to the parent tree.
 426 e       Open file in editor.
 427 -----------------------------------------------------------------------------
 428
 429 [[external-commands]]
 430 External Commands
 431 ~~~~~~~~~~~~~~~~~
 432
 433 For more custom needs, external commands provide a way to easily execute
 434 a script or program. They are bound to keys and use information from the
 435 current browsing state, such as the current commit ID. Tig comes with
 436 the following builtin external commands:
 437
 438 `-------`--------------------------------------------------------------------
 439 Key     Action
 440 -----------------------------------------------------------------------------
 441 C       git cherry-pick %(commit)
 442 G       git gc
 443 -----------------------------------------------------------------------------
 444
 445 [[refspec]]
 446 Revision Specification
 447 ----------------------
 448
 449 This section describes various ways to specify what revisions to display or
 450 otherwise limit the view to. Tig does not itself parse the described
 451 revision options so refer to the relevant git man pages for further
 452 information. Relevant man pages besides git-log(1) are git-diff(1) and
 453 git-rev-list(1).
 454
 455 You can tune the interaction with git by making use of the options explained
 456 in this section. For example, by configuring the environment variables
 457 described in the section on <<history-commands, history commands>>.
 458
 459 [[path-limiting]]
 460 Limit by Path Name
 461 ~~~~~~~~~~~~~~~~~~
 462
 463 If you are interested only in those revisions that made changes to a specific
 464 file (or even several files) list the files like this:
 465
 466 -----------------------------------------------------------------------------
 467 $ tig Makefile README
 468 -----------------------------------------------------------------------------
 469
 470 To avoid ambiguity with tig's subcommands or repository references such as tag
 471 name, be sure to separate file names from other git options using "\--". So if
 472 you have a file named 'status' it will clash with the 'status' subcommand, and
 473 thus you will have to use:
 474
 475 -----------------------------------------------------------------------------
 476 $ tig -- status
 477 -----------------------------------------------------------------------------
 478
 479 [[date-number-limiting]]
 480 Limit by Date or Number
 481 ~~~~~~~~~~~~~~~~~~~~~~~
 482
 483 To speed up interaction with git, you can limit the amount of commits to show
 484 both for the log and main view. Either limit by date using e.g.
 485 `\--since=1.month` or limit by the number of commits using `-n400`.
 486
 487 If you are only interested in changed that happened between two dates you can
 488 use:
 489
 490 -----------------------------------------------------------------------------
 491 $ tig --after="May 5th" --before="2006-05-16 15:44"
 492 -----------------------------------------------------------------------------
 493
 494 NOTE: If you want to avoid having to quote dates containing spaces you can use
 495 "." instead, e.g. `\--after=May.5th`.
 496
 497 [[commit-range-limiting]]
 498 Limiting by Commit Ranges
 499 ~~~~~~~~~~~~~~~~~~~~~~~~~
 500
 501 Alternatively, commits can be limited to a specific range, such as "all
 502 commits between 'tag-1.0' and 'tag-2.0'". For example:
 503
 504 -----------------------------------------------------------------------------
 505 $ tig tag-1.0..tag-2.0
 506 -----------------------------------------------------------------------------
 507
 508 This way of commit limiting makes it trivial to only browse the commits which
 509 haven't been pushed to a remote branch. Assuming 'origin' is your upstream
 510 remote branch, using:
 511
 512 -----------------------------------------------------------------------------
 513 $ tig origin..HEAD
 514 -----------------------------------------------------------------------------
 515
 516 will list what will be pushed to the remote branch. Optionally, the ending
 517 'HEAD' can be left out since it is implied.
 518
 519 [[reachability-limiting]]
 520 Limiting by Reachability
 521 ~~~~~~~~~~~~~~~~~~~~~~~~
 522
 523 Git interprets the range specifier "tag-1.0..tag-2.0" as "all commits
 524 reachable from 'tag-2.0' but not from 'tag-1.0'".  Where reachability refers
 525 to what commits are ancestors (or part of the history) of the branch or tagged
 526 revision in question.
 527
 528 If you prefer to specify which commit to preview in this way use the
 529 following:
 530
 531 -----------------------------------------------------------------------------
 532 $ tig tag-2.0 ^tag-1.0
 533 -----------------------------------------------------------------------------
 534
 535 You can think of '^' as a negation operator. Using this alternate syntax, it
 536 is possible to further prune commits by specifying multiple branch cut offs.
 537
 538 [[refspec-combi]]
 539 Combining Revisions Specification
 540 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 541
 542 Revisions options can to some degree be combined, which makes it possible to
 543 say "show at most 20 commits from within the last month that changed files
 544 under the Documentation/ directory."
 545
 546 -----------------------------------------------------------------------------
 547 $ tig --since=1.month -n20 -- Documentation/
 548 -----------------------------------------------------------------------------
 549
 550 [[refspec-all]]
 551 Examining All Repository References
 552 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 553
 554 In some cases, it can be useful to query changes across all references in a
 555 repository. An example is to ask "did any line of development in this
 556 repository change a particular file within the last week". This can be
 557 accomplished using:
 558
 559 -----------------------------------------------------------------------------
 560 $ tig --all --since=1.week -- Makefile
 561 -----------------------------------------------------------------------------
 562
 563 include::BUGS[]
 564
 565 [[copy-right]]
 566 Copyright
 567 ---------
 568
 569 Copyright (c) 2006-2008 Jonas Fonseca <fonseca@diku.dk>
 570
 571 This program is free software; you can redistribute it and/or modify
 572 it under the terms of the GNU General Public License as published by
 573 the Free Software Foundation; either version 2 of the License, or
 574 (at your option) any later version.
 575
 576 [[references]]
 577 References and Related Tools
 578 ----------------------------
 579
 580 Manpages:
 581
 582  - manpage:tig[1]
 583  - manpage:tigrc[5]
 584
 585 Online resources:
 586
 587 include::SITES[]
 588
 589 Other git repository browsers:
 590
 591  - gitk(1)
 592  - qgit(1)
 593  - gitview(1)