1TIGMANUAL(7)                      Tig Manual                      TIGMANUAL(7)
2
3
4

NAME

6       tigmanual - text-mode interface for Git
7

SYNOPSIS

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

DESCRIPTION

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

CALLING CONVENTIONS

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

THE VIEWER

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       %(stash)                      The currently selected
170                                     stash name.
171
172       %(directory)                  The current directory path
173                                     in the tree view or "." if
174                                     undefined.
175
176       %(file)                       The currently selected
177                                     file.
178
179       %(lineno)                     The currently selected
180                                     line number. Defaults to
181                                     0.
182
183       %(ref)                        The reference given to
184                                     blame or HEAD if
185                                     undefined.
186
187       %(revargs)                    The revision arguments
188                                     passed on the command
189                                     line.
190
191       %(fileargs)                   The file arguments passed
192                                     on the command line.
193
194       %(cmdlineargs)                All other options passed
195                                     on the command line.
196
197
198
199
200       %(diffargs)                   Options from diff-options
201                                     or TIG_DIFF_OPTS used by
202                                     the diff and stage view.
203
204       %(blameargs)                  Options from blame-options
205                                     used by the blame view.
206
207       %(logargs)                    Options from log-options
208                                     used by the log view.
209
210       %(mainargs)                   Options from main-options
211                                     used by the main view.
212
213       %(prompt)                     Prompt for the argument
214                                     value. Optionally specify
215                                     a custom prompt using
216                                     "%(prompt Enter branch
217                                     name: )"
218
219       %(text)                       The text of the currently
220                                     selected line.
221
222       %(repo:head)                  The name of the checked
223                                     out branch, e.g. master
224
225       %(repo:head-id)               The commit ID of the
226                                     checked out branch.
227
228       %(repo:remote)                The remote associated with
229                                     the checked out branch,
230                                     e.g. origin/master.
231
232       %(repo:cdup)                  The path to change
233                                     directory to the
234                                     repository root, e.g. ../
235
236       %(repo:prefix)                The path prefix of the
237                                     current work directory,
238                                     e.g subdir/.
239
240       %(repo:git-dir)               The path to the Git
241                                     directory, e.g.
242                                     /src/repo/.git.
243
244       %(repo:worktree)              The worktree path, if
245                                     defined.
246
247       %(repo:is-inside-work-tree)   Whether Tig is running
248                                     inside a work tree, either
249                                     true or false.
250
251
252       Example user-defined commands:
253
254       ·   Allow to amend the last commit:
255
256               bind generic + !git commit --amend
257
258       ·   Copy commit ID to clipboard:
259
260               bind generic 9 !@sh -c "echo -n %(commit) | xclip -selection c"
261
262       ·   Add/edit notes for the current commit used during a review:
263
264               bind generic T !git notes edit %(commit)
265
266       ·   Enter Git’s interactive add for fine-grained staging of file
267           content:
268
269               bind generic I !git add -i %(file)
270
271       ·   Rebase current branch on top of the selected branch:
272
273               bind refs 3 !git rebase -i %(branch)
274
275   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
279           [main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
280
281
282       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
286           [main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
287
288

ENVIRONMENT VARIABLES

290       Several options related to the interface with Git can be configured via
291       environment options.
292
293   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
300       TIGRC_USER
301           Path of the user configuration file.
302
303       TIGRC_SYSTEM
304           Path of the system wide configuration file.
305
306   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
310   Repository References
311       Commits that are referenced by tags and branch heads will be marked by
312       the reference name surrounded by [ and ]:
313
314           2006-03-26 19:42 Petr Baudis         | [cogito-0.17.1] Cogito 0.17.1
315
316
317       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
321           $ TIG_LS_REMOTE="git ls-remote . master feature/*" tig
322
323
324       Or set the variable permanently in your environment.
325
326       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
331           git ls-remote .
332
333
334   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
339           $ TIG_DIFF_OPTS="--relative-date" tig
340
341
342       Or set the variable permanently in your environment.
343

DEFAULT KEYBINDINGS

345       Below the default key bindings are shown.
346
347   View Switching
348       Key   Action
349
350       m     Switch to main view.
351
352       d     Switch to diff view.
353
354       l     Switch to log view.
355
356       p     Switch to pager view.
357
358       t     Switch to (directory) tree
359             view.
360
361       f     Switch to (file) blob
362             view.
363
364       g     Switch to grep view.
365
366       b     Switch to blame view.
367
368       r     Switch to refs view.
369
370       y     Switch to stash view.
371
372       h     Switch to help view
373
374       s     Switch to status view
375
376       c     Switch to stage view
377
378
379   View Manipulation
380       Key     Action
381
382       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
390
391
392
393
394
395
396
397
398       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
410       Tab     Switch to next view.
411
412       R       Reload and refresh the
413               current view.
414
415       O       Maximize the current view
416               to fill the whole display.
417
418       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
435       Down    Similar to Up but will
436               move down.
437
438       ,       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
447
448   View Specific Actions
449       Key   Action
450
451
452
453
454
455
456
457
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,-,a        Move cursor one page up.
514
515       PgDown, Space   Move cursor one page down.
516
517       End             Jump to last line.
518
519       Home            Jump to first 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 highlighting of commit title
609               overflow.
610
611       H       Go to the HEAD commit.
612
613       :       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
617       e       Open file in editor.
618
619
620   Prompt
621       Key                      Action
622
623       :<number>                Jump to the specific line
624                                number, e.g. :80.
625
626       :<sha>                   Jump to a specific commit,
627                                e.g. :2f12bcc.
628
629       :<x>                     Execute the corresponding
630                                key binding, e.g. :q.
631
632       :!<command>              Execute a system command
633                                in a pager, e.g. :!git log
634                                -p.
635
636       :<action>                Execute a Tig command,
637                                e.g. :edit.
638
639       :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
648       :save-display <file>     Save current display to
649                                <file>.
650
651       :save-options <file>     Save current options to
652                                <file>.
653
654       :save-view <file>        Save view info to <file>
655                                (for testing purposes).
656
657       :script <file>           Execute commands from
658                                <file>.
659
660
661
662       :exec <flags><args...>   Execute command using
663                                <args> with external
664                                user-defined command
665                                option flags defined in
666                                <flags>.
667
668       :echo <args...>          Display text in the status
669                                bar.
670
671
672   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
678       Keymap    Key   Action
679
680       main      C     git cherry-pick
681                       %(commit)
682
683       status    C     git commit
684
685       generic   G     git gc
686
687

REVISION SPECIFICATION

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
695       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
699   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
703           $ tig Makefile README
704
705
706       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
711           $ tig -- status
712
713
714   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
719       If you are only interested in changes that happened between two dates
720       you can use:
721
722           $ tig --after="May 5th" --before="2006-05-16 15:44"
723
724
725           Note
726           If you want to avoid having to quote dates containing spaces you
727           can use "." instead, e.g. --after=May.5th.
728
729   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
733           $ tig tag-1.0..tag-2.0
734
735
736       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
740           $ tig origin..HEAD
741
742
743       will list what will be pushed to the remote branch. Optionally, the
744       ending HEAD can be left out since it is implied.
745
746   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
752       If you prefer to specify which commit to preview in this way use the
753       following:
754
755           $ tig tag-2.0 ^tag-1.0
756
757
758       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
762   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
767           $ tig --since=1.month -n20 -- Documentation/
768
769
770   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
776           $ tig --all --since=1.week -- Makefile
777
778

MORE INFORMATION

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
787       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

SEE ALSO

793       Manpages:
794
795       ·   tig(1)
796
797       ·   tigrc(5)
798

NOTES

800        1. home page
801           https://jonas.github.io/tig
802
803        2. main Git repository
804           https://github.com/jonas/tig
805
806        3. jonas.fonseca@gmail.com
807           mailto:jonas.fonseca@gmail.com
808
809
810
811Tig 2.5.1                         04/08/2020                      TIGMANUAL(7)
Impressum