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 column of the
234 currently 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 The format for patterns is either POSIX.2 “extended” REs or PCRE /
563 PCRE2 if Tig was compiled with PCRE / PCRE2 support (check with tig
564 -v). See the manpage of re_format(7) or pcrepattern(3) /
565 pcre2pattern(3).
566 Case sensitivity can be controlled with variable ignore-case.
568 Misc
570 Key Action
571 Q Quit.
573 <C-L> Redraw screen.
575 z Stop all background
577 loading. This can be
578 useful if you use Tig in a
579 repository with a long
580 history without limiting
581 the revision log.
582 v Show version.
584 o Open option menu
586 # Toggle line numbers
588 on/off.
589 D Toggle date display
591 on/off/relative/relative-compact/custom
592 A Toggle author display
597 on/off/abbreviated/email/email user
598 name.
599 G Toggle revision graph visualization
601 on/off.
602 ~ Toggle (line) graphics mode
604 F Toggle reference display on/off (tag
606 and branch names).
607 W Toggle ignoring whitespace on/off for
609 diffs
610 X Toggle commit ID display on/off
612 % Toggle file filtering in order to see
614 the full diff instead of only the diff
615 concerning the currently selected file.
616 ^ Toggle revision filtering in the main
618 view.
619 $ Toggle highlighting of commit title
621 overflow.
622 H Go to the HEAD commit.
624 : Open prompt. This allows you to specify
626 what command to run and also to jump to
627 a specific line, e.g. :23
628 e Open file in editor.
630 Prompt
633 Key Action
634 :<number> Jump to the specific line
636 number, e.g. :80.
637 :<sha> Jump to a specific commit,
639 e.g. :2f12bcc.
640 :<x> Execute the corresponding
642 key binding, e.g. :q.
643 :!<command> Execute a system command
645 in a pager, e.g. :!git log
646 -p.
647 :<action> Execute a Tig command,
649 e.g. :edit.
650 :goto <rev> Jump to a specific
652 revision, e.g. :goto
653 %(commit)^2 to goto the
654 current commit’s 2nd
655 parent or :goto
656 some/branch to goto the
657 commit denoting the branch
658 some/branch.
659 :save-display <file> Save current display to
663 <file>.
664 :save-options <file> Save current options to
666 <file>.
667 :save-view <file> Save view info to <file>
669 (for testing purposes).
670 :script <file> Execute commands from
672 <file>.
673 :exec <flags><args...> Execute command using
675 <args> with external
676 user-defined command
677 option flags defined in
678 <flags>.
679 :echo <args...> Display text in the status
681 bar.
682 External Commands
685 For more custom needs, external commands provide a way to easily
686 execute a script or program. They are bound to keys and use information
687 from the current browsing state, such as the current commit ID. Tig
688 comes with the following built-in external commands:
689 Keymap Key Action
691 main C git cherry-pick
693 %(commit)
694 status C git commit
696 generic G git gc
698
701 This section describes various ways to specify what revisions to
702 display or otherwise limit the view to. Tig does not itself parse the
703 described revision options so refer to the relevant Git man pages for
704 further information. Relevant man pages besides git-log(1) are
705 git-diff(1) and git-rev-list(1).
706 You can tune the interaction with Git by making use of the options
708 explained in this section. For example, by configuring the environment
709 variable described in the section on diff options.
710 Limit by Path Name
712 If you are interested only in those revisions that made changes to a
713 specific file (or even several files) list the files like this:
714 $ tig Makefile README
716 To avoid ambiguity with Tig’s subcommands or repository references such
719 as tag names, be sure to separate file names from other Git options
720 using "--". So if you have a file named status it will clash with the
721 status subcommand, and thus you will have to use:
722 $ tig -- status
724 Limit by Date or Number
727 To speed up interaction with Git, you can limit the amount of commits
728 to show both for the log and main view. Either limit by date using e.g.
729 --since=1.month or limit by the number of commits using -n400.
730 If you are only interested in changes that happened between two dates
732 you can use:
733 $ tig --after="May 5th" --before="2006-05-16 15:44"
735 Note
738 If you want to avoid having to quote dates containing spaces you
739 can use "." instead, e.g. --after=May.5th.
740 Limiting by Commit Ranges
742 Alternatively, commits can be limited to a specific range, such as "all
743 commits between tag-1.0 and tag-2.0". For example:
744 $ tig tag-1.0..tag-2.0
746 This way of commit limiting makes it trivial to only browse the commits
749 which haven’t been pushed to a remote branch. Assuming origin is your
750 upstream remote branch, using:
751 $ tig origin..HEAD
753 will list what will be pushed to the remote branch. Optionally, the
756 ending HEAD can be left out since it is implied.
757 Limiting by Reachability
759 Git interprets the range specifier "tag-1.0..tag-2.0" as "all commits
760 reachable from tag-2.0 but not from tag-1.0". Where reachability refers
761 to what commits are ancestors (or part of the history) of the branch or
762 tagged revision in question.
763 If you prefer to specify which commit to preview in this way use the
765 following:
766 $ tig tag-2.0 ^tag-1.0
768 You can think of ^ as a negation operator. Using this alternate syntax,
771 it is possible to further prune commits by specifying multiple branch
772 cut offs.
773 Combining Revisions Specification
775 Revision options can to some degree be combined, which makes it
776 possible to say "show at most 20 commits from within the last month
777 that changed files under the Documentation/ directory."
778 $ tig --since=1.month -n20 -- Documentation/
780 Examining All Repository References
783 In some cases, it can be useful to query changes across all references
784 in a repository. An example is to ask "did any line of development in
785 this repository change a particular file within the last week". This
786 can be accomplished using:
787 $ tig --all --since=1.week -- Makefile
789
792 Please visit Tig’s home page[1] or main Git repository[2] for
793 information about new releases and how to report bugs and feature
794 requests.
795
797 Copyright (c) 2006-2022 Jonas Fonseca <jonas.fonseca@gmail.com[3]>
798 This program is free software; you can redistribute it and/or modify it
800 under the terms of the GNU General Public License as published by the
801 Free Software Foundation; either version 2 of the License, or (at your
802 option) any later version.
803
805 Manpages:
806 • tig(1)
808 • tigrc(5)
810
812 1. home page
813 https://jonas.github.io/tig
814 2. main Git repository
816 https://github.com/jonas/tig
817 3. jonas.fonseca@gmail.com
819 mailto:jonas.fonseca@gmail.com
820Tig 2.5.8 02/04/2023 TIGMANUAL(7)