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 reflog view
90 Presents a view of the reflog allowing to navigate the repo
91 history.
92 The diff view
94 Shows either the diff of the current working tree, that is, what
95 has changed since the last commit, or the commit diff complete with
96 log message, diffstat and diff.
97 The tree view
99 Lists directory trees associated with the current revision allowing
100 subdirectories to be descended or ascended and file blobs to be
101 viewed.
102 The blob view
104 Displays the file content or "blob" of data associated with a file
105 name.
106 The blame view
108 Displays the file content annotated or blamed by commits.
109 The refs view
111 Displays the branches, remotes and tags in the repository.
112 The status view
114 Displays status of files in the working tree and allows changes to
115 be staged/unstaged as well as adding of untracked files.
116 The stage view
118 Displays diff changes for staged or unstaged files being tracked or
119 file content of untracked files.
120 The stash view
122 Displays the list of stashes in the repository.
123 The grep view
125 Displays a list of files and all the lines that matches a search
126 pattern.
127 The pager view
129 Is used for displaying both input from stdin and output from Git
130 commands entered in the internal prompt.
131 The help view
133 Displays a quick reference of key bindings.
134 Browsing State and User-defined Commands
136 The viewer keeps track of both what head and commit ID you are
137 currently viewing. The commit ID will follow the cursor line and change
138 every time you highlight a different commit. Whenever you reopen the
139 diff view it will be reloaded, if the commit ID changed. The head ID is
140 used when opening the main and log view to indicate from what revision
141 to show history.
142 Some of the commands used or provided by Tig can be configured. This
144 goes for some of the environment variables as well as the external
145 commands. These user-defined commands can use arguments that refer to
146 the current browsing state by using one of the following variables.
147 Table 1. Browsing state variables
149 %(head) The currently viewed head
150 ID. Defaults to HEAD
151 %(commit) The currently selected
153 commit ID.
154 %(blob) The currently selected
156 blob ID.
157 %(branch) The currently selected
159 branch name.
160 %(remote) The currently selected
162 remote name. For remote
163 branches %(branch) will
164 contain the branch name.
165 %(tag) The currently selected tag
167 name.
168 %(stash) The currently selected
170 stash name.
171 %(directory) The current directory path
173 in the tree view or "." if
174 undefined.
175 %(file) The currently selected
177 file.
178 %(lineno) The currently selected
180 line number. Defaults to
181 0.
182 %(ref) The reference given to
184 blame or HEAD if
185 undefined.
186 %(revargs) The revision arguments
188 passed on the command
189 line.
190 %(fileargs) The file arguments passed
192 on the command line.
193 %(cmdlineargs) All other options passed
195 on the command line.
196 %(diffargs) Options from diff-options
201 or TIG_DIFF_OPTS used by
202 the diff and stage view.
203 %(blameargs) Options from blame-options
205 used by the blame view.
206 %(logargs) Options from log-options
208 used by the log view.
209 %(mainargs) Options from main-options
211 used by the main view.
212 %(prompt) Prompt for the argument
214 value. Optionally specify
215 a custom prompt using
216 "%(prompt Enter branch
217 name: )"
218 %(text) The text of the currently
220 selected line.
221 %(repo:head) The name of the checked
223 out branch, e.g. master
224 %(repo:head-id) The commit ID of the
226 checked out branch.
227 %(repo:remote) The remote associated with
229 the checked out branch,
230 e.g. origin/master.
231 %(repo:cdup) The path to change
233 directory to the
234 repository root, e.g. ../
235 %(repo:prefix) The path prefix of the
237 current work directory,
238 e.g subdir/.
239 %(repo:git-dir) The path to the Git
241 directory, e.g.
242 /src/repo/.git.
243 %(repo:worktree) The worktree path, if
245 defined.
246 %(repo:is-inside-work-tree) Whether Tig is running
248 inside a work tree, either
249 true or false.
250 Example user-defined commands:
253 · Allow to amend the last commit:
255 bind generic + !git commit --amend
257 · Copy commit ID to clipboard:
259 bind generic 9 !@sh -c "echo -n %(commit) | xclip -selection c"
261 · Add/edit notes for the current commit used during a review:
263 bind generic T !git notes edit %(commit)
265 · Enter Git’s interactive add for fine-grained staging of file
267 content:
268 bind generic I !git add -i %(file)
270 · Rebase current branch on top of the selected branch:
272 bind refs 3 !git rebase -i %(branch)
274 Title Windows
276 Each view has a title window which shows the name of the view, current
277 commit ID if available, and where the view is positioned:
278 [main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
280 By default, the title of the current view is highlighted using bold
283 font. For long loading views (taking over 3 seconds) the time since
284 loading started will be appended:
285 [main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
287
290 Several options related to the interface with Git can be configured via
291 environment options.
292 Configuration Files
294 Upon startup, Tig first reads the system wide configuration file
295 ({sysconfdir}/tigrc by default) and then proceeds to read the user’s
296 configuration file (~/.tigrc or $XDG_CONFIG_HOME/tig/config by
297 default). The paths to either of these files can be overridden through
298 the following environment variables:
299 TIGRC_USER
301 Path of the user configuration file.
302 TIGRC_SYSTEM
304 Path of the system wide configuration file.
305 History Files
307 If compiled with readline support, Tig writes a persistent command and
308 search history to ~/.tig_history or $XDG_DATA_HOME/tig/history.
309 Repository References
311 Commits that are referenced by tags and branch heads will be marked by
312 the reference name surrounded by [ and ]:
313 2006-03-26 19:42 Petr Baudis | [cogito-0.17.1] Cogito 0.17.1
315 If you want to limit what branches are shown, say only show branches
318 named master or those which start with the feature/ prefix, you can do
319 it by setting the following variable:
320 $ TIG_LS_REMOTE="git ls-remote . master feature/*" tig
322 Or set the variable permanently in your environment.
325 TIG_LS_REMOTE
327 Command for retrieving all repository references. The command
328 should output data in the same format as git-ls-remote(1). Defaults
329 to:
330 git ls-remote .
332 Diff options
335 It is possible to alter how diffs are shown by the diff view. If for
336 example you prefer to have commit and author dates shown as relative
337 dates, use:
338 $ TIG_DIFF_OPTS="--relative-date" tig
340 Or set the variable permanently in your environment.
343
345 Below the default key bindings are shown.
346 View Switching
348 Key Action
349 m Switch to main view.
351 d Switch to diff view.
353 l Switch to log view.
355 p Switch to pager view.
357 t Switch to (directory) tree
359 view.
360 f Switch to (file) blob
362 view.
363 g Switch to grep view.
365 b Switch to blame view.
367 r Switch to refs view.
369 y Switch to stash view.
371 h Switch to help view
373 s Switch to status view
375 c Switch to stage view
377 View Manipulation
380 Key Action
381 q Close view, if multiple
383 views are open it will
384 jump back to the previous
385 view in the view stack. If
386 it is the last open view
387 it will quit. Use Q to
388 quit all views at once.
389 Enter This key is "context
399 sensitive" depending on
400 what view you are
401 currently in. When in log
402 view on a commit line or
403 in the main view, split
404 the view and show the
405 commit diff. In the diff
406 view pressing Enter will
407 simply scroll the view one
408 line down.
409 Tab Switch to next view.
411 R Reload and refresh the
413 current view.
414 O Maximize the current view
416 to fill the whole display.
417 Up This key is "context
419 sensitive" and will move
420 the cursor one line up.
421 However, if you opened a
422 split view it will change
423 the cursor to point to the
424 previous commit in the
425 parent view and update the
426 child view to display it.
427 If you prefer this key to
428 move the cursor or scroll
429 within the diff view
430 instead, use bind diff
431 <Up> move-up or bind diff
432 <Up> scroll-line-up,
433 respectively.
434 Down Similar to Up but will
436 move down.
437 , Move to parent. In the
439 tree view, this means
440 switch to the parent
441 directory. In the blame
442 view it will load blame
443 for the parent commit. For
444 merges the parent is
445 queried.
446 View Specific Actions
449 Key Action
450 u Update status of file. In
465 the status view, this
466 allows you to add an
467 untracked file or stage
468 changes to a file for next
469 commit (similar to running
470 git-add <filename>). In
471 the stage view, when
472 pressing this on a diff
473 chunk line stages only
474 that chunk for next
475 commit, when not on a diff
476 chunk line all changes in
477 the displayed diff are
478 staged.
479 M Resolve unmerged file by
481 launching
482 git-mergetool(1). Note, to
483 work correctly this might
484 require some initial
485 configuration of your
486 preferred merge tool. See
487 the manpage of
488 git-mergetool(1).
489 ! Checkout file with
491 unstaged changes. This
492 will reset the file to
493 contain the content it had
494 at last commit.
495 1 Stage single diff line.
497 @ Move to next chunk in the
499 stage view.
500 ] Increase the diff context.
502 [ Decrease the diff context.
504 Cursor Navigation
507 Key Action
508 k Move cursor one line up.
510 j Move cursor one line down.
512 PgUp,-,a Move cursor one page up.
514 PgDown, Space Move cursor one page down.
516 End Jump to last line.
518 Home Jump to first line.
520 Scrolling
523 Key Action
524 Insert Scroll view one line up.
526 Delete Scroll view one line down.
528 ScrollBack Scroll view one page up.
531 ScrollFwd Scroll view one page down.
533 Left Scroll view one column
535 left.
536 Right Scroll view one column
538 right.
539 | Scroll view to the first
541 column.
542 Searching
545 Key Action
546 / Search the view. Opens a
548 prompt for entering search
549 regexp to use.
550 ? Search backwards in the
552 view. Also prompts for
553 regexp.
554 n Find next match for the
556 current search regexp.
557 N Find previous match for
559 the current search regexp.
560 Misc
563 Key Action
564 Q Quit.
566 <C-L> Redraw screen.
568 z Stop all background
570 loading. This can be
571 useful if you use Tig in a
572 repository with a long
573 history without limiting
574 the revision log.
575 v Show version.
577 o Open option menu
579 # Toggle line numbers
581 on/off.
582 D Toggle date display
584 on/off/relative/relative-compact/custom
585 A Toggle author display
587 on/off/abbreviated/email/email user
588 name.
589 G Toggle revision graph visualization
591 on/off.
592 ~ Toggle (line) graphics mode
594 F Toggle reference display on/off (tag
597 and branch names).
598 W Toggle ignoring whitespace on/off for
600 diffs
601 X Toggle commit ID display on/off
603 % Toggle file filtering in order to see
605 the full diff instead of only the diff
606 concerning the currently selected file.
607 $ Toggle highlighting of commit title
609 overflow.
610 H Go to the HEAD commit.
612 : Open prompt. This allows you to specify
614 what command to run and also to jump to
615 a specific line, e.g. :23
616 e Open file in editor.
618 Prompt
621 Key Action
622 :<number> Jump to the specific line
624 number, e.g. :80.
625 :<sha> Jump to a specific commit,
627 e.g. :2f12bcc.
628 :<x> Execute the corresponding
630 key binding, e.g. :q.
631 :!<command> Execute a system command
633 in a pager, e.g. :!git log
634 -p.
635 :<action> Execute a Tig command,
637 e.g. :edit.
638 :goto <rev> Jump to a specific
640 revision, e.g. :goto
641 %(commit)^2 to goto the
642 current commit’s 2nd
643 parent or :goto
644 some/branch to goto the
645 commit denoting the branch
646 some/branch.
647 :save-display <file> Save current display to
649 <file>.
650 :save-options <file> Save current options to
652 <file>.
653 :save-view <file> Save view info to <file>
655 (for testing purposes).
656 :script <file> Execute commands from
658 <file>.
659 :exec <flags><args...> Execute command using
663 <args> with external
664 user-defined command
665 option flags defined in
666 <flags>.
667 :echo <args...> Display text in the status
669 bar.
670 External Commands
673 For more custom needs, external commands provide a way to easily
674 execute a script or program. They are bound to keys and use information
675 from the current browsing state, such as the current commit ID. Tig
676 comes with the following built-in external commands:
677 Keymap Key Action
679 main C git cherry-pick
681 %(commit)
682 status C git commit
684 generic G git gc
686
689 This section describes various ways to specify what revisions to
690 display or otherwise limit the view to. Tig does not itself parse the
691 described revision options so refer to the relevant Git man pages for
692 further information. Relevant man pages besides git-log(1) are
693 git-diff(1) and git-rev-list(1).
694 You can tune the interaction with Git by making use of the options
696 explained in this section. For example, by configuring the environment
697 variable described in the section on diff options.
698 Limit by Path Name
700 If you are interested only in those revisions that made changes to a
701 specific file (or even several files) list the files like this:
702 $ tig Makefile README
704 To avoid ambiguity with Tig’s subcommands or repository references such
707 as tag names, be sure to separate file names from other Git options
708 using "--". So if you have a file named status it will clash with the
709 status subcommand, and thus you will have to use:
710 $ tig -- status
712 Limit by Date or Number
715 To speed up interaction with Git, you can limit the amount of commits
716 to show both for the log and main view. Either limit by date using e.g.
717 --since=1.month or limit by the number of commits using -n400.
718 If you are only interested in changes that happened between two dates
720 you can use:
721 $ tig --after="May 5th" --before="2006-05-16 15:44"
723 Note
726 If you want to avoid having to quote dates containing spaces you
727 can use "." instead, e.g. --after=May.5th.
728 Limiting by Commit Ranges
730 Alternatively, commits can be limited to a specific range, such as "all
731 commits between tag-1.0 and tag-2.0". For example:
732 $ tig tag-1.0..tag-2.0
734 This way of commit limiting makes it trivial to only browse the commits
737 which haven’t been pushed to a remote branch. Assuming origin is your
738 upstream remote branch, using:
739 $ tig origin..HEAD
741 will list what will be pushed to the remote branch. Optionally, the
744 ending HEAD can be left out since it is implied.
745 Limiting by Reachability
747 Git interprets the range specifier "tag-1.0..tag-2.0" as "all commits
748 reachable from tag-2.0 but not from tag-1.0". Where reachability refers
749 to what commits are ancestors (or part of the history) of the branch or
750 tagged revision in question.
751 If you prefer to specify which commit to preview in this way use the
753 following:
754 $ tig tag-2.0 ^tag-1.0
756 You can think of ^ as a negation operator. Using this alternate syntax,
759 it is possible to further prune commits by specifying multiple branch
760 cut offs.
761 Combining Revisions Specification
763 Revision options can to some degree be combined, which makes it
764 possible to say "show at most 20 commits from within the last month
765 that changed files under the Documentation/ directory."
766 $ tig --since=1.month -n20 -- Documentation/
768 Examining All Repository References
771 In some cases, it can be useful to query changes across all references
772 in a repository. An example is to ask "did any line of development in
773 this repository change a particular file within the last week". This
774 can be accomplished using:
775 $ tig --all --since=1.week -- Makefile
777
780 Please visit Tig’s home page[1] or main Git repository[2] for
781 information about new releases and how to report bugs and feature
782 requests.
783
785 Copyright (c) 2006-2014 Jonas Fonseca <jonas.fonseca@gmail.com[3]>
786 This program is free software; you can redistribute it and/or modify it
788 under the terms of the GNU General Public License as published by the
789 Free Software Foundation; either version 2 of the License, or (at your
790 option) any later version.
791
793 Manpages:
794 · tig(1)
796 · tigrc(5)
798
800 1. home page
801 https://jonas.github.io/tig
802 2. main Git repository
804 https://github.com/jonas/tig
805 3. jonas.fonseca@gmail.com
807 mailto:jonas.fonseca@gmail.com
808Tig 2.5.1 04/08/2020 TIGMANUAL(7)