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       %(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

ENVIRONMENT VARIABLES

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

DEFAULT KEYBINDINGS

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

REVISION SPECIFICATION

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

MORE INFORMATION

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

SEE ALSO

796       Manpages:
797
798tig(1)
799
800tigrc(5)
801

NOTES

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.7                         08/25/2022                      TIGMANUAL(7)
Impressum