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 [options] [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 a 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 are 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 author 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 refs view
107 Displays the branches, remotes and tags 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 unstaged files being tracked or
115 file content of untracked files.
116 The stash view
118 Displays the list of stashes in the repository.
119 The grep view
121 Displays a list of files and all the lines that matches a search
122 pattern.
123 The pager view
125 Is used for displaying both input from stdin and output from Git
126 commands entered in the internal prompt.
127 The help view
129 Displays a quick reference of key bindings.
130 Browsing State and User-defined Commands
132 The viewer keeps track of both what head and commit ID you are
133 currently viewing. The commit ID will follow the cursor line and change
134 every time you highlight a different commit. Whenever you reopen the
135 diff view it will be reloaded, if the commit ID changed. The head ID is
136 used when opening the main and log view to indicate from what revision
137 to show history.
138 Some of the commands used or provided by Tig can be configured. This
140 goes for some of the environment variables as well as the external
141 commands. These user-defined commands can use arguments that refer to
142 the current browsing state by using one of the following variables.
143 Table 1. Browsing state variables
145 %(head) The currently viewed head
146 ID. Defaults to HEAD
147 %(commit) The currently selected
149 commit ID.
150 %(blob) The currently selected
152 blob ID.
153 %(branch) The currently selected
155 branch name.
156 %(remote) The currently selected
158 remote name. For remote
159 branches %(branch) will
160 contain the branch name.
161 %(tag) The currently selected tag
163 name.
164 %(stash) The currently selected
166 stash name.
167 %(directory) The current directory path
169 in the tree view or "." if
170 undefined.
171 %(file) The currently selected
173 file.
174 %(lineno) The currently selected
176 line number. Defaults to
177 0.
178 %(ref) The reference given to
180 blame or HEAD if
181 undefined.
182 %(revargs) The revision arguments
184 passed on the command
185 line.
186 %(fileargs) The file arguments passed
188 on the command line.
189 %(cmdlineargs) All other options passed
191 on the command line.
192 %(diffargs) Options from diff-options
194 or TIG_DIFF_OPTS used by
195 the diff and stage view.
196 %(blameargs) Options from blame-options
198 used by the blame view.
199 %(logargs) Options from log-options
203 used by the log view.
204 %(mainargs) Options from main-options
206 used by the main view.
207 %(prompt) Prompt for the argument
209 value. Optionally specify
210 a custom prompt using
211 "%(prompt Enter branch
212 name: )"
213 %(text) The text of the currently
215 selected line.
216 %(repo:head) The name of the checked
218 out branch, e.g. master
219 %(repo:head-id) The commit ID of the
221 checked out branch.
222 %(repo:remote) The remote associated with
224 the checked out branch,
225 e.g. origin/master.
226 %(repo:cdup) The path to change
228 directory to the
229 repository root, e.g. ../
230 %(repo:prefix) The path prefix of the
232 current work directory,
233 e.g subdir/.
234 %(repo:git-dir) The path to the Git
236 directory, e.g.
237 /src/repo/.git.
238 %(repo:worktree) The worktree path, if
240 defined.
241 %(repo:is-inside-work-tree) Whether Tig is running
243 inside a work tree, either
244 true or false.
245 Example user-defined commands:
248 · Allow to amend the last commit:
250 bind generic + !git commit --amend
252 · Copy commit ID to clipboard:
254 bind generic 9 !@sh -c "echo -n %(commit) | xclip -selection c"
256 · Add/edit notes for the current commit used during a review:
258 bind generic T !git notes edit %(commit)
260 · Enter Git’s interactive add for fine-grained staging of file
262 content:
263 bind generic I !git add -i %(file)
265 · Rebase current branch on top of the selected branch:
267 bind refs 3 !git rebase -i %(branch)
269 Title Windows
271 Each view has a title window which shows the name of the view, current
272 commit ID if available, and where the view is positioned:
273 [main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
275 By default, the title of the current view is highlighted using bold
278 font. For long loading views (taking over 3 seconds) the time since
279 loading started will be appended:
280 [main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
282
285 Several options related to the interface with Git can be configured via
286 environment options.
287 Configuration Files
289 Upon startup, Tig first reads the system wide configuration file
290 ({sysconfdir}/tigrc by default) and then proceeds to read the user’s
291 configuration file (~/.tigrc or $XDG_CONFIG_HOME/tig/config by
292 default). The paths to either of these files can be overridden through
293 the following environment variables:
294 TIGRC_USER
296 Path of the user configuration file.
297 TIGRC_SYSTEM
299 Path of the system wide configuration file.
300 History Files
302 If compiled with readline support, Tig writes a persistent command and search
304 history to `~/.tig_history` or `$XDG_DATA_HOME/tig/history`.
305 [[repo-refs]]
307 Repository References
308 Commits that are referenced by tags and branch heads will be marked by
311 the reference name surrounded by [ and ]:
312 2006-03-26 19:42 Petr Baudis | [cogito-0.17.1] Cogito 0.17.1
314 If you want to limit what branches are shown, say only show branches
317 named master or those which start with the feature/ prefix, you can do
318 it by setting the following variable:
319 $ TIG_LS_REMOTE="git ls-remote . master feature/*" tig
321 Or set the variable permanently in your environment.
324 TIG_LS_REMOTE
326 Command for retrieving all repository references. The command
327 should output data in the same format as git-ls-remote(1). Defaults
328 to:
329 git ls-remote .
331 Diff options
334 It is possible to alter how diffs are shown by the diff view. If for
335 example you prefer to have commit and author dates shown as relative
336 dates, use:
337 $ TIG_DIFF_OPTS="--relative-date" tig
339 Or set the variable permanently in your environment.
342
344 Below the default key bindings are shown.
345 View Switching
347 Key Action
348 m Switch to main view.
350 d Switch to diff view.
352 l Switch to log view.
354 p Switch to pager view.
356 t Switch to (directory) tree
358 view.
359 f Switch to (file) blob
361 view.
362 g Switch to grep view.
364 b Switch to blame view.
366 r Switch to refs view.
368 y Switch to stash view.
370 h Switch to help view
372 s Switch to status view
374 c Switch to stage view
376 View Manipulation
379 Key Action
380 q Close view, if multiple
382 views are open it will
383 jump back to the previous
384 view in the view stack. If
385 it is the last open view
386 it will quit. Use Q to
387 quit all views at once.
388 Enter This key is "context
390 sensitive" depending on
391 what view you are
392 currently in. When in log
393 view on a commit line or
394 in the main view, split
395 the view and show the
396 commit diff. In the diff
397 view pressing Enter will
398 simply scroll the view one
399 line down.
400 Tab Switch to next view.
402 R Reload and refresh the
406 current view.
407 O Maximize the current view
409 to fill the whole display.
410 Up This key is "context
412 sensitive" and will move
413 the cursor one line up.
414 However, if you opened a
415 diff view from the main
416 view (split- or
417 full-screen) it will
418 change the cursor to point
419 to the previous commit in
420 the main view and update
421 the diff view to display
422 it. If you prefer this key
423 to move the cursor or
424 scroll within the diff
425 view instead, use bind
426 diff <Up> move-up or bind
427 diff <Up> scroll-line-up,
428 respectively.
429 Down Similar to Up but will
431 move down.
432 , Move to parent. In the
434 tree view, this means
435 switch to the parent
436 directory. In the blame
437 view it will load blame
438 for the parent commit. For
439 merges the parent is
440 queried.
441 View Specific Actions
444 Key Action
445 u Update status of file. In
447 the status view, this
448 allows you to add an
449 untracked file or stage
450 changes to a file for next
451 commit (similar to running
452 git-add <filename>). In
453 the stage view, when
454 pressing this on a diff
455 chunk line stages only
456 that chunk for next
457 commit, when not on a diff
458 chunk line all changes in
459 the displayed diff are
460 staged.
461 M Resolve unmerged file by
463 launching
464 git-mergetool(1). Note, to
465 work correctly this might
466 require some initial
467 configuration of your
468 preferred merge tool. See
469 the manpage of
470 git-mergetool(1).
471 ! Checkout file with
474 unstaged changes. This
475 will reset the file to
476 contain the content it had
477 at last commit.
478 1 Stage single diff line.
480 @ Move to next chunk in the
482 stage view.
483 ] Increase the diff context.
485 [ Decrease the diff context.
487 Cursor Navigation
490 Key Action
491 k Move cursor one line up.
493 j Move cursor one line down.
495 PgUp,-,a Move cursor one page up.
497 PgDown, Space Move cursor one page down.
499 End Jump to last line.
501 Home Jump to first line.
503 Scrolling
506 Key Action
507 Insert Scroll view one line up.
509 Delete Scroll view one line down.
511 ScrollBack Scroll view one page up.
513 ScrollFwd Scroll view one page down.
515 Left Scroll view one column
517 left.
518 Right Scroll view one column
520 right.
521 | Scroll view to the first
523 column.
524 Searching
527 Key Action
528 / Search the view. Opens a
530 prompt for entering search
531 regexp to use.
532 ? Search backwards in the
534 view. Also prompts for
535 regexp.
536 n Find next match for the
538 current search regexp.
539 N Find previous match for
542 the current search regexp.
543 Misc
546 Key Action
547 Q Quit.
549 <C-L> Redraw screen.
551 z Stop all background
553 loading. This can be
554 useful if you use Tig in a
555 repository with a long
556 history without limiting
557 the revision log.
558 v Show version.
560 o Open option menu
562 # Toggle line numbers
564 on/off.
565 D Toggle date display
567 on/off/relative/relative-compact/custom
568 A Toggle author display
570 on/off/abbreviated/email/email user
571 name.
572 G Toggle revision graph visualization
574 on/off.
575 ~ Toggle (line) graphics mode
577 F Toggle reference display on/off (tag
579 and branch names).
580 W Toggle ignoring whitespace on/off for
582 diffs
583 X Toggle commit ID display on/off
585 % Toggle file filtering in order to see
587 the full diff instead of only the diff
588 concerning the currently selected file.
589 $ Toggle highlighting of commit title
591 overflow.
592 : Open prompt. This allows you to specify
594 what command to run and also to jump to
595 a specific line, e.g. :23
596 e Open file in editor.
598 Prompt
601 Key Action
602 :<number> Jump to the specific line
604 number, e.g. :80.
605 :<sha> Jump to a specific commit,
610 e.g. :2f12bcc.
611 :<x> Execute the corresponding
613 key binding, e.g. :q.
614 :!<command> Execute a system command
616 in a pager, e.g. :!git log
617 -p.
618 :<action> Execute a Tig command,
620 e.g. :edit.
621 :goto <rev> Jump to a specific
623 revision, e.g. :goto
624 %(commit)^2 to goto the
625 current commit’s 2nd
626 parent or :goto
627 some/branch to goto the
628 commit denoting the branch
629 some/branch.
630 :save-display <file> Save current display to
632 <file>.
633 :save-options <file> Save current options to
635 <file>.
636 :save-view <file> Save view info to <file>
638 (for testing purposes).
639 :script <file> Execute commands from
641 <file>.
642 :exec <flags><args...> Execute command using
644 <args> with external
645 user-defined command
646 option flags defined in
647 <flags>.
648 :echo <args...> Display text in the status
650 bar.
651 External Commands
654 For more custom needs, external commands provide a way to easily
655 execute a script or program. They are bound to keys and use information
656 from the current browsing state, such as the current commit ID. Tig
657 comes with the following built-in external commands:
658 Keymap Key Action
660 main C git cherry-pick
662 %(commit)
663 status C git commit
665 generic G git gc
667
670 This section describes various ways to specify what revisions to
671 display or otherwise limit the view to. Tig does not itself parse the
672 described revision options so refer to the relevant Git man pages for
673 further information. Relevant man pages besides git-log(1) are
674 git-diff(1) and git-rev-list(1).
675 You can tune the interaction with Git by making use of the options
677 explained in this section. For example, by configuring the environment
678 variable described in the section on diff options.
679 Limit by Path Name
681 If you are interested only in those revisions that made changes to a
682 specific file (or even several files) list the files like this:
683 $ tig Makefile README
685 To avoid ambiguity with Tig’s subcommands or repository references such
688 as tag names, be sure to separate file names from other Git options
689 using "--". So if you have a file named status it will clash with the
690 status subcommand, and thus you will have to use:
691 $ tig -- status
693 Limit by Date or Number
696 To speed up interaction with Git, you can limit the amount of commits
697 to show both for the log and main view. Either limit by date using e.g.
698 --since=1.month or limit by the number of commits using -n400.
699 If you are only interested in changes that happened between two dates
701 you can use:
702 $ tig --after="May 5th" --before="2006-05-16 15:44"
704 Note
707 If you want to avoid having to quote dates containing spaces you
708 can use "." instead, e.g. --after=May.5th.
709 Limiting by Commit Ranges
711 Alternatively, commits can be limited to a specific range, such as "all
712 commits between tag-1.0 and tag-2.0". For example:
713 $ tig tag-1.0..tag-2.0
715 This way of commit limiting makes it trivial to only browse the commits
718 which haven’t been pushed to a remote branch. Assuming origin is your
719 upstream remote branch, using:
720 $ tig origin..HEAD
722 will list what will be pushed to the remote branch. Optionally, the
725 ending HEAD can be left out since it is implied.
726 Limiting by Reachability
728 Git interprets the range specifier "tag-1.0..tag-2.0" as "all commits
729 reachable from tag-2.0 but not from tag-1.0". Where reachability refers
730 to what commits are ancestors (or part of the history) of the branch or
731 tagged revision in question.
732 If you prefer to specify which commit to preview in this way use the
734 following:
735 $ tig tag-2.0 ^tag-1.0
737 You can think of ^ as a negation operator. Using this alternate syntax,
740 it is possible to further prune commits by specifying multiple branch
741 cut offs.
742 Combining Revisions Specification
744 Revision options can to some degree be combined, which makes it
745 possible to say "show at most 20 commits from within the last month
746 that changed files under the Documentation/ directory."
747 $ tig --since=1.month -n20 -- Documentation/
749 Examining All Repository References
752 In some cases, it can be useful to query changes across all references
753 in a repository. An example is to ask "did any line of development in
754 this repository change a particular file within the last week". This
755 can be accomplished using:
756 $ tig --all --since=1.week -- Makefile
758
761 Please visit Tig’s home page[1] or main Git repository[2] for
762 information about new releases and how to report bugs and feature
763 requests.
764
766 Copyright (c) 2006-2014 Jonas Fonseca <jonas.fonseca@gmail.com[3]>
767 This program is free software; you can redistribute it and/or modify it
769 under the terms of the GNU General Public License as published by the
770 Free Software Foundation; either version 2 of the License, or (at your
771 option) any later version.
772
774 Manpages:
775 · tig(1)
777 · tigrc(5)
779
781 1. home page
782 https://jonas.github.io/tig
783 2. main Git repository
785 https://github.com/jonas/tig
786 3. jonas.fonseca@gmail.com
788 mailto:jonas.fonseca@gmail.com
789Tig 2.4.1 07/26/2018 TIGMANUAL(7)