diff --git a/tigrc.5.txt b/tigrc.5.txt
index 522dad409f0403ee72ea0bf5d8ba71c341abf18b..1120a8642b6c817f833db9ef91f258729fdb5b8a 100644 (file)
--- a/tigrc.5.txt
+++ b/tigrc.5.txt
----
tigrc - tig user configuration file
+
SYNOPSIS
--------
[verse]
.............................................................................
-*color* 'fgcolor' 'bgcolor' '[attributes]'
+*set* 'variable' *=* 'value'
+*bind* 'keymap' 'key' 'action'
+*color* 'area' 'fgcolor' 'bgcolor' '[attributes]'
.............................................................................
+
DESCRIPTION
-----------
-You can permanently set an option by putting it in the `~/.tigrc` file.
-The file consists of a series of 'commands'. Each
-line of the file may contain only one command.
-The hash mark ('#'), or semi-colon (';') is used as a 'comment' character.
-All text after the comment character to the end of the line is ignored.
-You can use comments to annotate your initialization file.
+You can permanently set an option by putting it in the `~/.tigrc` file. The
+file consists of a series of 'commands'. Each line of the file may contain
+only one command.
+
+The hash mark ('#') is used as a 'comment' character. All text after the
+comment character to the end of the line is ignored. You can use comments to
+annotate your initialization file.
+
+
+Set command
+-----------
+
+A few selective variables can be configured via the set command. The syntax
+is:
+
+[verse]
+..............................................................................
+*set* variables *=* value
+..............................................................................
+
+Examples:
+
+--------------------------------------------------------------------------
+set show-author = yes # Show author?
+set show-date = yes # Show commit date?
+set show-rev-graph = yes # Show revision graph?
+set show-refs = yes # Show references?
+set show-line-numbers = no # Show line numbers?
+set author-width = 10 # Set width of the author column
+set line-graphics = no # Disable graphics characters
+set line-number-interval = 5 # Interval between line numbers
+set tab-size = 8 # Number of spaces per tab
+set encoding = "UTF-8" # Commit encoding
+--------------------------------------------------------------------------
+
+The type of variables are either bool, int, and string.
+
+Valid bool values::
+
+ To set a bool variable to true use either "1", "true", or "yes".
+ Any other value will set the variable to false.
+
+Valid int values::
+
+ A non-negative integer.
+
+Valid string values::
+
+ A string of characters. Optionally, use either ' or " as delimiters.
+
+Variables
+~~~~~~~~~
+
+The following variables can be set:
+
+'show-author' (bool)::
+'show-date' (bool)::
+'show-rev-graph' (bool)::
+'show-refs' (bool)::
+
+ Whether to show author, date, revision graph, and references
+ (branches, tags, and remotes) in the main view on start-up. Can all be
+ toggled.
+
+'author-width' (int)::
+
+ Width of the author column. When set to 5 or below, the author name
+ will be abbreviated to the author's initials.
+
+'line-graphics' (bool)::
-Color options
+ Whether to use graphic characters for line drawing.
+
+'line-number-interval' (int)::
+
+ Interval between line numbers. Note, you have to toggle on line
+ numbering with 'n' or the `-n` command line option. The default is to
+ number every line.
+
+'tab-size' (int)::
+
+ Number of spaces per tab. The default is 8 spaces.
+
+'commit-encoding' (string)::
+
+ The encoding used for commits. The default is UTF-8. Not this option
+ is shadowed by the "i18n.commitencoding" option in `.git/config`.
+
+
+Bind command
+------------
+
+Using bind commands keys can be mapped to an action when pressed in a given
+key map. The syntax is:
+
+[verse]
+..............................................................................
+*bind* 'keymap' 'key' 'action'
+..............................................................................
+
+Examples:
+
+--------------------------------------------------------------------------
+# A few keybindings
+bind main w scroll-line-up
+bind main s scroll-line-down
+bind main space enter
+bind diff a previous
+bind diff d next
+bind diff b move-first-line
+# 'unbind' the default quit key binding
+bind main Q none
+# An external command to update from upstream
+bind generic F !git fetch
+# Cherry-pick current commit onto current branch
+bind generic C !git cherry-pick %(commit)
+--------------------------------------------------------------------------
+
+Keys are mapped by first searching the keybindings for the current view, then
+the keybindings for the *generic* keymap, and last the default keybindings.
+Thus, the view keybindings shadow the generic keybindings which Shadow the
+built-in keybindings.
+
+--
+
+Keymaps::
+
+Valid keymaps are: *main*, *diff*, *log*, *help*, *pager*, *status*, *stage*,
+and *generic*. Use *generic* to set key mapping in all keymaps.
+
+Key values::
+
+Key values should never be quoted. Use either the ASCII value or one of the
+following symbolic key names. Symbolic key names are case insensitive, Use
+*Hash* to bind to the `#` key, since the hash mark is used as a comment
+character.
+
+*Enter*, *Space*, *Backspace*, *Tab*, *Escape*, *Left*, *Right*, *Up*, *Down*,
+*Insert*, *Delete*, *Hash*, *Home*, *End*, *PageUp*, *PageDown*, *F1*, *F2*, *F3*,
+*F4*, *F5*, *F6*, *F7*, *F8*, *F9*, *F10*, *F11*, *F12*.
+
+Action names::
+
+Valid action names are described below. Note, all names are
+case-insensitive, and you may use '-', '_', and '.' interchangeably,
+e.g. "view-main", "View.Main", and "VIEW_MAIN" are the same.
+
+--
+
+Actions
+~~~~~~~
+
+Apart from the action names listed below, all actions starting with a '!' will
+be available as an external command. External commands can contain variable
+names that will be substituted before the command is run. Valid variable names
+are:
+
+ifdef::backend-xhtml11[]
+[frame="none"]
+`-----------------------`-----------------------------------------------------
+endif::backend-xhtml11[]
+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.
+------------------------------------------------------------------------------
+
+As an example, the following external command will save the current commit as
+a patch file: "!git format-patch -1 %(commit)".
+
+ifdef::backend-xhtml11[]
+[frame="none"]
+`-----------------------`-----------------------------------------------------
+endif::backend-xhtml11[]
+View switching:
+------------------------------------------------------------------------------
+view-main Show main view
+view-diff Show diff view
+view-log Show log view
+view-tree Show tree view
+view-blob Show blob view
+view-blame Show blame view
+view-status Show status view
+view-stage Show stage view
+view-pager Show pager view
+view-help Show help page
+------------------------------------------------------------------------------
+
+ifdef::backend-xhtml11[]
+[frame="none"]
+`-----------------------`-----------------------------------------------------
+endif::backend-xhtml11[]
+View manipulation:
+------------------------------------------------------------------------------
+enter Enter current line and scroll
+next Move to next
+previous Move to previous
+parent Move to parent
+view-next Move focus to next view
+refresh Reload and refresh view
+maximize Maximize the current view
+view-close Close the current view
+quit Close all views and quit
+------------------------------------------------------------------------------
+
+ifdef::backend-xhtml11[]
+[frame="none"]
+`-----------------------`-----------------------------------------------------
+endif::backend-xhtml11[]
+View specific actions:
+------------------------------------------------------------------------------
+status-update Update file status
+status-merge Resolve unmerged file
+stage-next Find next chunk to stage
+------------------------------------------------------------------------------
+
+ifdef::backend-xhtml11[]
+[frame="none"]
+`-----------------------`-----------------------------------------------------
+endif::backend-xhtml11[]
+Cursor navigation:
+------------------------------------------------------------------------------
+move-up Move cursor one line up
+move-down Move cursor one line down
+move-page-down Move cursor one page down
+move-page-up Move cursor one page up
+move-first-line Move cursor to first line
+move-last-line Move cursor to last line
+------------------------------------------------------------------------------
+
+ifdef::backend-xhtml11[]
+[frame="none"]
+`-----------------------`-----------------------------------------------------
+endif::backend-xhtml11[]
+Scrolling:
+------------------------------------------------------------------------------
+scroll-line-up Scroll one line up
+scroll-line-down Scroll one line down
+scroll-page-eup Scroll one page up
+scroll-page-down Scroll one page down
+------------------------------------------------------------------------------
+
+ifdef::backend-xhtml11[]
+[frame="none"]
+`-----------------------`-----------------------------------------------------
+endif::backend-xhtml11[]
+Searching:
+------------------------------------------------------------------------------
+search Search the view
+search-back Search backwards in the view
+find-next Find next search match
+find-prev Find previous search match
+------------------------------------------------------------------------------
+
+ifdef::backend-xhtml11[]
+[frame="none"]
+`-----------------------`-----------------------------------------------------
+endif::backend-xhtml11[]
+Misc:
+------------------------------------------------------------------------------
+prompt Bring up the prompt
+screen-redraw Redraw the screen
+screen-resize Resize the screen
+show-version Show version information
+stop-loading Stop all loading views
+toggle-lineno Toggle line numbers
+toggle-date Toggle date display
+toggle-author Toggle author display
+toggle-rev-graph Toggle revision graph visualization
+toggle-refs Toggle reference display
+edit Open in editor
+none Do nothing
+------------------------------------------------------------------------------
+
+
+Color command
-------------
-Color options control highlighting and the user interface styles.
-If your terminal supports color, these commands can be used to assign
-foreground/backgound combinations to certain areas. Optionally, an
-attribute can be given as the last parameter. The syntax is:
+Color commands control highlighting and the user interface styles. If your
+terminal supports color, these commands can be used to assign foreground and
+background combinations to certain areas. Optionally, an attribute can be
+given as the last parameter. The syntax is:
[verse]
-..........................................................................
- *color* 'area' 'fgcolor' 'bgcolor' '[attributes]'
-..........................................................................
+..............................................................................
+*color* 'area' 'fgcolor' 'bgcolor' '[attributes]'
+..............................................................................
+
+Examples:
+
+------------------------------------------------------------------------------
+# Overwrite the default terminal colors to white on black.
+color default white black
+# Diff colors
+color diff-header yellow default
+color diff-index blue default
+color diff-chunk magenta default
+# A strange looking cursor line
+color cursor red default underline
+# UI colors
+color title-blur white blue
+color title-focus white blue bold
+------------------------------------------------------------------------------
-Valid colors include: *white*, *black*, *green*, *magenta*, *blue*, *cyan*,
-*yellow*, *red*, *default*. Use *default* to refer to the default terminal
-colors.
+Area names::
-Valid attributes include: *normal*, *blink*, *bold*, *dim*, *reverse*, *standout*,
-and *underline*. Note, not all attributes may be supported by the terminal.
+ Valid area names are described below. Note, all names are
+ case-insensitive, and you may use '-', '_', and '.' interchangeably,
+ e.g. "Diff-Header", "DIFF_HEADER", and "diff.header" are the same.
-Valid area names are described below. Note, all names are case-insensitive,
-and you may use '-', '_', and '.' interchangeably. So "Diff-Header",
-"DIFF_HEADER", and "diff.header" are the same.
+Color names::
-Diff markup
-~~~~~~~~~~~
+ Valid colors include: *white*, *black*, *green*, *magenta*, *blue*,
+ *cyan*, *yellow*, *red*, *default*. Use *default* to refer to the
+ default terminal colors. This is recommended for background colors
+ if you are using a terminal with a transparent background.
+
+Attribute names::
+
+ Valid attributes include: *normal*, *blink*, *bold*, *dim*, *reverse*,
+ *standout*, and *underline*. Note, not all attributes may be supported
+ by the terminal.
+
+UI colors
+~~~~~~~~~
+
+The colors and attributes to be used for the text that is not highlighted or
+that specify the use of the default terminal colors can be controlled by
+setting the *default* color option.
+
+ifdef::backend-xhtml11[]
+[frame="none"]
+`-----------------------`-----------------------------------------------------
+endif::backend-xhtml11[]
+General:
+------------------------------------------------------------------------------
+default Overwrite default terminal colors (see above).
+cursor The cursor line.
+status The status window showing info messages.
+title-focus The title window for the current view.
+title-blur The title window of any backgrounded view.
+delimiter Delimiter shown for truncated lines.
+line-number Line numbers.
+date The commit date.
+------------------------------------------------------------------------------
+
+ifdef::backend-xhtml11[]
+[frame="none"]
+`-----------------------`-----------------------------------------------------
+endif::backend-xhtml11[]
+Main view colors:
+------------------------------------------------------------------------------
+main-author The commit author.
+main-revgraph The revision graph.
+main-commit The commit comment.
+main-head Label of the current branch.
+main-remote Label of a remote.
+main-tracked Label of the remote tracked by the current branch.
+main-tag Label of a signed tag.
+main-local-tag Label of a local tag.
+main-ref Label of any other reference.
+------------------------------------------------------------------------------
+
+ifdef::backend-xhtml11[]
+[frame="none"]
+`-----------------------`-----------------------------------------------------
+endif::backend-xhtml11[]
+Status view:
+------------------------------------------------------------------------------
+stat-head The "On branch"-line.
+stat-section Status section titles,
+stat-staged Status flag of staged files.
+stat-unstaged Status flag of unstaged files.
+stat-untracked Status flag of untracked files.
+------------------------------------------------------------------------------
+
+ifdef::backend-xhtml11[]
+[frame="none"]
+`-----------------------`-----------------------------------------------------
+endif::backend-xhtml11[]
+Blame view:
+------------------------------------------------------------------------------
+blame-id The commit ID.
+------------------------------------------------------------------------------
+
+Highlighting
+~~~~~~~~~~~~
+
+--
+
+Diff markup::
Options concerning diff start, chunks and lines added and deleted.
*diff-header*, *diff-chunk*, *diff-add*, *diff-del*
-Enhanced git diff markup
-~~~~~~~~~~~~~~~~~~~~~~~~
+Enhanced git diff markup::
Extra diff information emitted by the git diff machinery, such as mode
changes, rename detection, and similarity.
*diff-oldmode*, *diff-newmode*, *diff-copy-from*, *diff-copy-to*,
-*diff-rename-from*, *diff-rename-to*, *diff-similarity* *diff-dissimilarity*
+*diff-rename-from*, *diff-rename-to*, *diff-similarity*, *diff-dissimilarity*
*diff-tree*, *diff-index*
-Pretty print commit headers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Pretty print commit headers::
-Commit diffs and the revision logs are usually formatted using pretty
-printed headers , unless `--pretty=raw` was given. This includes lines,
-such as merge info, commit ID, and author and comitter date.
+Commit diffs and the revision logs are usually formatted using pretty printed
+headers , unless `--pretty=raw` was given. This includes lines, such as merge
+info, commit ID, and author and committer date.
-*pp-author*, *pp-commit*, *pp-merge*, *pp-date*, *pp-adate*, *pp-cdate*
+*pp-author*, *pp-commit*, *pp-merge*, *pp-date*, *pp-adate*, *pp-cdate*,
+*pp-refs*
-Raw commit header
-~~~~~~~~~~~~~~~~~
+Raw commit header::
-Usually shown when `--pretty=raw` is given, however 'commit' is pretty
-much omnipresent.
+Usually shown when `--pretty=raw` is given, however 'commit' is pretty much
+omnipresent.
*commit*, *parent*, *tree*, *author*, *committer*
-Commit message
-~~~~~~~~~~~~~~
+Commit message::
-For now only `Signed-off-by lines` are colorized.
+For now only `Signed-off-by` and `Acked-by` lines are colorized.
-*signoff*
+*signoff*, *acked*
-UI colors
-~~~~~~~~~
-
-Colors for text not matching any of the above: *default*
-
-Status window colors: *status*
+Tree markup::
-Title window colors: *title-blur*, *title-focus*
+Colors for information of the tree view.
-Cursor line colors: *cursor*
+*tree-dir*, *tree-file*
-Main view specific: *main-date*, *main-author*, *main-commit*, *main-delim*,
-*main-tag*, *main-ref*
-
-
-EXAMPLES
---------
+--
-Some sample options:
+COPYRIGHT
+---------
+Copyright (c) 2006-2009 Jonas Fonseca <fonseca@diku.dk>
-==========================================================================
- # Diff colors
- color diff-header yellow default
- color diff-index blue default
- color diff-chunk magenta default
- # UI colors
- color title-blur white blue
- color title-focus white blue bold
-==========================================================================
+Licensed under the terms of the GNU General Public License.
SEE ALSO
--------
-tig(1)
+manpage:tig[1] and the http://jonas.nitro.dk/tig/manual.html[tig manual].