6 tig - text-mode interface for git
12 tig [options] [--] [git log options]
13 tig [options] log [git log options]
14 tig [options] diff [git diff options]
15 tig [options] show [git show options]
16 tig [options] < [git command output]
20 Browse changes in a git repository. Additionally, tig(1) can also act
21 as a pager for output of various git commands.
23 When browsing repositories, tig(1) uses the underlying git commands
24 to present the user with various views, such as summarized commit log
25 and showing the commit with the log message, diffstat, and the diff.
27 Using tig(1) as a pager, it will display input from stdin and try
34 Start up in log view using the internal log command.
37 Start up in diff view using the internal diff command.
39 -n[INTERVAL], --line-number[=INTERVAL]::
40 Prefix line numbers in log and diff view.
41 Optionally, with interval different than each line.
43 -t[NSPACES], --tab-size[=NSPACES]::
44 Set the number of spaces tabs should be expanded to.
47 Show version and exit.
50 End of tig(1) options. Useful when specifying command
51 options for the main view. Example:
53 $ tig -- --since=1.month
55 log [git log options]::
56 Open log view using the given git log options.
58 diff [git diff options]::
59 Open diff view using the given git diff options.
61 show [git show options]::
62 Open diff view using the given git show options.
65 tig(1) will stop the option parsing when the first
66 command line parameter not starting with "-" is
67 encountered. All options including this one will be
68 passed to git log when loading the main view.
69 This makes it possible to say:
75 If stdin is a pipe, any log or diff options will be ignored and the
76 pager view will be opened loading data from stdin. The pager mode
77 can be used for colorizing output from various git commands.
79 Example on how to colorize the output of git-show(1):
85 All git command options specified on the command line will
86 be passed to the given command and all will be shell quoted
87 before they are passed to the shell.
89 NOTE: If you specify options for the main view, you should
90 not use the `--pretty` option as this option will be set
91 automatically to the format expected by the main view.
93 Example on how to open the log view and show both author and
94 committer information:
96 $ tig log --pretty=fuller
98 See the <<refspec, "Specifying revisions">> section below
99 for an introduction to revision options supported by the git
100 commands. For details on specific git command options, refer
101 to the man page of the command in question.
103 ENVIRONMENT VARIABLES
104 ---------------------
105 Several options related to the interface with git can be configured
106 via environment options.
108 Repository references
109 ~~~~~~~~~~~~~~~~~~~~~
110 Commits that are referenced by tags and branch heads will be marked
111 by the reference name surrounded by '[' and ']':
113 2006-03-26 19:42 Petr Baudis | [cogito-0.17.1] Cogito 0.17.1
115 If you want to filter out certain directories under `.git/refs/`, say
116 `tmp` you can do it by setting the following variable:
118 $ TIG_LS_REMOTE="git ls-remote . | sed /\/tmp\//d" tig
120 Or set the variable permanently in your environment.
123 Set command for retrieving all repository references. The command
124 should output data in the same format as git-ls-remote(1).
129 It is possible to alter which commands are used for the different views.
130 If for example you prefer commits in the main view to be sorted by date
131 and only show 500 commits, use:
133 $ TIG_MAIN_CMD="git log --date-order -n500 --pretty=raw %s" tig
135 Or set the variable permanently in your environment.
137 Notice, how `%s` is used to specify the commit reference. There can
138 be a maximum of 5 `%s` ref specifications.
141 The command used for the diff view. By default, git show is used
145 The command used for the log view. If you prefer to have both
146 author and committer shown in the log view be sure to pass
147 `--pretty=fuller` to git log.
150 The command used for the main view. Note, you must always specify
151 the option: `--pretty=raw` since the main view parser expects to
157 tig(1) presents various 'views' of a repository. Each view is based on output
158 from an external command, most often 'git log', 'git diff', or 'git show'.
161 Is the default view, and it shows a one line summary of each commit
162 in the chosen list of revision. The summary includes commit date,
163 author, and the first line of the log message. Additionally, any
164 repository references, such as tags, will be shown.
167 Presents a more rich view of the revision log showing the whole log
168 message and the diffstat.
171 Shows either the diff of the current working tree, that is, what
172 has changed since the last commit, or the commit diff complete
173 with log message, diffstat and diff.
176 Is used for displaying both input from stdin and output from git
177 commands entered in the internal prompt.
180 Displays the information from the tig(1) man page. For the help view
181 to work you need to have the tig(1) man page installed.
185 Below the default key bindings are shown.
196 Switch to pager view.
200 If on a commit line show the commit diff. Additionally, if in
201 main or log view this will split the view. To open the commit
202 diff in full size view either use 'd' or press Return twice.
209 Move cursor one line up.
211 Move cursor one line down.
213 Move cursor one line up and enter. When used in the main view
214 this will always show the diff of the current commit in the
217 Move cursor one line down and enter.
219 Move cursor one page up.
221 Move cursor one page down.
230 Scroll view one line up.
232 Scroll view one line down.
234 Scroll view one page up.
236 Scroll view one page down.
245 Stop all background loading. This can be useful if you use
246 tig(1) in a repository with a long history without limiting
251 Toggle line numbers on/off.
253 Open prompt. This allows you to specify what git command
259 Revision specification
260 ----------------------
261 This section describes various ways to specify what revisions to display
262 or otherwise limit the view to. tig(1) does not itself parse the described
263 revision options so refer to the relevant git man pages for futher
264 information. Relevant man pages besides git-log(1) are git-diff(1) and
267 You can tune the interaction with git by making use of the options
268 explained in this section. For example, by configuring the environment
269 variables described in the <<view-commands, "View commands">> section.
273 If you are interested only in those revisions that made changes to a
274 specific file (or even several files) list the files like this:
278 To avoid ambiguity with repository references such as tag name, be sure
279 to separate file names from other git options using "\--". So if you
280 have a file named 'master' it will clash with the reference named
281 'master', and thus you will have to use:
285 NOTE: For the main view, avoiding ambiguity will in some cases require
286 you to specify two "\--" options. The first will make tig(1) stop
287 option processing and the latter will be passed to git log.
289 Limit by date or number
290 ~~~~~~~~~~~~~~~~~~~~~~~
291 To speed up interaction with git, you can limit the amount of commits
292 to show both for the log and main view. Either limit by date using
293 e.g. `--since=1.month` or limit by the number of commits using `-n400`.
295 If you are only interested in changed that happened between two dates
298 $ tig -- --after=may.5th --before=2006-05-16.15:44
300 NOTE: The dot (".") is used as a separator instead of a space to avoid
301 having to quote the option value.
303 Limiting by commit ranges
304 ~~~~~~~~~~~~~~~~~~~~~~~~~
305 Alternatively, commits can be limited to a specific range, such as
306 "all commits between 'tag-1.0' and 'tag-2.0'". For example:
308 $ tig log tag-1.0..tag-2.0
310 This way of commit limiting makes it trivial to only browse the commits
311 which haven't been pushed to a remote branch. Assuming 'origin' is your
312 upstream remote branch, using:
314 $ tig log origin..HEAD
316 will list what will be pushed to the remote branch. Optionally, the ending
317 'HEAD' can be left out since it is implied.
319 Limiting by reachability
320 ~~~~~~~~~~~~~~~~~~~~~~~~
321 Git interprets the range specifier "tag-1.0..tag-2.0" as
322 "all commits reachable from 'tag-2.0' but not from 'tag-1.0'".
323 Where reachability refers to what commits are ancestors (or part of the
324 history) of the branch or tagged revision in question.
326 If you prefer to specify which commit to preview in this way use the
329 $ tig log tag-2.0 ^tag-1.0
331 You can think of '^' as a negation operator. Using this alternate syntax,
332 it is possible to further prune commits by specifying multiple branch
335 Combining revisions specification
336 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
337 Revisions options can to some degree be combined, which makes it possible
338 to say "show at most 20 commits from within the last month that changed
339 files under the Documentation/ directory."
341 $ tig -- --since=1.month -n20 -- Documentation/
343 Examining all repository references
344 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
345 In some cases, it can be useful to query changes across all references
346 in a repository. An example is to ask "did any line of development in
347 this repository change a particular file within the last week". This
348 can be accomplished using:
350 $ tig -- --all --since=1.week -- Makefile
354 Known bugs and problems:
356 - If the screen width is very small the main view can draw
357 outside the current view causing bad wrapping. Same goes
358 for title and status windows.
362 Features that should be explored.
370 Copyright (c) Jonas Fonseca <fonseca@diku.dk>, 2006
372 This program is free software; you can redistribute it and/or modify
373 it under the terms of the GNU General Public License as published by
374 the Free Software Foundation; either version 2 of the License, or
375 (at your option) any later version.
380 link:http://www.kernel.org/pub/software/scm/git/docs/[git(7)],
381 link:http://www.kernel.org/pub/software/scm/cogito/docs/[cogito(7)]
382 gitk(1): git repository browser written using tcl/tk,
383 gitview(1): git repository browser written using python/gtk.