Update manual to reflect default keybinding changes
[tig.git] / doc / tig.1.adoc
blobf94f45bea8ad7a5eec4922b2aafacc8978f781f4
1 tig(1)
2 ======
3 :docext: adoc
4 :sysconfdir: /etc
6 NAME
7 ----
8 tig - text-mode interface for Git
10 SYNOPSIS
11 --------
12 [verse]
13 _______________________________________________________________________
14 tig        [options] [revisions] [--] [paths]
15 tig log    [options] [revisions] [--] [paths]
16 tig show   [options] [revisions] [--] [paths]
17 tig blame  [options] [rev] [--] path
18 tig grep   [options] [pattern]
19 tig refs
20 tig stash
21 tig status
22 tig <      [Git command output]
23 _______________________________________________________________________
25 DESCRIPTION
26 -----------
28 Tig is an ncurses-based text-mode interface for git(1). It functions
29 mainly as a Git repository browser, but can also assist in staging
30 changes for commit at chunk level and act as a pager for output from
31 various Git commands.
33 OPTIONS
34 -------
36 Command line options recognized by Tig include all valid git-log(1) and
37 git-diff(1) options, as well as the following subcommands and Tig specific
38 options. The first command line parameter not starting with "-" is interpreted
39 as being either a revision specification or a path and will end the option
40 parsing. All additional options will be passed to the underlying Git command.
42 show::
43         Open diff view using the given git-show(1) options.
45 blame::
46         Show given file annotated by commits.
47         Takes zero or more git-blame(1) options.
48         Optionally limited from given revision.
50 status::
51         Start up in status view.
53 log::
54         Start up in log view, displaying git-log(1) output.
56 refs::
57         Start up in refs view.
59 stash::
60         Start up in stash view.
62 grep::
63         Open the grep view. Supports the same options as git-grep(1).
65 +<number>::
66     Show the first view with line <number> visible and selected.
68 -v, --version::
69         Show version and exit.
71 -h, --help::
72         Show help message and exit.
74 PAGER MODE
75 ----------
77 Tig enters pager mode when input is provided via stdin and supports the
78 following subcommands and options:
82  - When the 'show' subcommand is specified and the '--stdin' option is given,
83    stdin is assumed to be a list of commit IDs and will be forwarded to the diff
84    view's underlying git-show(1) command. For example:
86 -----------------------------------------------------------------------------
87 $ git rev-list --author=vivien HEAD | tig show --stdin
88 -----------------------------------------------------------------------------
90  - When '--stdin' is given, stdin is assumed to be a list of commit IDs
91    and will be forwarded to the main view's underlying git-log(1)
92    command. For example:
94 -----------------------------------------------------------------------------
95 $ tig --no-walk --stdin < cherry-picks.txt
96 -----------------------------------------------------------------------------
98  - When '--pretty=raw' is given, stdin is assumed to be a "pretty=raw"
99    formatted output similar to that of git-log(1). For example:
101 -----------------------------------------------------------------------------
102 $ git reflog --pretty=raw | tig --pretty=raw
103 -----------------------------------------------------------------------------
107 When no subcommands nor options are given, the pager view will be used for
108 displaying the Git command input given on stdin. The pager view assumes the
109 input is either from git-log(1) or git-diff(1) and will highlight it similar to
110 the log and diff views. For example:
112 -----------------------------------------------------------------------------
113 $ git log -Schange -p --raw | tig
114 -----------------------------------------------------------------------------
116 EXAMPLES
117 --------
119 Display the list of commits for the current branch:
120 -----------------------------------------------------------------------------
121 $ tig
122 -----------------------------------------------------------------------------
124 Display commits from one or more branches:
125 -----------------------------------------------------------------------------
126 $ tig test master
127 -----------------------------------------------------------------------------
129 Display all branches:
130 -----------------------------------------------------------------------------
131 $ tig --all
132 -----------------------------------------------------------------------------
134 Display differences between two branches:
135 -----------------------------------------------------------------------------
136 $ tig test..master
137 -----------------------------------------------------------------------------
139 Display changes for sub-module versions:
140 -----------------------------------------------------------------------------
141 $ tig --submodule
142 -----------------------------------------------------------------------------
144 Display changes for a single file:
145 -----------------------------------------------------------------------------
146 $ tig -- README
147 -----------------------------------------------------------------------------
149 Display contents of the README file in a specific revision:
150 -----------------------------------------------------------------------------
151 $ tig show tig-0.8:README
152 -----------------------------------------------------------------------------
154 Display revisions between two dates for a specific file:
155 -----------------------------------------------------------------------------
156 $ tig --after="2004-01-01" --before="2006-05-16" -- README
157 -----------------------------------------------------------------------------
159 Blame file with copy detection enabled:
160 -----------------------------------------------------------------------------
161 $ tig blame -C README
162 -----------------------------------------------------------------------------
164 Display the list of stashes:
165 -----------------------------------------------------------------------------
166 $ tig stash
167 -----------------------------------------------------------------------------
169 Grep all files for lines containing `DEFINE_ENUM`:
170 -----------------------------------------------------------------------------
171 $ tig grep -p DEFINE_ENUM
172 -----------------------------------------------------------------------------
174 Show references (branches, remotes and tags):
175 -----------------------------------------------------------------------------
176 $ tig refs
177 -----------------------------------------------------------------------------
179 ENVIRONMENT VARIABLES
180 ---------------------
182 In addition to environment variables used by Git (e.g. GIT_DIR), Tig defines
183 the ones below. The command related environment variables have access to the
184 internal state of Tig via replacement variables, such as `%(commit)` and
185 `%(blob)`.
186 ifdef::version[]
187 See manpage:tigrc[5] for a full list.
188 endif::version[]
189 ifndef::version[]
190 See link:tigrc.5.{docext}[tigrc(5)] for a full list.
191 endif::version[]
193 TIGRC_USER::
194         Path of the user configuration file (defaults to `~/.tigrc`).
196 TIGRC_SYSTEM::
197         Path of the system wide configuration file (defaults to
198         `{sysconfdir}/tigrc`). Define to empty string to use built-in
199         configuration.
201 TIG_LS_REMOTE::
202         Set command for retrieving all repository references. The command
203         should output data in the same format as git-ls-remote(1).
205 TIG_DIFF_OPTS::
206         The diff options to use in the diff view. The diff view uses
207         git-show(1) for formatting and always passes --patch-with-stat.  You
208         may also set the `diff-options` setting in the configuration file.
210 TIG_TRACE::
211         Path for trace file where information about Git commands are logged.
213 TIG_SCRIPT::
214         Path to script that should be executed automatically on startup. If this
215         environment variable is defined to the empty string, the script is read
216         from stdin. The script is interpreted line-by-line and can contain
217         prompt commands and key mappings.
219 TIG_NO_DISPLAY::
220         Open Tig without rendering anything to the terminal. This force Ncurses
221         to write to /dev/null. The main use is for automated testing of Tig.
223 FILES
224 -----
225 '~/.tigrc'::
226         User configuration file. See manpage:tigrc[5] for examples.
228 '{sysconfdir}/tigrc'::
229         System wide configuration file.
231 '$GIT_DIR/config'::
232 '~/.gitconfig::
233 '{sysconfdir}/gitconfig::
234         Git configuration files. Read on start-up with the help of
235         git-config(1).
237 BUGS
238 ----
240 Please visit Tig's http://jonas.nitro.dk/tig[home page] or
241 https://github.com/jonas/tig[main Git repository] for information about
242 new releases and how to report bugs or feature request.
244 COPYRIGHT
245 ---------
246 Copyright (c) 2006-2014 Jonas Fonseca <jonas.fonseca@gmail.com>
248 This program is free software; you can redistribute it and/or modify
249 it under the terms of the GNU General Public License as published by
250 the Free Software Foundation; either version 2 of the License, or
251 (at your option) any later version.
253 SEE ALSO
254 --------
255 ifndef::backend-docbook[]
256 link:tigrc.5.{docext}[tigrc(5)],
257 link:manual.{docext}[the Tig manual],
258 endif::backend-docbook[]
259 ifdef::backend-docbook[]
260 manpage:tigrc[5],
261 manpage:tigmanual[7],
262 endif::backend-docbook[]
263 git(7)