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 Calling Conventions
  15 -------------------
  16
  17 Pager Mode
  18 ~~~~~~~~~~
  19
  20 If stdin is a pipe, any log or diff options will be ignored and the pager view
  21 will be opened loading data from stdin. The pager mode can be used for
  22 colorizing output from various git commands.
  23
  24 Example on how to colorize the output of git-show(1):
  25
  26         $ git show | tig
  27
  28 Git Command Options
  29 ~~~~~~~~~~~~~~~~~~~
  30
  31 All git command options specified on the command line will be passed to the
  32 given command and all will be shell quoted before they are passed to the
  33 shell.
  34
  35 NOTE: If you specify options for the main view, you should not use the
  36 `--pretty` option as this option will be set automatically to the format
  37 expected by the main view.
  38
  39 Example on how to open the log view and show both author and committer
  40 information:
  41
  42         $ tig log --pretty=fuller
  43
  44 See the <<refspec, "Specifying revisions">> section below for an introduction
  45 to revision options supported by the git commands. For details on specific git
  46 command options, refer to the man page of the command in question.
  47
  48 Environment Variables
  49 ---------------------
  50
  51 Several options related to the interface with git can be configured via
  52 environment options.
  53
  54 Repository References
  55 ~~~~~~~~~~~~~~~~~~~~~
  56
  57 Commits that are referenced by tags and branch heads will be marked by the
  58 reference name surrounded by '[' and ']':
  59
  60         2006-03-26 19:42 Petr Baudis         | [cogito-0.17.1] Cogito 0.17.1
  61
  62 If you want to filter out certain directories under `.git/refs/`, say `tmp`
  63 you can do it by setting the following variable:
  64
  65         $ TIG_LS_REMOTE="git ls-remote . | sed /\/tmp\//d" tig
  66
  67 Or set the variable permanently in your environment.
  68
  69 TIG_LS_REMOTE::
  70         Set command for retrieving all repository references. The command
  71         should output data in the same format as git-ls-remote(1).
  72
  73 [[history-commands]]
  74 History Commands
  75 ~~~~~~~~~~~~~~~~
  76
  77 It is possible to alter which commands are used for the different views.  If
  78 for example you prefer commits in the main view to be sorted by date and only
  79 show 500 commits, use:
  80
  81         $ TIG_MAIN_CMD="git log --date-order -n500 --pretty=raw %s" tig
  82
  83 Or set the variable permanently in your environment.
  84
  85 Notice, how `%s` is used to specify the commit reference. There can be a
  86 maximum of 5 `%s` ref specifications.
  87
  88 TIG_DIFF_CMD::
  89         The command used for the diff view. By default, git show is used
  90         as a backend.
  91
  92 TIG_LOG_CMD::
  93         The command used for the log view. If you prefer to have both
  94         author and committer shown in the log view be sure to pass
  95         `--pretty=fuller` to git log.
  96
  97 TIG_MAIN_CMD::
  98         The command used for the main view. Note, you must always specify
  99         the option: `--pretty=raw` since the main view parser expects to
 100         read that format.
 101
 102 The Viewer
 103 ----------
 104
 105 The display consists of a status window on the last line of the screen and one
 106 or more views. The default is to only show one view at the time but it is
 107 possible to split both the main and log view to also show the commit diff.
 108
 109 If you are in the log view and press 'Enter' when the current line is a commit
 110 line, such as:
 111
 112         commit 4d55caff4cc89335192f3e566004b4ceef572521
 113
 114 You will split the view so that the log view is displayed in the top window
 115 and the diff view in the bottom window. You can switch between the two views
 116 by pressing 'Tab'. To maximize the log view again, simply press 'l'.
 117
 118 Current Head and Commit ID
 119 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 120
 121 The viewer keeps track of both what head and commit ID you are currently
 122 viewing. The commit ID will follow the cursor line and change everytime time
 123 you highlight a different commit. Whenever you reopen the diff view it will be
 124 reloaded, if the commit ID changed.
 125
 126 The head ID is used when opening the main and log view to indicate from what
 127 revision to show history.
 128
 129 Views
 130 ~~~~~
 131
 132 tig(1) presents various 'views' of a repository. Each view is based on output
 133 from an external command, most often 'git log', 'git diff', or 'git show'.
 134
 135 The main view::
 136         Is the default view, and it shows a one line summary of each commit
 137         in the chosen list of revisions. The summary includes commit date,
 138         author, and the first line of the log message. Additionally, any
 139         repository references, such as tags, will be shown.
 140
 141 The log view::
 142         Presents a more rich view of the revision log showing the whole log
 143         message and the diffstat.
 144
 145 The diff view::
 146         Shows either the diff of the current working tree, that is, what
 147         has changed since the last commit, or the commit diff complete
 148         with log message, diffstat and diff.
 149
 150 The pager view::
 151         Is used for displaying both input from stdin and output from git
 152         commands entered in the internal prompt.
 153
 154 The help view::
 155         Displays key binding quick reference.
 156
 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         [main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
 164
 165 By default, the title of the current view is highlighted using bold font.  For
 166 long loading views (taking over 3 seconds) the time since loading started will
 167 be appended:
 168
 169         [main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
 170
 171 Keys
 172 ----
 173 Below the default key bindings are shown.
 174
 175 View Switching
 176 ~~~~~~~~~~~~~~
 177 m::
 178         Switch to main view.
 179 d::
 180         Switch to diff view.
 181 l::
 182         Switch to log view.
 183 p::
 184         Switch to pager view.
 185 h, ?::
 186         Show man page.
 187
 188 View Manipulation
 189 ~~~~~~~~~~~~~~~~~
 190 q::
 191         Close view, if multiple views are open it will jump back to the
 192         previous view in the view stack. If it is the last open view it
 193         will quit. Use 'Q' to quit all views at once.
 194 Enter::
 195         This key is "context sensitive" depending on what view you are
 196         currently in. When in log view on a commit line or in the main
 197         view, split the view and show the commit diff. In the diff view
 198         pressing Enter will simply scroll the view one line down.
 199 Tab::
 200         Switch to next view.
 201 Up::
 202         This key is "context sensitive" and will move the cursor one
 203         line up. However, uf you opened a diff view from the main view
 204         (split- or full-screen) it will change the cursor to point to
 205         the previous commit in the main view and update the diff view
 206         to display it.
 207 Down::
 208         Similar to 'Up' but will move down.
 209
 210 Cursor Navigation
 211 ~~~~~~~~~~~~~~~~~
 212 j::
 213         Move cursor one line up.
 214 k::
 215         Move cursor one line down.
 216 PgUp::
 217 b::
 218 -::
 219         Move cursor one page up.
 220 PgDown::
 221 Space::
 222         Move cursor one page down.
 223 Home::
 224         Jump to first line.
 225 End::
 226         Jump to last line.
 227
 228 Scrolling
 229 ~~~~~~~~~
 230 Insert::
 231         Scroll view one line up.
 232 Delete::
 233         Scroll view one line down.
 234 w::
 235         Scroll view one page up.
 236 s::
 237         Scroll view one page down.
 238
 239 Misc
 240 ~~~~
 241 Q::
 242         Quit.
 243 r::
 244         Redraw screen.
 245 z::
 246         Stop all background loading. This can be useful if you use
 247         tig(1) in a repository with a long history without limiting
 248         the revision log.
 249 v::
 250         Show version.
 251 n::
 252         Toggle line numbers on/off.
 253 g::
 254         Toggle revision graph visualization on/off.
 255 ':'::
 256         Open prompt. This allows you to specify what git command
 257         to run. Example:
 258
 259         :log -p
 260
 261 [[refspec]]
 262 Revision Specification
 263 ----------------------
 264
 265 This section describes various ways to specify what revisions to display or
 266 otherwise limit the view to. tig(1) does not itself parse the described
 267 revision options so refer to the relevant git man pages for futher
 268 information. Relevant man pages besides git-log(1) are git-diff(1) and
 269 git-rev-list(1).
 270
 271 You can tune the interaction with git by making use of the options explained
 272 in this section. For example, by configuring the environment variables
 273 described in the  <<history-commands, "History commands">> section.
 274
 275 Limit by Path Name
 276 ~~~~~~~~~~~~~~~~~~
 277
 278 If you are interested only in those revisions that made changes to a specific
 279 file (or even several files) list the files like this:
 280
 281         $ tig log Makefile README
 282
 283 To avoid ambiguity with repository references such as tag name, be sure to
 284 separate file names from other git options using "\--". So if you have a file
 285 named 'master' it will clash with the reference named 'master', and thus you
 286 will have to use:
 287
 288         $ tig log -- master
 289
 290 NOTE: For the main view, avoiding ambiguity will in some cases require you to
 291 specify two "\--" options. The first will make tig(1) stop option processing
 292 and the latter will be passed to git log.
 293
 294 Limit by Date or Number
 295 ~~~~~~~~~~~~~~~~~~~~~~~
 296
 297 To speed up interaction with git, you can limit the amount of commits to show
 298 both for the log and main view. Either limit by date using e.g.
 299 `--since=1.month` or limit by the number of commits using `-n400`.
 300
 301 If you are only interested in changed that happened between two dates you can
 302 use:
 303
 304         $ tig -- --after="May 5th" --before="2006-05-16 15:44"
 305
 306 NOTE: If you want to avoid having to quote dates containing spaces you can use
 307 "." instead, e.g. `--after=May.5th`.
 308
 309 Limiting by Commit Ranges
 310 ~~~~~~~~~~~~~~~~~~~~~~~~~
 311
 312 Alternatively, commits can be limited to a specific range, such as "all
 313 commits between 'tag-1.0' and 'tag-2.0'". For example:
 314
 315         $ tig log tag-1.0..tag-2.0
 316
 317 This way of commit limiting makes it trivial to only browse the commits which
 318 haven't been pushed to a remote branch. Assuming 'origin' is your upstream
 319 remote branch, using:
 320
 321         $ tig log origin..HEAD
 322
 323 will list what will be pushed to the remote branch. Optionally, the ending
 324 'HEAD' can be left out since it is implied.
 325
 326 Limiting by Reachability
 327 ~~~~~~~~~~~~~~~~~~~~~~~~
 328
 329 Git interprets the range specifier "tag-1.0..tag-2.0" as "all commits
 330 reachable from 'tag-2.0' but not from 'tag-1.0'".  Where reachability refers
 331 to what commits are ancestors (or part of the history) of the branch or tagged
 332 revision in question.
 333
 334 If you prefer to specify which commit to preview in this way use the
 335 following:
 336
 337         $ tig log tag-2.0 ^tag-1.0
 338
 339 You can think of '^' as a negation operator. Using this alternate syntax, it
 340 is possible to further prune commits by specifying multiple branch cut offs.
 341
 342 Combining Revisions Specification
 343 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 344
 345 Revisions options can to some degree be combined, which makes it possible to
 346 say "show at most 20 commits from within the last month that changed files
 347 under the Documentation/ directory."
 348
 349         $ tig -- --since=1.month -n20 -- Documentation/
 350
 351 Examining All Repository References
 352 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 353
 354 In some cases, it can be useful to query changes across all references in a
 355 repository. An example is to ask "did any line of development in this
 356 repository change a particular file within the last week". This can be
 357 accomplished using:
 358
 359         $ tig -- --all --since=1.week -- Makefile
 360
 361 include::BUGS[]
 362
 363 Copyright
 364 ---------
 365
 366 Copyright (c) 2006 Jonas Fonseca <fonseca@diku.dk>
 367
 368 This program is free software; you can redistribute it and/or modify
 369 it under the terms of the GNU General Public License as published by
 370 the Free Software Foundation; either version 2 of the License, or
 371 (at your option) any later version.
 372
 373 References and Related Tools
 374 ----------------------------
 375
 376 include::SITES[]
 377
 378 Git porcelains:
 379
 380  - link:http://www.kernel.org/pub/software/scm/git/docs/[git],
 381  - link:http://www.kernel.org/pub/software/scm/cogito/docs/[Cogito]
 382
 383 Other git repository browsers:
 384
 385  - gitk(1)
 386  - qgit(1)
 387  - gitview(1)