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 %(refname) The currently selected
170 reference name including
171 the remote name for remote
172 branches.
173 %(stash) The currently selected
175 stash name.
176 %(directory) The current directory path
178 in the tree view or "." if
179 undefined.
180 %(file) The currently selected
182 file.
183 %(lineno) The currently selected
185 line number. Defaults to
186 0.
187 %(lineno_old) The currently selected
189 line number, before the
190 diff was applied. Defaults
191 to 0.
192 %(ref) The reference given to
194 blame or HEAD if
195 undefined.
196 %(revargs) The revision arguments
201 passed on the command
202 line.
203 %(fileargs) The file arguments passed
205 on the command line.
206 %(cmdlineargs) All other options passed
208 on the command line.
209 %(diffargs) Options from diff-options
211 or TIG_DIFF_OPTS used by
212 the diff and stage view.
213 %(blameargs) Options from blame-options
215 used by the blame view.
216 %(logargs) Options from log-options
218 used by the log view.
219 %(mainargs) Options from main-options
221 used by the main view.
222 %(prompt) Prompt for the argument
224 value. Optionally specify
225 a custom prompt using
226 "%(prompt Enter branch
227 name: )"
228 %(text) The text of the currently
230 selected line.
231 %(repo:head) The name of the checked
233 out branch, e.g. master
234 %(repo:head-id) The commit ID of the
236 checked out branch.
237 %(repo:remote) The remote associated with
239 the checked out branch,
240 e.g. origin/master.
241 %(repo:cdup) The path to change
243 directory to the
244 repository root, e.g. ../
245 %(repo:prefix) The path prefix of the
247 current work directory,
248 e.g subdir/.
249 %(repo:git-dir) The path to the Git
251 directory, e.g.
252 /src/repo/.git.
253 %(repo:worktree) The worktree path, if
255 defined.
256 %(repo:is-inside-work-tree) Whether Tig is running
258 inside a work tree, either
259 true or false.
260 Example user-defined commands:
263 • Allow to amend the last commit:
265 bind generic + !git commit --amend
267 • Copy commit ID to clipboard:
269 bind generic 9 @sh -c "echo -n %(commit) | xclip -selection c"
271 • Add/edit notes for the current commit used during a review:
273 bind generic T !git notes edit %(commit)
275 • Enter Git’s interactive add for fine-grained staging of file
277 content:
278 bind generic I !git add -i %(file)
280 • Rebase current branch on top of the selected branch:
282 bind refs 3 !git rebase -i %(branch)
284 Title Windows
286 Each view has a title window which shows the name of the view, current
287 commit ID if available, and where the view is positioned:
288 [main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
290 By default, the title of the current view is highlighted using bold
293 font. For long loading views (taking over 3 seconds) the time since
294 loading started will be appended:
295 [main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
297
300 Several options related to the interface with Git can be configured via
301 environment options.
302 Configuration Files
304 Upon startup, Tig first reads the system wide configuration file
305 ({sysconfdir}/tigrc by default) and then proceeds to read the user’s
306 configuration file (~/.tigrc or $XDG_CONFIG_HOME/tig/config by
307 default). The paths to either of these files can be overridden through
308 the following environment variables:
309 TIGRC_USER
311 Path of the user configuration file.
312 TIGRC_SYSTEM
314 Path of the system wide configuration file.
315 History Files
317 If compiled with readline support, Tig writes a persistent command and
318 search history to ~/.tig_history or $XDG_DATA_HOME/tig/history.
319 Repository References
321 Commits that are referenced by tags and branch heads will be marked by
322 the reference name surrounded by [ and ]:
323 2006-03-26 19:42 Petr Baudis | [cogito-0.17.1] Cogito 0.17.1
325 If you want to limit what branches are shown, say only show branches
328 named master or those which start with the feature/ prefix, you can do
329 it by setting the following variable:
330 $ TIG_LS_REMOTE="git ls-remote . master feature/*" tig
332 Or set the variable permanently in your environment.
335 TIG_LS_REMOTE
337 Command for retrieving all repository references. The command
338 should output data in the same format as git-ls-remote(1). Defaults
339 to:
340 git ls-remote .
342 Diff options
345 It is possible to alter how diffs are shown by the diff view. If for
346 example you prefer to have commit and author dates shown as relative
347 dates, use:
348 $ TIG_DIFF_OPTS="--relative-date" tig
350 Or set the variable permanently in your environment.
353
355 Below the default key bindings are shown.
356 View Switching
358 Key Action
359 m Switch to main view.
361 d Switch to diff view.
363 l Switch to log view.
365 p Switch to pager view.
367 t Switch to (directory) tree
369 view.
370 f Switch to (file) blob
372 view.
373 g Switch to grep view.
375 b Switch to blame view.
377 r Switch to refs view.
379 y Switch to stash view.
381 h Switch to help view
383 s Switch to status view
385 c Switch to stage view
387 View Manipulation
390 Key Action
391 q Close view, if multiple
399 views are open it will
400 jump back to the previous
401 view in the view stack. If
402 it is the last open view
403 it will quit. Use Q to
404 quit all views at once.
405 Enter This key is "context
407 sensitive" depending on
408 what view you are
409 currently in. When in log
410 view on a commit line or
411 in the main view, split
412 the view and show the
413 commit diff. In the diff
414 view pressing Enter will
415 simply scroll the view one
416 line down.
417 Tab Switch to next view.
419 R Reload and refresh the
421 current view.
422 O Maximize the current view
424 to fill the whole display.
425 Up This key is "context
427 sensitive" and will move
428 the cursor one line up.
429 However, if you opened a
430 split view it will change
431 the cursor to point to the
432 previous commit in the
433 parent view and update the
434 child view to display it.
435 If you prefer this key to
436 move the cursor or scroll
437 within the diff view
438 instead, use bind diff
439 <Up> move-up or bind diff
440 <Up> scroll-line-up,
441 respectively.
442 Down Similar to Up but will
444 move down.
445 , Move to parent. In the
447 tree view, this means
448 switch to the parent
449 directory. In the blame
450 view it will load blame
451 for the parent commit. For
452 merges the parent is
453 queried.
454 View Specific Actions
457 Key Action
458 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, - Move cursor one page up.
514 PgDown, Space Move cursor one page down.
516 Home Jump to first line.
518 End Jump to last 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.4 06/05/2021 TIGMANUAL(7)