1TIGMANUAL(7) Tig Manual TIGMANUAL(7)
2
6 tigmanual - text-mode interface for git
7
9 tig [options] [revisions] [--] [paths]
10 tig show [options] [revisions] [--] [paths]
11 tig blame [rev] path
12 tig status
13 tig < [git command output]
14
17 This is the manual for tig, the ncurses-based text-mode interface for
18 git. Tig allows you to browse changes in a git repository and can
19 additionally act as a pager for output of various git commands. When
20 used as a pager, it will display input from stdin and colorize it.
21 When browsing repositories, tig uses the underlying git commands to
23 present the user with various views, such as summarized commit log and
24 showing the commit with the log message, diffstat, and the diff.
25
27 Pager Mode
28 If stdin is a pipe, any log or diff options will be ignored and the
29 pager view will be opened loading data from stdin. The pager mode can
30 be used for colorizing output from various git commands.
31 Example on how to colorize the output of git-show(1):
33 $ git show | tig
35 Git Command Options
38 All git command options specified on the command line will be passed to
39 the given command and all will be shell quoted before they are passed
40 to the shell.
41 Note
43 If you specify options for the main view, you should not use the
44 --pretty option as this option will be set automatically to the
45 format expected by the main view.
46 Example on how to view a commit and show both author and committer
48 information:
49 $ tig show --pretty=fuller
51 See the section on specifying revisions for an introduction to revision
54 options supported by the git commands. For details on specific git
55 command options, refer to the man page of the command in question.
56
58 The display consists of a status window on the last line of the screen
59 and one or more views. The default is to only show one view at the time
60 but it is possible to split both the main and log view to also show the
61 commit diff.
62 If you are in the log view and press Enter when the current line is a
64 commit line, such as:
65 commit 4d55caff4cc89335192f3e566004b4ceef572521
67 You will split the view so that the log view is displayed in the top
70 window and the diff view in the bottom window. You can switch between
71 the two views by pressing Tab. To maximize the log view again, simply
72 press l.
73 Views
75 Various views of a repository is presented. Each view is based on
76 output from an external command, most often git log, git diff, or git
77 show.
78 The main view
80 Is the default view, and it shows a one line summary of each commit
81 in the chosen list of revisions. The summary includes commit date,
82 author, and the first line of the log message. Additionally, any
83 repository references, such as tags, will be shown.
84 The log view
86 Presents a more rich view of the revision log showing the whole log
87 message and the diffstat.
88 The diff view
90 Shows either the diff of the current working tree, that is, what
91 has changed since the last commit, or the commit diff complete with
92 log message, diffstat and diff.
93 The tree view
95 Lists directory trees associated with the current revision allowing
96 subdirectories to be descended or ascended and file blobs to be
97 viewed.
98 The blob view
100 Displays the file content or "blob" of data associated with a file
101 name.
102 The blame view
104 Displays the file content annotated or blamed by commits.
105 The branch view
107 Displays the branches in the repository.
108 The status view
110 Displays status of files in the working tree and allows changes to
111 be staged/unstaged as well as adding of untracked files.
112 The stage view
114 Displays diff changes for staged or unstanged files being tracked
115 or file content of untracked files.
116 The pager view
118 Is used for displaying both input from stdin and output from git
119 commands entered in the internal prompt.
120 The help view
122 Displays a quick reference of key bindings.
123 Browsing State and User-defined Commands
125 The viewer keeps track of both what head and commit ID you are
126 currently viewing. The commit ID will follow the cursor line and change
127 every time you highlight a different commit. Whenever you reopen the
128 diff view it will be reloaded, if the commit ID changed. The head ID is
129 used when opening the main and log view to indicate from what revision
130 to show history.
131 Some of the commands used or provided by tig can be configured. This
133 goes for some of the environment variables as well as the external
134 commands. These user-defined commands can use arguments that refer to
135 the current browsing state by using one of the following variables.
136 Table 1. Browsing state variables
138 %(head) The currently viewed head
139 ID. Defaults to HEAD
140 %(commit) The currently selected
142 commit ID.
143 %(blob) The currently selected
145 blob ID.
146 %(directory) The current directory path
148 in the tree view; empty
149 for the root directory.
150 %(file) The currently selected
152 file.
153 %(ref) The reference given to
155 blame or HEAD if
156 undefined.
157 Title Windows
160 Each view has a title window which shows the name of the view, current
161 commit ID if available, and where the view is positioned:
162 [main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
164 By default, the title of the current view is highlighted using bold
167 font. For long loading views (taking over 3 seconds) the time since
168 loading started will be appended:
169 [main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
171
174 Several options related to the interface with git can be configured via
175 environment options.
176 Configuration Files
178 Upon startup, tig first reads the system wide configuration file
179 ({sysconfdir}/tigrc by default) and then proceeds to read the user’s
180 configuration file (~/.tigrc by default). The paths to either of these
181 files can be overridden through the following environment variables:
182 TIGRC_USER
184 Path of the user configuration file.
185 TIGRC_SYSTEM
187 Path of the system wide configuration file.
188 Repository References
190 Commits that are referenced by tags and branch heads will be marked by
191 the reference name surrounded by [ and ]:
192 2006-03-26 19:42 Petr Baudis | [cogito-0.17.1] Cogito 0.17.1
194 If you want to filter what branches gets shown, say limit to only show
197 branches named master or which starts with the jf/ prefix, you can do
198 it by setting the following variable:
199 $ TIG_LS_REMOTE="git ls-remote . master jf/*" tig
201 Or set the variable permanently in your environment.
204 TIG_LS_REMOTE
206 Set command for retrieving all repository references. The command
207 should output data in the same format as git-ls-remote(1). Defaults
208 to:
209 git ls-remote .
211 History Commands
214 It is possible to alter which commands are used for the different
215 views. If for example you prefer commits in the main view to be sorted
216 by date and only show 500 commits, use:
217 $ TIG_MAIN_CMD="git log --date-order -n500 --pretty=raw %(head)" tig
219 Or set the variable permanently in your environment.
222 Notice, how %(head) is used to specify the commit reference.
224 TIG_DIFF_CMD
226 The command used for the diff view. Defaults to:
227 git show --pretty=fuller --no-color --root
229 --patch-with-stat --find-copies-harder -C %(commit)
230 TIG_LOG_CMD
233 The command used for the log view. If you prefer to have both
234 author and committer shown in the log view be sure to pass
235 --pretty=fuller to git log. Defaults to:
236 git log --no-color --cc --stat -n100 %(head)
238 TIG_MAIN_CMD
241 The command used for the main view. Note, you must always specify
242 the option: --pretty=raw since the main view parser expects to read
243 that format.
244 git log --no-color --pretty=raw --parents --topo-order %(head)
246 Tree Commands
249 TIG_TREE_CMD
250 The command used for the tree view. Defaults to:
251 git ls-tree %(commit) %(directory)
253 TIG_BLOB_CMD
256 The command used for the blob view. Defaults to:
257 git cat-file blob %(blob)
259
262 Below the default key bindings are shown.
263 View Switching
265 Key Action
266 m Switch to main view.
269 d Switch to diff view.
271 l Switch to log view.
273 p Switch to pager view.
275 t Switch to (directory) tree
277 view.
278 f Switch to (file) blob
280 view.
281 B Switch to blame view.
283 H Switch to branch view.
285 h Switch to help view
287 S Switch to status view
289 c Switch to stage view
291 View Manipulation
294 Key Action
295 q Close view, if multiple
297 views are open it will
298 jump back to the previous
299 view in the view stack. If
300 it is the last open view
301 it will quit. Use Q to
302 quit all views at once.
303 Enter This key is "context
305 sensitive" depending on
306 what view you are
307 currently in. When in log
308 view on a commit line or
309 in the main view, split
310 the view and show the
311 commit diff. In the diff
312 view pressing Enter will
313 simply scroll the view one
314 line down.
315 Tab Switch to next view.
317 R Reload and refresh the
319 current view.
320 M Maximize the current view
322 to fill the whole display.
323 Up This key is "context
337 sensitive" and will move
338 the cursor one line up.
339 However, if you opened a
340 diff view from the main
341 view (split- or
342 full-screen) it will
343 change the cursor to point
344 to the previous commit in
345 the main view and update
346 the diff view to display
347 it.
348 Down Similar to Up but will
350 move down.
351 , Move to parent. In the
353 tree view, this means
354 switch to the parent
355 directory. In the blame
356 view it will load blame
357 for the parent commit. For
358 merges the parent is
359 queried.
360 View Specific Actions
363 Key Action
364 u Update status of file. In
366 the status view, this
367 allows you to add an
368 untracked file or stage
369 changes to a file for next
370 commit (similar to running
371 git-add <filename>). In
372 the stage view, when
373 pressing this on a diff
374 chunk line stages only
375 that chunk for next
376 commit, when not on a diff
377 chunk line all changes in
378 the displayed diff is
379 staged.
380 M Resolve unmerged file by
382 launching
383 git-mergetool(1). Note, to
384 work correctly this might
385 require some initial
386 configuration of your
387 preferred merge tool. See
388 the manpage of
389 git-mergetool(1).
390 ! Checkout file with
392 unstaged changes. This
393 will reset the file to
394 contain the content it had
395 at last commit.
396 @ Move to next chunk in the
398 stage view.
399 Cursor Navigation
402 Key Action
403 k Move cursor one line up.
406 j Move cursor one line down.
408 PgUp,-,a Move cursor one page up.
410 PgDown, Space Move cursor one page down.
412 End Jump to last line.
414 Home Jump to first line.
416 Scrolling
419 Key Action
420 Insert Scroll view one line up.
422 Delete Scroll view one line down.
424 w Scroll view one page up.
426 s Scroll view one page down.
428 Left Scroll view one column
430 left.
431 Right Scroll view one column
433 right.
434 Searching
437 Key Action
438 / Search the view. Opens a
440 prompt for entering search
441 regexp to use.
442 ? Search backwards in the
444 view. Also prompts for
445 regexp.
446 n Find next match for the
448 current search regexp.
449 N Find previous match for
451 the current search regexp.
452 Misc
455 Key Action
456 Q Quit.
458 r Redraw screen.
460 z Stop all background
462 loading. This can be
463 useful if you use tig in a
464 repository with a long
465 history without limiting
466 the revision log.
467 v Show version.
469 o Open option menu
471 . Toggle line numbers
475 on/off.
476 D Toggle date display
478 on/off.
479 A Toggle author display
481 on/off.
482 g Toggle revision graph
484 visualization on/off.
485 F Toggle reference display
487 on/off (tag and branch
488 names).
489 : Open prompt. This allows
491 you to specify what git
492 command to run. Example
493 :log -p. You can also use
494 this to jump to a specific
495 line by typing
496 :<linenumber>, e.g. :80.
497 e Open file in editor.
499 External Commands
502 For more custom needs, external commands provide a way to easily
503 execute a script or program. They are bound to keys and use information
504 from the current browsing state, such as the current commit ID. Tig
505 comes with the following built-in external commands:
506 Keymap Key Action
508 main C git cherry-pick
510 %(commit)
511 status C git commit
513 generic G git gc
515
518 This section describes various ways to specify what revisions to
519 display or otherwise limit the view to. Tig does not itself parse the
520 described revision options so refer to the relevant git man pages for
521 further information. Relevant man pages besides git-log(1) are
522 git-diff(1) and git-rev-list(1).
523 You can tune the interaction with git by making use of the options
525 explained in this section. For example, by configuring the environment
526 variables described in the section on history commands.
527 Limit by Path Name
529 If you are interested only in those revisions that made changes to a
530 specific file (or even several files) list the files like this:
531 $ tig Makefile README
533 To avoid ambiguity with tig’s subcommands or repository references such
536 as tag name, be sure to separate file names from other git options
537 using "--". So if you have a file named status it will clash with the
538 status subcommand, and thus you will have to use:
539 $ tig -- status
541 Limit by Date or Number
544 To speed up interaction with git, you can limit the amount of commits
545 to show both for the log and main view. Either limit by date using e.g.
546 --since=1.month or limit by the number of commits using -n400.
547 If you are only interested in changed that happened between two dates
549 you can use:
550 $ tig --after="May 5th" --before="2006-05-16 15:44"
552 Note
555 If you want to avoid having to quote dates containing spaces you
556 can use "." instead, e.g. --after=May.5th.
557 Limiting by Commit Ranges
559 Alternatively, commits can be limited to a specific range, such as "all
560 commits between tag-1.0 and tag-2.0". For example:
561 $ tig tag-1.0..tag-2.0
563 This way of commit limiting makes it trivial to only browse the commits
566 which haven’t been pushed to a remote branch. Assuming origin is your
567 upstream remote branch, using:
568 $ tig origin..HEAD
570 will list what will be pushed to the remote branch. Optionally, the
573 ending HEAD can be left out since it is implied.
574 Limiting by Reachability
576 Git interprets the range specifier "tag-1.0..tag-2.0" as "all commits
577 reachable from tag-2.0 but not from tag-1.0". Where reachability refers
578 to what commits are ancestors (or part of the history) of the branch or
579 tagged revision in question.
580 If you prefer to specify which commit to preview in this way use the
582 following:
583 $ tig tag-2.0 ^tag-1.0
585 You can think of ^ as a negation operator. Using this alternate syntax,
588 it is possible to further prune commits by specifying multiple branch
589 cut offs.
590 Combining Revisions Specification
592 Revisions options can to some degree be combined, which makes it
593 possible to say "show at most 20 commits from within the last month
594 that changed files under the Documentation/ directory."
595 $ tig --since=1.month -n20 -- Documentation/
597 Examining All Repository References
600 In some cases, it can be useful to query changes across all references
601 in a repository. An example is to ask "did any line of development in
602 this repository change a particular file within the last week". This
603 can be accomplished using:
604 $ tig --all --since=1.week -- Makefile
606
609 Known bugs and problems:
610 · Proper locale support: in it’s current state tig is pretty much
612 UTF-8 only.
613
615 Copyright (c) 2006-2009 Jonas Fonseca <fonseca@diku.dk[1]>
616 This program is free software; you can redistribute it and/or modify it
618 under the terms of the GNU General Public License as published by the
619 Free Software Foundation; either version 2 of the License, or (at your
620 option) any later version.
621
623 Manpages:
624 · manpage:tig[1]
626 · manpage:tigrc[5]
628 Online resources:
630 · Homepage: http://jonas.nitro.dk/tig/
632 · Manual: http://jonas.nitro.dk/tig/manual.html
634 · Tarballs: http://jonas.nitro.dk/tig/releases/
636 · Git URL: git://repo.or.cz/tig.git (mirror) or
638 http://jonas.nitro.dk/tig/tig.git (master)
639 · Gitweb: http://repo.or.cz/w/tig.git
641
643 1. fonseca@diku.dk
644 mailto:fonseca@diku.dk
645Tig 0.15 11/20/2009 TIGMANUAL(7)