![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/manual.txt b/manual.txt
index 7df984604bb8afe0464ab1d66b0ae37b316ff611..c9b18932fd98705bff238aa1af9b897094f6a16d 100644 (file)
--- a/manual.txt
+++ b/manual.txt
+ifndef::doctype-manpage[]
The tig Manual
==============
Jonas Fonseca <fonseca@diku.dk>
+endif::doctype-manpage[]
This is the manual for tig, the ncurses-based text-mode interface for git.
Tig allows you to browse changes in a git repository and can additionally act
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 view a commit and show both author and committer
The blame view::
Displays the file content annotated or blamed by commits.
+The branch view::
+ Displays the branches in the repository.
+
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.
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.
-------------------------------------------------------------------------------
+.Browsing state variables
+[frame="none",grid="none",cols="25<m,75<"]
+|=============================================================================
+|%(head) |The currently viewed 'head' ID. Defaults to HEAD
+|%(commit) |The currently selected commit ID.
+|%(blob) |The currently selected blob ID.
+|%(branch) |The currently selected branch name.
+|%(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.
+|%(revargs) |The revision arguments passed on the command line.
+|%(fileargs) |The file arguments passed on the command line.
+|%(diffargs) |The diff options passed on the command line.
+|=============================================================================
[[title-window]]
Title Windows
--
-[[history-commands]]
-History Commands
-~~~~~~~~~~~~~~~~
+[[diff-options]]
+Diff options
+~~~~~~~~~~~~
-It is possible to alter which commands are used for the different views. If
-for example you prefer commits in the main view to be sorted by date and only
-show 500 commits, use:
+It is possible to alter how diffs are shown by the diff view. If for example
+you prefer to have commit and author dates shown as relative dates, use:
-----------------------------------------------------------------------------
-$ TIG_MAIN_CMD="git log --date-order -n500 --pretty=raw %(head)" tig
+$ TIG_DIFF_OPTS="--relative-date" tig
-----------------------------------------------------------------------------
Or set the variable permanently in your environment.
-Notice, how `%(head)` is used to specify the commit reference.
-
---
-
-TIG_DIFF_CMD::
-
- The command used for the diff view. Defaults to:
------------------------------------------------------------------------------
-git show --pretty=fuller --no-color --root
- --patch-with-stat --find-copies-harder -C %(commit)
------------------------------------------------------------------------------
-
-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. Defaults to:
------------------------------------------------------------------------------
-git log --no-color --cc --stat -n100 %(head)
------------------------------------------------------------------------------
-
-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
- read that format.
------------------------------------------------------------------------------
-git log --no-color --pretty=raw --parents --topo-order %(head)
------------------------------------------------------------------------------
-
---
-
-[[tree-commands]]
-Tree Commands
-~~~~~~~~~~~~~
-
---
-
-TIG_TREE_CMD::
-
- The command used for the tree view. Defaults to:
------------------------------------------------------------------------------
-git ls-tree %(commit) %(directory)
------------------------------------------------------------------------------
-
-TIG_BLOB_CMD::
-
- The command used for the blob view. Defaults to:
------------------------------------------------------------------------------
-git cat-file blob %(blob)
------------------------------------------------------------------------------
-
---
-
[[keys]]
Default Keybindings
-------------------
View Switching
~~~~~~~~~~~~~~
-`-------`--------------------------------------------------------------------
-Key Action
------------------------------------------------------------------------------
-m Switch to main view.
-d Switch to diff view.
-l Switch to log view.
-p Switch to pager view.
-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
------------------------------------------------------------------------------
+[frame="none",grid="none",cols="2<,8<",options="header"]
+|=============================================================================
+|Key |Action
+|m |Switch to main view.
+|d |Switch to diff view.
+|l |Switch to log view.
+|p |Switch to pager view.
+|t |Switch to (directory) tree view.
+|f |Switch to (file) blob view.
+|B |Switch to blame view.
+|H |Switch to branch view.
+|h |Switch to help view
+|S |Switch to status view
+|c |Switch to stage view
+|=============================================================================
[[view-manipulation]]
View Manipulation
~~~~~~~~~~~~~~~~~
-`-------`--------------------------------------------------------------------
-Key Action
------------------------------------------------------------------------------
-q Close view, if multiple views are open it will jump back to the \
- previous view in the view stack. If it is the last open view it \
+[frame="none",grid="none",cols="2<,8<",options="header"]
+|=============================================================================
+|Key |Action
+|q |Close view, if multiple views are open it will jump back to the
+ previous view in the view stack. If it is the last open view it
will quit. Use 'Q' to quit all views at once.
-Enter This key is "context sensitive" depending on what view you are \
- currently in. When in log view on a commit line or in the main \
- view, split the view and show the commit diff. In the diff view \
+|Enter |This key is "context sensitive" depending on what view you are
+ currently in. When in log view on a commit line or in the main
+ 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, 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 \
+|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, 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.
-Down Similar to 'Up' but will move down.
-',' Move to parent. In the tree view, this means switch to the parent \
- directory. In the blame view it will load blame for the parent \
+|Down |Similar to 'Up' but will move down.
+|, |Move to parent. In the tree view, this means switch to the parent
+ directory. In the blame view it will load blame for the parent
commit. For merges the parent is queried.
------------------------------------------------------------------------------
+|=============================================================================
-[[view-manipulation]]
+[[view-actions]]
View Specific Actions
~~~~~~~~~~~~~~~~~~~~~
-`-------`--------------------------------------------------------------------
-Key Action
------------------------------------------------------------------------------
-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.
------------------------------------------------------------------------------
+[frame="none",grid="none",cols="2<,8<",options="header"]
+|=============================================================================
+|Key |Action
+|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.
+|=============================================================================
[[cursor-nav]]
Cursor Navigation
~~~~~~~~~~~~~~~~~
-`-------`--------------------------------------------------------------------
-Key Action
------------------------------------------------------------------------------
-j Move cursor one line up.
-k Move cursor one line down.
-PgUp,\
--,a Move cursor one page up.
-PgDown Space Move cursor one page down.
-Home Jump to first line.
-End Jump to last line.
------------------------------------------------------------------------------
+[frame="none",grid="none",cols="2<,8<",options="header"]
+|=============================================================================
+|Key |Action
+|k |Move cursor one line up.
+|j |Move cursor one line down.
+|PgUp,-,a |Move cursor one page up.
+|PgDown, Space |Move cursor one page down.
+|End |Jump to last line.
+|Home |Jump to first line.
+|=============================================================================
[[view-scrolling]]
Scrolling
~~~~~~~~~
-`-------`--------------------------------------------------------------------
-Key Action
------------------------------------------------------------------------------
-Insert Scroll view one line up.
-Delete Scroll view one line down.
-w Scroll view one page up.
-s Scroll view one page down.
------------------------------------------------------------------------------
+[frame="none",grid="none",cols="2<,8<",options="header"]
+|=============================================================================
+|Key |Action
+|Insert |Scroll view one line up.
+|Delete |Scroll view one line down.
+|w |Scroll view one page up.
+|s |Scroll view one page down.
+|Left |Scroll view one column left.
+|Right |Scroll view one column right.
+|\| |Scroll view to the first column.
+|=============================================================================
[[searching]]
Searching
~~~~~~~~~
-`-------`--------------------------------------------------------------------
-Key Action
------------------------------------------------------------------------------
-/ Search the view. Opens a prompt for entering search regex to use.
-? Search backwards in the view. Also prompts for regex.
-n Find next match for the current search regex.
-N Find previous match for the current search regex.
------------------------------------------------------------------------------
+[frame="none",grid="none",cols="2<,8<",options="header"]
+|=============================================================================
+|Key |Action
+|/ |Search the view. Opens a prompt for entering search regexp to use.
+|? |Search backwards in the view. Also prompts for regexp.
+|n |Find next match for the current search regexp.
+|N |Find previous match for the current search regexp.
+|=============================================================================
[[misc-keys]]
Misc
~~~~
-`-------`--------------------------------------------------------------------
-Key Action
------------------------------------------------------------------------------
-Q Quit.
-r Redraw screen.
-z Stop all background loading. This can be useful if you use \
- tig in a repository with a long history without limiting \
- the revision log.
-v Show version.
-'.' 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`
-e Open file in editor.
------------------------------------------------------------------------------
+[frame="none",grid="none",cols="2<,8<",options="header"]
+|=============================================================================
+|Key |Action
+|Q |Quit.
+|r |Redraw screen.
+|z |Stop all background loading. This can be useful if you use
+ tig in a repository with a long history without limiting
+ the revision log.
+|v |Show version.
+|o |Open option menu
+|. |Toggle line numbers on/off.
+|D |Toggle date display on/off/short/relative/local.
+|A |Toggle author display on/off/abbreviated.
+|g |Toggle revision graph visualization on/off.
+|~ |Toggle (line) graphics mode
+|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`. You can also use this to jump
+ to a specific line by typing `:<linenumber>`, e.g. `:80`.
+|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:
+the following built-in external commands:
-`-------`--------------------------------------------------------------------
-Key Action
------------------------------------------------------------------------------
-C git cherry-pick %(commit)
-G git gc
------------------------------------------------------------------------------
+[frame="none",grid="none",cols="1<,1<,8<",options="header"]
+|=============================================================================
+|Keymap |Key |Action
+|main |C |git cherry-pick %(commit)
+|status |C |git commit
+|generic|G |git gc
+|=============================================================================
[[refspec]]
Revision Specification
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 section on <<history-commands, history commands>>.
+in this section. For example, by configuring the environment variable
+described in the section on <<diff-options, diff options>>.
[[path-limiting]]
Limit by Path Name
-----------------------------------------------------------------------------
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
+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:
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:
-----------------------------------------------------------------------------
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
Copyright
---------
-Copyright (c) 2006-2009 Jonas Fonseca <fonseca@diku.dk>
+Copyright (c) 2006-2010 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
Online resources:
include::SITES[]
-
-Other git repository browsers:
-
- - gitk(1)
- - qgit(1)
- - gitview(1)