1TIGMANUAL(7) Tig Manual TIGMANUAL(7)
2
3
4
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
15
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
22 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
32 Example on how to colorize the output of git-show(1):
33
34 $ git show | tig
35
36
37 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
42 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
47 Example on how to view a commit and show both author and committer
48 information:
49
50 $ tig show --pretty=fuller
51
52
53 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
63 If you are in the log view and press Enter when the current line is a
64 commit line, such as:
65
66 commit 4d55caff4cc89335192f3e566004b4ceef572521
67
68
69 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
74 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
79 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
85 The log view
86 Presents a more rich view of the revision log showing the whole log
87 message and the diffstat.
88
89 The reflog view
90 Presents a view of the reflog allowing to navigate the repo
91 history.
92
93 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
98 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
103 The blob view
104 Displays the file content or "blob" of data associated with a file
105 name.
106
107 The blame view
108 Displays the file content annotated or blamed by commits.
109
110 The refs view
111 Displays the branches, remotes and tags in the repository.
112
113 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
117 The stage view
118 Displays diff changes for staged or unstaged files being tracked or
119 file content of untracked files.
120
121 The stash view
122 Displays the list of stashes in the repository.
123
124 The grep view
125 Displays a list of files and all the lines that matches a search
126 pattern.
127
128 The pager view
129 Is used for displaying both input from stdin and output from Git
130 commands entered in the internal prompt.
131
132 The help view
133 Displays a quick reference of key bindings.
134
135 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
143 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
148 Table 1. Browsing state variables
149 %(head) The currently viewed head
150 ID. Defaults to HEAD
151
152 %(commit) The currently selected
153 commit ID.
154
155 %(blob) The currently selected
156 blob ID.
157
158 %(branch) The currently selected
159 branch name.
160
161 %(remote) The currently selected
162 remote name. For remote
163 branches %(branch) will
164 contain the branch name.
165
166 %(tag) The currently selected tag
167 name.
168
169 %(refname) The currently selected
170 reference name including
171 the remote name for remote
172 branches.
173
174 %(stash) The currently selected
175 stash name.
176
177 %(directory) The current directory path
178 in the tree view or "." if
179 undefined.
180
181 %(file) The currently selected
182 file.
183
184 %(file_old) The old filename of the
185 currently selected file.
186
187 %(lineno) The currently selected
188 line number. Defaults to
189 0.
190
191 %(lineno_old) The currently selected
192 line number, before the
193 diff was applied. Defaults
194 to 0.
195
196
197
198
199
200 %(ref) The reference given to
201 blame or HEAD if
202 undefined.
203
204 %(revargs) The revision arguments
205 passed on the command
206 line.
207
208 %(fileargs) The file arguments passed
209 on the command line.
210
211 %(cmdlineargs) All other options passed
212 on the command line.
213
214 %(diffargs) Options from diff-options
215 or TIG_DIFF_OPTS used by
216 the diff and stage view.
217
218 %(blameargs) Options from blame-options
219 used by the blame view.
220
221 %(logargs) Options from log-options
222 used by the log view.
223
224 %(mainargs) Options from main-options
225 used by the main view.
226
227 %(prompt) Prompt for the argument
228 value. Optionally specify
229 a custom prompt using
230 "%(prompt Enter branch
231 name: )"
232
233 %(text) The text of the currently
234 selected line.
235
236 %(repo:head) The name of the checked
237 out branch, e.g. master
238
239 %(repo:head-id) The commit ID of the
240 checked out branch.
241
242 %(repo:remote) The remote associated with
243 the checked out branch,
244 e.g. origin/master.
245
246 %(repo:cdup) The path to change
247 directory to the
248 repository root, e.g. ../
249
250 %(repo:prefix) The path prefix of the
251 current work directory,
252 e.g subdir/.
253
254 %(repo:git-dir) The path to the Git
255 directory, e.g.
256 /src/repo/.git.
257
258 %(repo:worktree) The worktree path, if
259 defined.
260
261 %(repo:is-inside-work-tree) Whether Tig is running
262 inside a work tree, either
263 true or false.
264
265
266 Example user-defined commands:
267
268 • Allow to amend the last commit:
269
270 bind generic + !git commit --amend
271
272 • Copy commit ID to clipboard:
273
274 bind generic 9 @sh -c "echo -n %(commit) | xclip -selection c"
275
276 • Add/edit notes for the current commit used during a review:
277
278 bind generic T !git notes edit %(commit)
279
280 • Enter Git’s interactive add for fine-grained staging of file
281 content:
282
283 bind generic I !git add -i %(file)
284
285 • Rebase current branch on top of the selected branch:
286
287 bind refs 3 !git rebase -i %(branch)
288
289 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
293 [main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
294
295
296 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
300 [main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
301
302
304 Several options related to the interface with Git can be configured via
305 environment options.
306
307 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
314 TIGRC_USER
315 Path of the user configuration file.
316
317 TIGRC_SYSTEM
318 Path of the system wide configuration file.
319
320 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
324 Repository References
325 Commits that are referenced by tags and branch heads will be marked by
326 the reference name surrounded by [ and ]:
327
328 2006-03-26 19:42 Petr Baudis | [cogito-0.17.1] Cogito 0.17.1
329
330
331 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
335 $ TIG_LS_REMOTE="git ls-remote . master feature/*" tig
336
337
338 Or set the variable permanently in your environment.
339
340 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
345 git ls-remote .
346
347
348 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
353 $ TIG_DIFF_OPTS="--relative-date" tig
354
355
356 Or set the variable permanently in your environment.
357
359 Below the default key bindings are shown.
360
361 View Switching
362 Key Action
363
364 m Switch to main view.
365
366 d Switch to diff view.
367
368 l Switch to log view.
369
370 p Switch to pager view.
371
372 t Switch to (directory) tree
373 view.
374
375 f Switch to (file) blob
376 view.
377
378 g Switch to grep view.
379
380 b Switch to blame view.
381
382 r Switch to refs view.
383
384 y Switch to stash view.
385
386 h Switch to help view
387
388 s Switch to status view
389
390 c Switch to stage view
391
392
393 View Manipulation
394 Key Action
395
396
397
398 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
406 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
418 Tab Switch to next view.
419
420 R Reload and refresh the
421 current view.
422
423 O Maximize the current view
424 to fill the whole display.
425
426 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
443 Down Similar to Up but will
444 move down.
445
446 , 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
455
456 View Specific Actions
457 Key Action
458
459
460
461
462
463
464 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
480 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
490 ! Checkout file with
491 unstaged changes. This
492 will reset the file to
493 contain the content it had
494 at last commit.
495
496 1 Stage single diff line.
497
498 @ Move to next chunk in the
499 stage view.
500
501 ] Increase the diff context.
502
503 [ Decrease the diff context.
504
505
506 Cursor Navigation
507 Key Action
508
509 k Move cursor one line up.
510
511 j Move cursor one line down.
512
513 PgUp, - Move cursor one page up.
514
515 PgDown, Space Move cursor one page down.
516
517 Home Jump to first line.
518
519 End Jump to last line.
520
521
522 Scrolling
523 Key Action
524
525 Insert Scroll view one line up.
526
527 Delete Scroll view one line down.
528
529
530 ScrollBack Scroll view one page up.
531
532 ScrollFwd Scroll view one page down.
533
534 Left Scroll view one column
535 left.
536
537 Right Scroll view one column
538 right.
539
540 | Scroll view to the first
541 column.
542
543
544 Searching
545 Key Action
546
547 / Search the view. Opens a
548 prompt for entering search
549 regexp to use.
550
551 ? Search backwards in the
552 view. Also prompts for
553 regexp.
554
555 n Find next match for the
556 current search regexp.
557
558 N Find previous match for
559 the current search regexp.
560
561
562 Misc
563 Key Action
564
565 Q Quit.
566
567 <C-L> Redraw screen.
568
569 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
576 v Show version.
577
578 o Open option menu
579
580 # Toggle line numbers
581 on/off.
582
583 D Toggle date display
584 on/off/relative/relative-compact/custom
585
586 A Toggle author display
587 on/off/abbreviated/email/email user
588 name.
589
590 G Toggle revision graph visualization
591 on/off.
592
593 ~ Toggle (line) graphics mode
594
595
596 F Toggle reference display on/off (tag
597 and branch names).
598
599 W Toggle ignoring whitespace on/off for
600 diffs
601
602 X Toggle commit ID display on/off
603
604 % Toggle file filtering in order to see
605 the full diff instead of only the diff
606 concerning the currently selected file.
607
608 ^ Toggle revision filtering in the main
609 view.
610
611 $ Toggle highlighting of commit title
612 overflow.
613
614 H Go to the HEAD commit.
615
616 : 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
620 e Open file in editor.
621
622
623 Prompt
624 Key Action
625
626 :<number> Jump to the specific line
627 number, e.g. :80.
628
629 :<sha> Jump to a specific commit,
630 e.g. :2f12bcc.
631
632 :<x> Execute the corresponding
633 key binding, e.g. :q.
634
635 :!<command> Execute a system command
636 in a pager, e.g. :!git log
637 -p.
638
639 :<action> Execute a Tig command,
640 e.g. :edit.
641
642 :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
651 :save-display <file> Save current display to
652 <file>.
653
654 :save-options <file> Save current options to
655 <file>.
656
657 :save-view <file> Save view info to <file>
658 (for testing purposes).
659
660
661
662 :script <file> Execute commands from
663 <file>.
664
665 :exec <flags><args...> Execute command using
666 <args> with external
667 user-defined command
668 option flags defined in
669 <flags>.
670
671 :echo <args...> Display text in the status
672 bar.
673
674
675 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
681 Keymap Key Action
682
683 main C git cherry-pick
684 %(commit)
685
686 status C git commit
687
688 generic G git gc
689
690
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
698 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
702 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
706 $ tig Makefile README
707
708
709 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
714 $ tig -- status
715
716
717 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
722 If you are only interested in changes that happened between two dates
723 you can use:
724
725 $ tig --after="May 5th" --before="2006-05-16 15:44"
726
727
728 Note
729 If you want to avoid having to quote dates containing spaces you
730 can use "." instead, e.g. --after=May.5th.
731
732 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
736 $ tig tag-1.0..tag-2.0
737
738
739 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
743 $ tig origin..HEAD
744
745
746 will list what will be pushed to the remote branch. Optionally, the
747 ending HEAD can be left out since it is implied.
748
749 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
755 If you prefer to specify which commit to preview in this way use the
756 following:
757
758 $ tig tag-2.0 ^tag-1.0
759
760
761 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
765 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
770 $ tig --since=1.month -n20 -- Documentation/
771
772
773 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
779 $ tig --all --since=1.week -- Makefile
780
781
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-2014 Jonas Fonseca <jonas.fonseca@gmail.com[3]>
789
790 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
798 • tig(1)
799
800 • tigrc(5)
801
803 1. home page
804 https://jonas.github.io/tig
805
806 2. main Git repository
807 https://github.com/jonas/tig
808
809 3. jonas.fonseca@gmail.com
810 mailto:jonas.fonseca@gmail.com
811
812
813
814Tig 2.5.5 01/11/2022 TIGMANUAL(7)