![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/manual.txt b/manual.txt
index 82e848e98dd4750e55c2c85b47d6503e3832977d..8ac7cd28c90e723b5d7bd5c1ae834d407e4721ca 100644 (file)
--- a/manual.txt
+++ b/manual.txt
shell.
NOTE: If you specify options for the main view, you should not use the
-`--pretty` option as this option will be set automatically to the format
+`\--pretty` option as this option will be set automatically to the format
expected by the main view.
-Example on how to open the log view and show both author and committer
+Example on how to view a commit and show both author and committer
information:
-----------------------------------------------------------------------------
-$ tig log --pretty=fuller
+$ tig show --pretty=fuller
-----------------------------------------------------------------------------
-See the <<refspec, "Specifying revisions">> section below for an introduction
-to revision options supported by the git commands. For details on specific git
+See the section on <<refspec, specifying revisions>> for an introduction to
+revision options supported by the git commands. For details on specific git
command options, refer to the man page of the command in question.
+[[viewer]]
+The Viewer
+----------
+
+The display consists of a status window on the last line of the screen and one
+or more views. The default is to only show one view at the time but it is
+possible to split both the main and log view to also show the commit diff.
+
+If you are in the log view and press 'Enter' when the current line is a commit
+line, such as:
+
+-----------------------------------------------------------------------------
+commit 4d55caff4cc89335192f3e566004b4ceef572521
+-----------------------------------------------------------------------------
+
+You will split the view so that the log view is displayed in the top window
+and the diff view in the bottom window. You can switch between the two views
+by pressing 'Tab'. To maximize the log view again, simply press 'l'.
+
+[[views]]
+Views
+~~~~~
+
+Various 'views' of a repository is presented. Each view is based on output
+from an external command, most often 'git log', 'git diff', or 'git show'.
+
+The main view::
+ Is the default view, and it shows a one line summary of each commit
+ in the chosen list of revisions. The summary includes commit date,
+ author, and the first line of the log message. Additionally, any
+ repository references, such as tags, will be shown.
+
+The log view::
+ Presents a more rich view of the revision log showing the whole log
+ message and the diffstat.
+
+The diff view::
+ Shows either the diff of the current working tree, that is, what
+ has changed since the last commit, or the commit diff complete
+ with log message, diffstat and diff.
+
+The tree view::
+ Lists directory trees associated with the current revision allowing
+ subdirectories to be descended or ascended and file blobs to be
+ viewed.
+
+The blob view::
+ Displays the file content or "blob" of data associated with a file
+ name.
+
+The blame view::
+ Displays the file content annotated or blamed by commits.
+
+The status view::
+ Displays status of files in the working tree and allows changes to be
+ staged/unstaged as well as adding of untracked files.
+
+The stage view::
+ Displays diff changes for staged or unstanged files being tracked or
+ file content of untracked files.
+
+The pager view::
+ Is used for displaying both input from stdin and output from git
+ commands entered in the internal prompt.
+
+The help view::
+ Displays a quick reference of key bindings.
+
+[[commit-id]]
+Browsing State and User-defined Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The viewer keeps track of both what head and commit ID you are currently
+viewing. The commit ID will follow the cursor line and change every time you
+highlight a different commit. Whenever you reopen the diff view it will be
+reloaded, if the commit ID changed. The head ID is used when opening the main
+and log view to indicate from what revision to show history.
+
+Some of the commands used or provided by tig can be configured. This goes for
+the <<external-commands, external commands>>. These user-defined commands can
+use arguments that refer to the current browsing state by using one of the
+following variables.
+
+`-----------------------`-----------------------------------------------------
+Browsing state variables
+------------------------------------------------------------------------------
+%(head) The currently viewed 'head' ID. Defaults to HEAD
+%(commit) The currently selected commit ID.
+%(blob) The currently selected blob ID.
+%(directory) The current directory path in the tree view; \
+ empty for the root directory.
+%(file) The currently selected file.
+%(ref) The reference given to blame or HEAD if undefined.
+------------------------------------------------------------------------------
+
+[[title-window]]
+Title Windows
+~~~~~~~~~~~~~
+
+Each view has a title window which shows the name of the view, current commit
+ID if available, and where the view is positioned:
+
+-----------------------------------------------------------------------------
+[main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
+-----------------------------------------------------------------------------
+
+By default, the title of the current view is highlighted using bold font. For
+long loading views (taking over 3 seconds) the time since loading started will
+be appended:
+
+-----------------------------------------------------------------------------
+[main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
+-----------------------------------------------------------------------------
+
[[env-variables]]
Environment Variables
---------------------
Several options related to the interface with git can be configured via
environment options.
+[[configuration-files]]
+Configuration Files
+~~~~~~~~~~~~~~~~~~~
+
+Upon startup, tig first reads the system wide configuration file
+(`{sysconfdir}/tigrc` by default) and then proceeds to read the user's
+configuration file (`~/.tigrc` by default). The paths to either of these files
+can be overridden through the following environment variables:
+
+TIGRC_USER::
+ Path of the user configuration file.
+
+TIGRC_SYSTEM::
+ Path of the system wide configuration file.
+
[[repo-refs]]
Repository References
~~~~~~~~~~~~~~~~~~~~~
2006-03-26 19:42 Petr Baudis | [cogito-0.17.1] Cogito 0.17.1
-----------------------------------------------------------------------------
-If you want to filter out certain directories under `.git/refs/`, say `tmp`
-you can do it by setting the following variable:
+If you want to filter what branches gets shown, say limit to only show
+branches named `master` or which starts with the `jf/` prefix, you can
+do it by setting the following variable:
-----------------------------------------------------------------------------
-$ TIG_LS_REMOTE="git ls-remote . | sed /\/tmp\//d" tig
+$ TIG_LS_REMOTE="git ls-remote . master jf/*" tig
-----------------------------------------------------------------------------
Or set the variable permanently in your environment.
+--
+
TIG_LS_REMOTE::
+
Set command for retrieving all repository references. The command
- should output data in the same format as git-ls-remote(1).
+ should output data in the same format as git-ls-remote(1). Defaults
+ to:
+-----------------------------------------------------------------------------
+git ls-remote .
+-----------------------------------------------------------------------------
+
+--
[[history-commands]]
History Commands
Notice, how `%s` is used to specify the commit reference. There can be a
maximum of 5 `%s` ref specifications.
+--
+
TIG_DIFF_CMD::
- The command used for the diff view. By default, git show is used
- as a backend.
+
+ The command used for the diff view. Defaults to:
+-----------------------------------------------------------------------------
+git show --pretty=fuller --no-color --root
+ --patch-with-stat --find-copies-harder -C %s
+-----------------------------------------------------------------------------
TIG_LOG_CMD::
+
The command used for the log view. If you prefer to have both
author and committer shown in the log view be sure to pass
- `--pretty=fuller` to git log.
+ `\--pretty=fuller` to git log. Defaults to:
+-----------------------------------------------------------------------------
+git log --no-color --cc --stat -n100 %s
+-----------------------------------------------------------------------------
TIG_MAIN_CMD::
+
The command used for the main view. Note, you must always specify
- the option: `--pretty=raw` since the main view parser expects to
+ the option: `\--pretty=raw` since the main view parser expects to
read that format.
-
-[[viewer]]
-The Viewer
-----------
-
-The display consists of a status window on the last line of the screen and one
-or more views. The default is to only show one view at the time but it is
-possible to split both the main and log view to also show the commit diff.
-
-If you are in the log view and press 'Enter' when the current line is a commit
-line, such as:
-
-----------------------------------------------------------------------------
-commit 4d55caff4cc89335192f3e566004b4ceef572521
+git log --no-color --pretty=raw --parents --topo-order %s
-----------------------------------------------------------------------------
-You will split the view so that the log view is displayed in the top window
-and the diff view in the bottom window. You can switch between the two views
-by pressing 'Tab'. To maximize the log view again, simply press 'l'.
-
-[[commit-id]]
-Current Head and Commit ID
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The viewer keeps track of both what head and commit ID you are currently
-viewing. The commit ID will follow the cursor line and change everytime time
-you highlight a different commit. Whenever you reopen the diff view it will be
-reloaded, if the commit ID changed.
-
-The head ID is used when opening the main and log view to indicate from what
-revision to show history.
-
-[[views]]
-Views
-~~~~~
+--
-Various 'views' of a repository is presented. Each view is based on output
-from an external command, most often 'git log', 'git diff', or 'git show'.
-
-The main view::
- Is the default view, and it shows a one line summary of each commit
- in the chosen list of revisions. The summary includes commit date,
- author, and the first line of the log message. Additionally, any
- repository references, such as tags, will be shown.
-
-The log view::
- Presents a more rich view of the revision log showing the whole log
- message and the diffstat.
-
-The diff view::
- Shows either the diff of the current working tree, that is, what
- has changed since the last commit, or the commit diff complete
- with log message, diffstat and diff.
-
-The pager view::
- Is used for displaying both input from stdin and output from git
- commands entered in the internal prompt.
-
-The help view::
- Displays key binding quick reference.
-
-[[title-window]]
-Title Windows
+[[tree-commands]]
+Tree Commands
~~~~~~~~~~~~~
-Each view has a title window which shows the name of the view, current commit
-ID if available, and where the view is positioned:
+--
+
+TIG_TREE_CMD::
+ The command used for the tree view. Takes two arguments, the first is
+ the revision ID and the second is the path of the directory tree,
+ empty for the root directory. Defaults to:
-----------------------------------------------------------------------------
-[main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
+git ls-tree %s %s
-----------------------------------------------------------------------------
-By default, the title of the current view is highlighted using bold font. For
-long loading views (taking over 3 seconds) the time since loading started will
-be appended:
+TIG_BLOB_CMD::
+ The command used for the blob view. Takes one argument which is the
+ blob ID. Defaults to:
-----------------------------------------------------------------------------
-[main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
+git cat-file blob %s
-----------------------------------------------------------------------------
+--
+
[[keys]]
Default Keybindings
-------------------
d Switch to diff view.
l Switch to log view.
p Switch to pager view.
-h Show man page.
+t Switch to (directory) tree view.
+f Switch to (file) blob view.
+B Switch to blame view.
+h Switch to help view
+S Switch to status view
+c Switch to stage view
-----------------------------------------------------------------------------
[[view-manipulation]]
view, split the view and show the commit diff. In the diff view \
pressing Enter will simply scroll the view one line down.
Tab Switch to next view.
+R Reload and refresh the current view.
+M Maximize the current view to fill the whole display.
Up This key is "context sensitive" and will move the cursor one \
- line up. However, uf you opened a diff view from the main view \
+ line up. However, if you opened a diff view from the main view \
(split- or full-screen) it will change the cursor to point to \
the previous commit in the main view and update the diff view \
to display it.
tig in a repository with a long history without limiting \
the revision log.
v Show version.
-n Toggle line numbers on/off.
+'.' Toggle line numbers on/off.
+D Toggle date display on/off.
+A Toggle author display on/off.
g Toggle revision graph visualization on/off.
+F Toggle reference display on/off (tag and branch names).
':' Open prompt. This allows you to specify what git command \
to run. Example `:log -p`
+u Update status of file. In the status view, this allows you to add an \
+ untracked file or stage changes to a file for next commit (similar to \
+ running git-add <filename>). In the stage view, when pressing this on \
+ a diff chunk line stages only that chunk for next commit, when not on \
+ a diff chunk line all changes in the displayed diff is staged.
+M Resolve unmerged file by launching git-mergetool(1). Note, to work \
+ correctly this might require some initial configuration of your \
+ preferred merge tool. See the manpage of git-mergetool(1).
+! Checkout file with unstaged changes. This will reset the file to \
+ contain the content it had at last commit.
+@ Move to next chunk in the stage view.
+',' Move tree view to the parent tree.
+e Open file in editor.
+-----------------------------------------------------------------------------
+
+[[external-commands]]
+External Commands
+~~~~~~~~~~~~~~~~~
+
+For more custom needs, external commands provide a way to easily execute
+a script or program. They are bound to keys and use information from the
+current browsing state, such as the current commit ID. Tig comes with
+the following builtin external commands:
+
+`-------`--------------------------------------------------------------------
+Key Action
+-----------------------------------------------------------------------------
+C git cherry-pick %(commit)
+G git gc
-----------------------------------------------------------------------------
[[refspec]]
This section describes various ways to specify what revisions to display or
otherwise limit the view to. Tig does not itself parse the described
-revision options so refer to the relevant git man pages for futher
+revision options so refer to the relevant git man pages for further
information. Relevant man pages besides git-log(1) are git-diff(1) and
git-rev-list(1).
You can tune the interaction with git by making use of the options explained
in this section. For example, by configuring the environment variables
-described in the <<history-commands, "History commands">> section.
+described in the section on <<history-commands, history commands>>.
[[path-limiting]]
Limit by Path Name
file (or even several files) list the files like this:
-----------------------------------------------------------------------------
-$ tig log Makefile README
+$ tig Makefile README
-----------------------------------------------------------------------------
-To avoid ambiguity with repository references such as tag name, be sure to
-separate file names from other git options using "\--". So if you have a file
-named 'master' it will clash with the reference named 'master', and thus you
-will have to use:
+To avoid ambiguity with tig's subcommands or repository references such as tag
+name, be sure to separate file names from other git options using "\--". So if
+you have a file named 'status' it will clash with the 'status' subcommand, and
+thus you will have to use:
-----------------------------------------------------------------------------
-$ tig log -- master
+$ tig -- status
-----------------------------------------------------------------------------
-NOTE: For the main view, avoiding ambiguity will in some cases require you to
-specify two "\--" options. The first will make tig stop option processing
-and the latter will be passed to git log.
-
[[date-number-limiting]]
Limit by Date or Number
~~~~~~~~~~~~~~~~~~~~~~~
To speed up interaction with git, you can limit the amount of commits to show
both for the log and main view. Either limit by date using e.g.
-`--since=1.month` or limit by the number of commits using `-n400`.
+`\--since=1.month` or limit by the number of commits using `-n400`.
If you are only interested in changed that happened between two dates you can
use:
-----------------------------------------------------------------------------
-$ tig -- --after="May 5th" --before="2006-05-16 15:44"
+$ tig --after="May 5th" --before="2006-05-16 15:44"
-----------------------------------------------------------------------------
NOTE: If you want to avoid having to quote dates containing spaces you can use
-"." instead, e.g. `--after=May.5th`.
+"." instead, e.g. `\--after=May.5th`.
[[commit-range-limiting]]
Limiting by Commit Ranges
commits between 'tag-1.0' and 'tag-2.0'". For example:
-----------------------------------------------------------------------------
-$ tig log tag-1.0..tag-2.0
+$ tig tag-1.0..tag-2.0
-----------------------------------------------------------------------------
This way of commit limiting makes it trivial to only browse the commits which
remote branch, using:
-----------------------------------------------------------------------------
-$ tig log origin..HEAD
+$ tig origin..HEAD
-----------------------------------------------------------------------------
will list what will be pushed to the remote branch. Optionally, the ending
following:
-----------------------------------------------------------------------------
-$ tig log tag-2.0 ^tag-1.0
+$ tig tag-2.0 ^tag-1.0
-----------------------------------------------------------------------------
You can think of '^' as a negation operator. Using this alternate syntax, it
under the Documentation/ directory."
-----------------------------------------------------------------------------
-$ tig -- --since=1.month -n20 -- Documentation/
+$ tig --since=1.month -n20 -- Documentation/
-----------------------------------------------------------------------------
[[refspec-all]]
accomplished using:
-----------------------------------------------------------------------------
-$ tig -- --all --since=1.week -- Makefile
+$ tig --all --since=1.week -- Makefile
-----------------------------------------------------------------------------
include::BUGS[]
Copyright
---------
-Copyright (c) 2006 Jonas Fonseca <fonseca@diku.dk>
+Copyright (c) 2006-2008 Jonas Fonseca <fonseca@diku.dk>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
Manpages:
- - gitlink:tig[1]
- - gitlink:tigrc[5]
+ - manpage:tig[1]
+ - manpage:tigrc[5]
Online resources:
include::SITES[]
-Git porcelains:
-
- - link:http://www.kernel.org/pub/software/scm/git/docs/[git],
- - link:http://www.kernel.org/pub/software/scm/cogito/docs/[Cogito]
-
Other git repository browsers:
- gitk(1)