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 %(file_old) The old filename of the
185 currently selected file.
186 %(lineno) The currently selected
188 line number. Defaults to
189 0.
190 %(lineno_old) The currently selected
192 line number, before the
193 diff was applied. Defaults
194 to 0.
195 %(ref) The reference given to
201 blame or HEAD if
202 undefined.
203 %(revargs) The revision arguments
205 passed on the command
206 line.
207 %(fileargs) The file arguments passed
209 on the command line.
210 %(cmdlineargs) All other options passed
212 on the command line.
213 %(diffargs) Options from diff-options
215 or TIG_DIFF_OPTS used by
216 the diff and stage view.
217 %(blameargs) Options from blame-options
219 used by the blame view.
220 %(logargs) Options from log-options
222 used by the log view.
223 %(mainargs) Options from main-options
225 used by the main view.
226 %(prompt) Prompt for the argument
228 value. Optionally specify
229 a custom prompt using
230 "%(prompt Enter branch
231 name: )"
232 %(text) The text of the currently
234 selected line.
235 %(repo:head) The name of the checked
237 out branch, e.g. master
238 %(repo:head-id) The commit ID of the
240 checked out branch.
241 %(repo:remote) The remote associated with
243 the checked out branch,
244 e.g. origin/master.
245 %(repo:cdup) The path to change
247 directory to the
248 repository root, e.g. ../
249 %(repo:prefix) The path prefix of the
251 current work directory,
252 e.g subdir/.
253 %(repo:git-dir) The path to the Git
255 directory, e.g.
256 /src/repo/.git.
257 %(repo:worktree) The worktree path, if
259 defined.
260 %(repo:is-inside-work-tree) Whether Tig is running
262 inside a work tree, either
263 true or false.
264 Example user-defined commands:
267 • Allow to amend the last commit:
269 bind generic + !git commit --amend
271 • Copy commit ID to clipboard:
273 bind generic 9 @sh -c "echo -n %(commit) | xclip -selection c"
275 • Add/edit notes for the current commit used during a review:
277 bind generic T !git notes edit %(commit)
279 • Enter Git’s interactive add for fine-grained staging of file
281 content:
282 bind generic I !git add -i %(file)
284 • Rebase current branch on top of the selected branch:
286 bind refs 3 !git rebase -i %(branch)
288 Title Windows
290 Each view has a title window which shows the name of the view, current
291 commit ID if available, and where the view is positioned:
292 [main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
294 By default, the title of the current view is highlighted using bold
297 font. For long loading views (taking over 3 seconds) the time since
298 loading started will be appended:
299 [main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
301
304 Several options related to the interface with Git can be configured via
305 environment options.
306 Configuration Files
308 Upon startup, Tig first reads the system wide configuration file
309 ({sysconfdir}/tigrc by default) and then proceeds to read the user’s
310 configuration file (~/.tigrc or $XDG_CONFIG_HOME/tig/config by
311 default). The paths to either of these files can be overridden through
312 the following environment variables:
313 TIGRC_USER
315 Path of the user configuration file.
316 TIGRC_SYSTEM
318 Path of the system wide configuration file.
319 History Files
321 If compiled with readline support, Tig writes a persistent command and
322 search history to ~/.tig_history or $XDG_DATA_HOME/tig/history.
323 Repository References
325 Commits that are referenced by tags and branch heads will be marked by
326 the reference name surrounded by [ and ]:
327 2006-03-26 19:42 Petr Baudis | [cogito-0.17.1] Cogito 0.17.1
329 If you want to limit what branches are shown, say only show branches
332 named master or those which start with the feature/ prefix, you can do
333 it by setting the following variable:
334 $ TIG_LS_REMOTE="git ls-remote . master feature/*" tig
336 Or set the variable permanently in your environment.
339 TIG_LS_REMOTE
341 Command for retrieving all repository references. The command
342 should output data in the same format as git-ls-remote(1). Defaults
343 to:
344 git ls-remote .
346 Diff options
349 It is possible to alter how diffs are shown by the diff view. If for
350 example you prefer to have commit and author dates shown as relative
351 dates, use:
352 $ TIG_DIFF_OPTS="--relative-date" tig
354 Or set the variable permanently in your environment.
357
359 Below the default key bindings are shown.
360 View Switching
362 Key Action
363 m Switch to main view.
365 d Switch to diff view.
367 l Switch to log view.
369 p Switch to pager view.
371 t Switch to (directory) tree
373 view.
374 f Switch to (file) blob
376 view.
377 g Switch to grep view.
379 b Switch to blame view.
381 r Switch to refs view.
383 y Switch to stash view.
385 h Switch to help view
387 s Switch to status view
389 c Switch to stage view
391 View Manipulation
394 Key Action
395 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 revision filtering in the main
609 view.
610 $ Toggle highlighting of commit title
612 overflow.
613 H Go to the HEAD commit.
615 : Open prompt. This allows you to specify
617 what command to run and also to jump to
618 a specific line, e.g. :23
619 e Open file in editor.
621 Prompt
624 Key Action
625 :<number> Jump to the specific line
627 number, e.g. :80.
628 :<sha> Jump to a specific commit,
630 e.g. :2f12bcc.
631 :<x> Execute the corresponding
633 key binding, e.g. :q.
634 :!<command> Execute a system command
636 in a pager, e.g. :!git log
637 -p.
638 :<action> Execute a Tig command,
640 e.g. :edit.
641 :goto <rev> Jump to a specific
643 revision, e.g. :goto
644 %(commit)^2 to goto the
645 current commit’s 2nd
646 parent or :goto
647 some/branch to goto the
648 commit denoting the branch
649 some/branch.
650 :save-display <file> Save current display to
652 <file>.
653 :save-options <file> Save current options to
655 <file>.
656 :save-view <file> Save view info to <file>
658 (for testing purposes).
659 :script <file> Execute commands from
663 <file>.
664 :exec <flags><args...> Execute command using
666 <args> with external
667 user-defined command
668 option flags defined in
669 <flags>.
670 :echo <args...> Display text in the status
672 bar.
673 External Commands
676 For more custom needs, external commands provide a way to easily
677 execute a script or program. They are bound to keys and use information
678 from the current browsing state, such as the current commit ID. Tig
679 comes with the following built-in external commands:
680 Keymap Key Action
682 main C git cherry-pick
684 %(commit)
685 status C git commit
687 generic G git gc
689
692 This section describes various ways to specify what revisions to
693 display or otherwise limit the view to. Tig does not itself parse the
694 described revision options so refer to the relevant Git man pages for
695 further information. Relevant man pages besides git-log(1) are
696 git-diff(1) and git-rev-list(1).
697 You can tune the interaction with Git by making use of the options
699 explained in this section. For example, by configuring the environment
700 variable described in the section on diff options.
701 Limit by Path Name
703 If you are interested only in those revisions that made changes to a
704 specific file (or even several files) list the files like this:
705 $ tig Makefile README
707 To avoid ambiguity with Tig’s subcommands or repository references such
710 as tag names, be sure to separate file names from other Git options
711 using "--". So if you have a file named status it will clash with the
712 status subcommand, and thus you will have to use:
713 $ tig -- status
715 Limit by Date or Number
718 To speed up interaction with Git, you can limit the amount of commits
719 to show both for the log and main view. Either limit by date using e.g.
720 --since=1.month or limit by the number of commits using -n400.
721 If you are only interested in changes that happened between two dates
723 you can use:
724 $ tig --after="May 5th" --before="2006-05-16 15:44"
726 Note
729 If you want to avoid having to quote dates containing spaces you
730 can use "." instead, e.g. --after=May.5th.
731 Limiting by Commit Ranges
733 Alternatively, commits can be limited to a specific range, such as "all
734 commits between tag-1.0 and tag-2.0". For example:
735 $ tig tag-1.0..tag-2.0
737 This way of commit limiting makes it trivial to only browse the commits
740 which haven’t been pushed to a remote branch. Assuming origin is your
741 upstream remote branch, using:
742 $ tig origin..HEAD
744 will list what will be pushed to the remote branch. Optionally, the
747 ending HEAD can be left out since it is implied.
748 Limiting by Reachability
750 Git interprets the range specifier "tag-1.0..tag-2.0" as "all commits
751 reachable from tag-2.0 but not from tag-1.0". Where reachability refers
752 to what commits are ancestors (or part of the history) of the branch or
753 tagged revision in question.
754 If you prefer to specify which commit to preview in this way use the
756 following:
757 $ tig tag-2.0 ^tag-1.0
759 You can think of ^ as a negation operator. Using this alternate syntax,
762 it is possible to further prune commits by specifying multiple branch
763 cut offs.
764 Combining Revisions Specification
766 Revision options can to some degree be combined, which makes it
767 possible to say "show at most 20 commits from within the last month
768 that changed files under the Documentation/ directory."
769 $ tig --since=1.month -n20 -- Documentation/
771 Examining All Repository References
774 In some cases, it can be useful to query changes across all references
775 in a repository. An example is to ask "did any line of development in
776 this repository change a particular file within the last week". This
777 can be accomplished using:
778 $ tig --all --since=1.week -- Makefile
780
783 Please visit Tig’s home page[1] or main Git repository[2] for
784 information about new releases and how to report bugs and feature
785 requests.
786
788 Copyright (c) 2006-2022 Jonas Fonseca <jonas.fonseca@gmail.com[3]>
789 This program is free software; you can redistribute it and/or modify it
791 under the terms of the GNU General Public License as published by the
792 Free Software Foundation; either version 2 of the License, or (at your
793 option) any later version.
794
796 Manpages:
797 • tig(1)
799 • tigrc(5)
801
803 1. home page
804 https://jonas.github.io/tig
805 2. main Git repository
807 https://github.com/jonas/tig
808 3. jonas.fonseca@gmail.com
810 mailto:jonas.fonseca@gmail.com
811Tig 2.5.7 08/25/2022 TIGMANUAL(7)