manual: remove section on porcelains
[tig] / manual.txt
CommitLineData
d839253b
JF
1The tig Manual
2==============
3Jonas Fonseca <fonseca@diku.dk>
4
5This is the manual for tig, the ncurses-based text-mode interface for git.
6Tig allows you to browse changes in a git repository and can additionally act
7as a pager for output of various git commands. When used as a pager, it will
8display input from stdin and colorize it.
9
10When browsing repositories, tig uses the underlying git commands to present
11the user with various views, such as summarized commit log and showing the
12commit with the log message, diffstat, and the diff.
13
9783cb12 14ifndef::backend-docbook[]
2bc4f7bd
JF
15*Table of Contents*
16
9783cb12
JF
17include::manual.toc[]
18endif::backend-docbook[]
19
20[[calling-conventions]]
d839253b
JF
21Calling Conventions
22-------------------
23
9783cb12 24[[pager-mode]]
d839253b
JF
25Pager Mode
26~~~~~~~~~~
27
28If stdin is a pipe, any log or diff options will be ignored and the pager view
29will be opened loading data from stdin. The pager mode can be used for
30colorizing output from various git commands.
31
32Example on how to colorize the output of git-show(1):
33
511147de
JF
34-----------------------------------------------------------------------------
35$ git show | tig
36-----------------------------------------------------------------------------
d839253b 37
9783cb12 38[[cmd-options]]
d839253b
JF
39Git Command Options
40~~~~~~~~~~~~~~~~~~~
41
42All git command options specified on the command line will be passed to the
43given command and all will be shell quoted before they are passed to the
44shell.
45
46NOTE: If you specify options for the main view, you should not use the
47`--pretty` option as this option will be set automatically to the format
48expected by the main view.
49
50Example on how to open the log view and show both author and committer
51information:
52
511147de
JF
53-----------------------------------------------------------------------------
54$ tig log --pretty=fuller
55-----------------------------------------------------------------------------
d839253b
JF
56
57See the <<refspec, "Specifying revisions">> section below for an introduction
58to revision options supported by the git commands. For details on specific git
59command options, refer to the man page of the command in question.
60
9783cb12 61[[env-variables]]
d839253b
JF
62Environment Variables
63---------------------
64
65Several options related to the interface with git can be configured via
66environment options.
67
9783cb12 68[[repo-refs]]
d839253b
JF
69Repository References
70~~~~~~~~~~~~~~~~~~~~~
71
72Commits that are referenced by tags and branch heads will be marked by the
73reference name surrounded by '[' and ']':
74
511147de
JF
75-----------------------------------------------------------------------------
762006-03-26 19:42 Petr Baudis | [cogito-0.17.1] Cogito 0.17.1
77-----------------------------------------------------------------------------
d839253b
JF
78
79If you want to filter out certain directories under `.git/refs/`, say `tmp`
80you can do it by setting the following variable:
81
511147de
JF
82-----------------------------------------------------------------------------
83$ TIG_LS_REMOTE="git ls-remote . | sed /\/tmp\//d" tig
84-----------------------------------------------------------------------------
d839253b
JF
85
86Or set the variable permanently in your environment.
87
88TIG_LS_REMOTE::
89 Set command for retrieving all repository references. The command
90 should output data in the same format as git-ls-remote(1).
91
92[[history-commands]]
93History Commands
94~~~~~~~~~~~~~~~~
95
96It is possible to alter which commands are used for the different views. If
97for example you prefer commits in the main view to be sorted by date and only
98show 500 commits, use:
99
511147de
JF
100-----------------------------------------------------------------------------
101$ TIG_MAIN_CMD="git log --date-order -n500 --pretty=raw %s" tig
102-----------------------------------------------------------------------------
d839253b
JF
103
104Or set the variable permanently in your environment.
105
106Notice, how `%s` is used to specify the commit reference. There can be a
107maximum of 5 `%s` ref specifications.
108
109TIG_DIFF_CMD::
110 The command used for the diff view. By default, git show is used
111 as a backend.
112
113TIG_LOG_CMD::
114 The command used for the log view. If you prefer to have both
115 author and committer shown in the log view be sure to pass
116 `--pretty=fuller` to git log.
117
118TIG_MAIN_CMD::
119 The command used for the main view. Note, you must always specify
120 the option: `--pretty=raw` since the main view parser expects to
121 read that format.
122
66c86725
JF
123[[tree-commands]]
124Tree Commands
125~~~~~~~~~~~~~
126
127TIG_TREE_CMD::
128 The command used for the tree view. Takes two arguments, the first
129 is the revision ID and the second is the path of the directory tree,
130 empty for the root directory. Defaults to "git ls-tree %s %s".
131
132TIG_BLOB_CMD::
133 The command used for the blob view. Takes one argument which is
134 the blob ID. Defaults to "git cat-file blob %s".
135
9783cb12 136[[viewer]]
d839253b
JF
137The Viewer
138----------
139
140The display consists of a status window on the last line of the screen and one
141or more views. The default is to only show one view at the time but it is
142possible to split both the main and log view to also show the commit diff.
143
144If you are in the log view and press 'Enter' when the current line is a commit
145line, such as:
146
511147de
JF
147-----------------------------------------------------------------------------
148commit 4d55caff4cc89335192f3e566004b4ceef572521
149-----------------------------------------------------------------------------
d839253b
JF
150
151You will split the view so that the log view is displayed in the top window
152and the diff view in the bottom window. You can switch between the two views
153by pressing 'Tab'. To maximize the log view again, simply press 'l'.
154
9783cb12 155[[commit-id]]
d839253b
JF
156Current Head and Commit ID
157~~~~~~~~~~~~~~~~~~~~~~~~~~
158
159The viewer keeps track of both what head and commit ID you are currently
f7ffec06 160viewing. The commit ID will follow the cursor line and change every time
d839253b
JF
161you highlight a different commit. Whenever you reopen the diff view it will be
162reloaded, if the commit ID changed.
163
164The head ID is used when opening the main and log view to indicate from what
165revision to show history.
166
9783cb12 167[[views]]
d839253b
JF
168Views
169~~~~~
170
511147de 171Various 'views' of a repository is presented. Each view is based on output
d839253b
JF
172from an external command, most often 'git log', 'git diff', or 'git show'.
173
174The main view::
175 Is the default view, and it shows a one line summary of each commit
176 in the chosen list of revisions. The summary includes commit date,
177 author, and the first line of the log message. Additionally, any
178 repository references, such as tags, will be shown.
179
180The log view::
181 Presents a more rich view of the revision log showing the whole log
182 message and the diffstat.
183
184The diff view::
185 Shows either the diff of the current working tree, that is, what
186 has changed since the last commit, or the commit diff complete
187 with log message, diffstat and diff.
188
3360f449
JF
189The tree view::
190 Lists directory trees associated with the current revision allowing
191 subdirectories to be descended or ascended and file blobs to be
192 viewed.
193
194The blob view::
195 Displays the file content or "blob" of data associated with a file
196 name.
197
173d76ea
JF
198The status view::
199 Displays status of files in the working tree and allows changes to be
200 staged/unstaged as well as adding of untracked files.
201
f9a044a4
JF
202The stage view::
203 Displays diff changes for staged or unstanged files being tracked or
204 file content of untracked files.
205
d839253b
JF
206The pager view::
207 Is used for displaying both input from stdin and output from git
208 commands entered in the internal prompt.
209
210The help view::
24b5b3e0 211 Displays key binding quick reference.
d839253b 212
9783cb12 213[[title-window]]
d839253b
JF
214Title Windows
215~~~~~~~~~~~~~
216
217Each view has a title window which shows the name of the view, current commit
218ID if available, and where the view is positioned:
219
511147de
JF
220-----------------------------------------------------------------------------
221[main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
222-----------------------------------------------------------------------------
d839253b
JF
223
224By default, the title of the current view is highlighted using bold font. For
225long loading views (taking over 3 seconds) the time since loading started will
226be appended:
227
511147de
JF
228-----------------------------------------------------------------------------
229[main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
230-----------------------------------------------------------------------------
d839253b 231
9783cb12 232[[keys]]
669b0c34
JF
233Default Keybindings
234-------------------
d839253b
JF
235Below the default key bindings are shown.
236
9783cb12 237[[view-switching]]
d839253b
JF
238View Switching
239~~~~~~~~~~~~~~
669b0c34
JF
240
241`-------`--------------------------------------------------------------------
242Key Action
243-----------------------------------------------------------------------------
244m Switch to main view.
245d Switch to diff view.
246l Switch to log view.
247p Switch to pager view.
3360f449 248t Switch to (directory) tree view.
0001fc34 249f Switch to (file) blob view.
173d76ea
JF
250h Switch to help view
251S Switch to status view
f9a044a4 252c Switch to stage view
669b0c34 253-----------------------------------------------------------------------------
d839253b 254
9783cb12 255[[view-manipulation]]
d839253b
JF
256View Manipulation
257~~~~~~~~~~~~~~~~~
669b0c34
JF
258
259`-------`--------------------------------------------------------------------
260Key Action
261-----------------------------------------------------------------------------
262q Close view, if multiple views are open it will jump back to the \
263 previous view in the view stack. If it is the last open view it \
d839253b 264 will quit. Use 'Q' to quit all views at once.
669b0c34
JF
265Enter This key is "context sensitive" depending on what view you are \
266 currently in. When in log view on a commit line or in the main \
267 view, split the view and show the commit diff. In the diff view \
d839253b 268 pressing Enter will simply scroll the view one line down.
669b0c34 269Tab Switch to next view.
272818ea 270R Reload and refresh the current view.
669b0c34 271Up This key is "context sensitive" and will move the cursor one \
f7ffec06 272 line up. However, if you opened a diff view from the main view \
669b0c34
JF
273 (split- or full-screen) it will change the cursor to point to \
274 the previous commit in the main view and update the diff view \
d839253b 275 to display it.
669b0c34
JF
276Down Similar to 'Up' but will move down.
277-----------------------------------------------------------------------------
d839253b 278
9783cb12 279[[cursor-nav]]
d839253b
JF
280Cursor Navigation
281~~~~~~~~~~~~~~~~~
669b0c34
JF
282
283`-------`--------------------------------------------------------------------
284Key Action
285-----------------------------------------------------------------------------
286j Move cursor one line up.
287k Move cursor one line down.
03e8d891
JF
288PgUp,\
289-,a Move cursor one page up.
669b0c34
JF
290PgDown Space Move cursor one page down.
291Home Jump to first line.
292End Jump to last line.
293-----------------------------------------------------------------------------
d839253b 294
9783cb12 295[[view-scrolling]]
d839253b
JF
296Scrolling
297~~~~~~~~~
669b0c34
JF
298
299`-------`--------------------------------------------------------------------
300Key Action
301-----------------------------------------------------------------------------
302Insert Scroll view one line up.
303Delete Scroll view one line down.
304w Scroll view one page up.
305s Scroll view one page down.
306-----------------------------------------------------------------------------
d839253b 307
4af34daa
JF
308[[searching]]
309Searching
310~~~~~~~~~
311
312`-------`--------------------------------------------------------------------
313Key Action
314-----------------------------------------------------------------------------
315/ Search the view. Opens a prompt for entering search regex to use.
316? Search backwards in the view. Also prompts for regex.
317n Find next match for the current search regex.
318N Find previous match for the current search regex.
319-----------------------------------------------------------------------------
320
9783cb12 321[[misc-keys]]
d839253b
JF
322Misc
323~~~~
669b0c34
JF
324
325`-------`--------------------------------------------------------------------
326Key Action
327-----------------------------------------------------------------------------
328Q Quit.
329r Redraw screen.
330z Stop all background loading. This can be useful if you use \
331 tig in a repository with a long history without limiting \
d839253b 332 the revision log.
669b0c34 333v Show version.
904e68d8 334'.' Toggle line numbers on/off.
669b0c34
JF
335g Toggle revision graph visualization on/off.
336':' Open prompt. This allows you to specify what git command \
337 to run. Example `:log -p`
f9a044a4
JF
338u Update status of file. In the status view, this allows you to add an \
339 untracked file or stage changes to a file for next commit (similar to \
340 running git-add <filename>). In the stage view, when pressing this on \
341 a diff chunk line stages only that chunk for next commit, when not on \
342 a diff chunk line all changes in the displayed diff is staged.
b5c18d9d
JF
343M Resolve unmerged file by launching git-mergetool(1). Note, to work \
344 correctly this might require some initial configuration of your \
345 preferred merge tool. See the manpage of git-mergetool(1).
669b0c34 346-----------------------------------------------------------------------------
d839253b 347
f655964f
JF
348[[external-commands]]
349External Commands
350~~~~~~~~~~~~~~~~~
351
352Tig also comes with a few builtin external commands. These are simple shell
353commands that are run and can take arguments from the current browsing state,
354such as the current commit ID. The default commands are:
355
356`-------`--------------------------------------------------------------------
357Key Action
358-----------------------------------------------------------------------------
359C git cherry-pick %(commit)
360G git gc
361-----------------------------------------------------------------------------
362
d839253b
JF
363[[refspec]]
364Revision Specification
365----------------------
366
367This section describes various ways to specify what revisions to display or
511147de 368otherwise limit the view to. Tig does not itself parse the described
f7ffec06 369revision options so refer to the relevant git man pages for further
d839253b
JF
370information. Relevant man pages besides git-log(1) are git-diff(1) and
371git-rev-list(1).
372
373You can tune the interaction with git by making use of the options explained
374in this section. For example, by configuring the environment variables
375described in the <<history-commands, "History commands">> section.
376
9783cb12 377[[path-limiting]]
d839253b
JF
378Limit by Path Name
379~~~~~~~~~~~~~~~~~~
380
381If you are interested only in those revisions that made changes to a specific
382file (or even several files) list the files like this:
383
511147de
JF
384-----------------------------------------------------------------------------
385$ tig log Makefile README
386-----------------------------------------------------------------------------
d839253b
JF
387
388To avoid ambiguity with repository references such as tag name, be sure to
389separate file names from other git options using "\--". So if you have a file
390named 'master' it will clash with the reference named 'master', and thus you
391will have to use:
392
511147de
JF
393-----------------------------------------------------------------------------
394$ tig log -- master
395-----------------------------------------------------------------------------
d839253b
JF
396
397NOTE: For the main view, avoiding ambiguity will in some cases require you to
511147de 398specify two "\--" options. The first will make tig stop option processing
d839253b
JF
399and the latter will be passed to git log.
400
9783cb12 401[[date-number-limiting]]
d839253b
JF
402Limit by Date or Number
403~~~~~~~~~~~~~~~~~~~~~~~
404
405To speed up interaction with git, you can limit the amount of commits to show
406both for the log and main view. Either limit by date using e.g.
407`--since=1.month` or limit by the number of commits using `-n400`.
408
409If you are only interested in changed that happened between two dates you can
410use:
411
511147de
JF
412-----------------------------------------------------------------------------
413$ tig -- --after="May 5th" --before="2006-05-16 15:44"
414-----------------------------------------------------------------------------
d839253b
JF
415
416NOTE: If you want to avoid having to quote dates containing spaces you can use
417"." instead, e.g. `--after=May.5th`.
418
9783cb12 419[[commit-range-limiting]]
d839253b
JF
420Limiting by Commit Ranges
421~~~~~~~~~~~~~~~~~~~~~~~~~
422
423Alternatively, commits can be limited to a specific range, such as "all
424commits between 'tag-1.0' and 'tag-2.0'". For example:
425
511147de
JF
426-----------------------------------------------------------------------------
427$ tig log tag-1.0..tag-2.0
428-----------------------------------------------------------------------------
d839253b
JF
429
430This way of commit limiting makes it trivial to only browse the commits which
431haven't been pushed to a remote branch. Assuming 'origin' is your upstream
432remote branch, using:
433
511147de
JF
434-----------------------------------------------------------------------------
435$ tig log origin..HEAD
436-----------------------------------------------------------------------------
d839253b
JF
437
438will list what will be pushed to the remote branch. Optionally, the ending
439'HEAD' can be left out since it is implied.
440
9783cb12 441[[reachability-limiting]]
d839253b
JF
442Limiting by Reachability
443~~~~~~~~~~~~~~~~~~~~~~~~
444
445Git interprets the range specifier "tag-1.0..tag-2.0" as "all commits
446reachable from 'tag-2.0' but not from 'tag-1.0'". Where reachability refers
447to what commits are ancestors (or part of the history) of the branch or tagged
448revision in question.
449
450If you prefer to specify which commit to preview in this way use the
451following:
452
511147de
JF
453-----------------------------------------------------------------------------
454$ tig log tag-2.0 ^tag-1.0
455-----------------------------------------------------------------------------
d839253b
JF
456
457You can think of '^' as a negation operator. Using this alternate syntax, it
458is possible to further prune commits by specifying multiple branch cut offs.
459
9783cb12 460[[refspec-combi]]
d839253b
JF
461Combining Revisions Specification
462~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
463
464Revisions options can to some degree be combined, which makes it possible to
465say "show at most 20 commits from within the last month that changed files
466under the Documentation/ directory."
467
511147de
JF
468-----------------------------------------------------------------------------
469$ tig -- --since=1.month -n20 -- Documentation/
470-----------------------------------------------------------------------------
d839253b 471
9783cb12 472[[refspec-all]]
d839253b
JF
473Examining All Repository References
474~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
475
476In some cases, it can be useful to query changes across all references in a
477repository. An example is to ask "did any line of development in this
478repository change a particular file within the last week". This can be
479accomplished using:
480
511147de
JF
481-----------------------------------------------------------------------------
482$ tig -- --all --since=1.week -- Makefile
483-----------------------------------------------------------------------------
d839253b
JF
484
485include::BUGS[]
486
9783cb12 487[[copy-right]]
d839253b
JF
488Copyright
489---------
490
f9a044a4 491Copyright (c) 2006-2007 Jonas Fonseca <fonseca@diku.dk>
d839253b
JF
492
493This program is free software; you can redistribute it and/or modify
494it under the terms of the GNU General Public License as published by
495the Free Software Foundation; either version 2 of the License, or
496(at your option) any later version.
497
9783cb12 498[[references]]
d839253b
JF
499References and Related Tools
500----------------------------
501
511147de
JF
502Manpages:
503
504 - gitlink:tig[1]
505 - gitlink:tigrc[5]
506
507Online resources:
508
d839253b
JF
509include::SITES[]
510
d839253b
JF
511Other git repository browsers:
512
513 - gitk(1)
514 - qgit(1)
515 - gitview(1)