From 2bc4f7bd461405083a225b7d43b1ddc947670259 Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Wed, 14 Jun 2006 22:28:10 +0200 Subject: [PATCH] Documentation update Brings tigrc(5) into sync. A small fix in INSTALL. --- INSTALL | 2 +- asciidoc.conf | 2 +- manual.txt | 2 + tigrc.5.txt | 359 +++++++++++++++++++++++++++++++++++++++++--------- 4 files changed, 298 insertions(+), 67 deletions(-) diff --git a/INSTALL b/INSTALL index c0ba999..dac48a4 100644 --- a/INSTALL +++ b/INSTALL @@ -21,7 +21,7 @@ Tool Description ------------------------------------------------------------------------------- git-core Tig is just a frontend for git. ncurses Be sure to also have development files \ - installed. Usually they are available in a + installed. Usually they are available in a \ separate package ending with `-dev`. asciidoc (>= 7.0), xmlto For building documentation. (Optional) ------------------------------------------------------------------------------- diff --git a/asciidoc.conf b/asciidoc.conf index a23a8f4..ed87a26 100644 --- a/asciidoc.conf +++ b/asciidoc.conf @@ -24,7 +24,7 @@ endif::backend-xhtml11[] ifdef::readme[] # No header or footers for README.html [header] -
+

{doctitle}

[footer] diff --git a/manual.txt b/manual.txt index 637b85c..5d811ca 100644 --- a/manual.txt +++ b/manual.txt @@ -12,6 +12,8 @@ the user with various views, such as summarized commit log and showing the commit with the log message, diffstat, and the diff. ifndef::backend-docbook[] +*Table of Contents* + include::manual.toc[] endif::backend-docbook[] diff --git a/tigrc.5.txt b/tigrc.5.txt index 522dad4..f278193 100644 --- a/tigrc.5.txt +++ b/tigrc.5.txt @@ -5,118 +5,347 @@ NAME ---- 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. -Color options -------------- +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. -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: -[verse] -.......................................................................... - *color* 'area' 'fgcolor' 'bgcolor' '[attributes]' -.......................................................................... +Set command +----------- -Valid colors include: *white*, *black*, *green*, *magenta*, *blue*, *cyan*, -*yellow*, *red*, *default*. Use *default* to refer to the default terminal -colors. +A few selective variables can be configured via the set command. The syntax +is: -Valid attributes include: *normal*, *blink*, *bold*, *dim*, *reverse*, *standout*, -and *underline*. Note, not all attributes may be supported by the terminal. +[verse] +.............................................................................. + *set* variables *=* value +.............................................................................. -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. +Examples: -Diff markup -~~~~~~~~~~~ +-------------------------------------------------------------------------- + set show-rev-graph = yes # Show revision graph? + set line-number-interval = 5 # Interval between line numbers + set tab-size = 8 # Number of spaces pr tab + set encoding = "UTF-8" # Commit encoding +-------------------------------------------------------------------------- -Options concerning diff start, chunks and lines added and deleted. +The type of variables are either bool, int, and string. -*diff-header*, *diff-chunk*, *diff-add*, *diff-del* +Valid bool values:: -Enhanced git diff markup -~~~~~~~~~~~~~~~~~~~~~~~~ + To set a bool variable to true use either "1", "true", or "yes". + Any other value will set the variable to false. -Extra diff information emitted by the git diff machinery, such as mode -changes, rename detection, and similarity. +Valid int values:: -*diff-oldmode*, *diff-newmode*, *diff-copy-from*, *diff-copy-to*, -*diff-rename-from*, *diff-rename-to*, *diff-similarity* *diff-dissimilarity* -*diff-tree*, *diff-index* + A non-negative integer. -Pretty print commit headers -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Valid string values:: -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. + A string of characters. Optionally, use either ' or " as delimiters. -*pp-author*, *pp-commit*, *pp-merge*, *pp-date*, *pp-adate*, *pp-cdate* +Variables +~~~~~~~~~ -Raw commit header -~~~~~~~~~~~~~~~~~ +The following variables can be set: -Usually shown when `--pretty=raw` is given, however 'commit' is pretty -much omnipresent. +'show-rev-graph' (bool):: -*commit*, *parent*, *tree*, *author*, *committer* + Show revision graph in the main view on startup. Can be toggled with + 'g'. -Commit message -~~~~~~~~~~~~~~ +'line-number-interval' (int):: -For now only `Signed-off-by lines` are colorized. + 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. -*signoff* +'tab-size' (int):: -UI colors -~~~~~~~~~ + Number of spaces per tab. The default is 8 spaces. -Colors for text not matching any of the above: *default* +'commit-encoding' (string):: -Status window colors: *status* + The encoding used for commits. The default is UTF-8. Not this option + is shadowed by the "i18n.commitencoding" option in `.git/config`. -Title window colors: *title-blur*, *title-focus* -Cursor line colors: *cursor* +Bind command +------------ -Main view specific: *main-date*, *main-author*, *main-commit*, *main-delim*, -*main-tag*, *main-ref* +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 +-------------------------------------------------------------------------- + +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 shaddow the generic keybindings which shaddow the +built-in keybindings. + +-- + +Keymaps:: + +Valid keymaps are: *main*, *diff*, *log*, *help*, *pager*, 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 +~~~~~~~ + +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-help Show help page +view-pager Show pager view +------------------------------------------------------------------------------ + +ifdef::backend-xhtml11[] +[frame="none"] +`-----------------------`----------------------------------------------------- +endif::backend-xhtml11[] +View manipulation:: +------------------------------------------------------------------------------ +enter Enter current line and scroll +next Move to next +previous Move to previous +view-next Move focus to next view +view-close Close the current view +quit Close all views and quit +------------------------------------------------------------------------------ + +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_up Scroll one page up +scroll-page_down Scroll one page down +------------------------------------------------------------------------------ + +ifdef::backend-xhtml11[] +[frame="none"] +`-----------------------`----------------------------------------------------- +endif::backend-xhtml11[] +Misc:: +------------------------------------------------------------------------------ +prompt Bring up the prompt +screen-update Update the screen +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-rev_graph Toggle revision graph visualization +------------------------------------------------------------------------------ + + +Color command +------------- -EXAMPLES --------- +Color commands control highlighting and the user interface styles. If your +terminal supports color, these commands can be used to assign foreground and +backgound combinations to certain areas. Optionally, an attribute can be given +as the last parameter. The syntax is: + +[verse] +.............................................................................. + *color* 'area' 'fgcolor' 'bgcolor' '[attributes]' +.............................................................................. -Some sample options: +Examples: -========================================================================== +------------------------------------------------------------------------------ # 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 -========================================================================== +------------------------------------------------------------------------------ + +Area names:: + + 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. + +Color names:: + + Valid colors include: *white*, *black*, *green*, *magenta*, *blue*, + *cyan*, *yellow*, *red*, *default*. Use *default* to refer to the + default terminal colors. + +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 +~~~~~~~~~ + +-- + +Status window colors:: + +Appearance of the bottom window showing info messages. + +*status* + +Title window colors:: + +Appearence of the title windows when they are attached +to any backgrounded windows and the current window. + +*title-blur*, *title-focus* + +Cursor line colors:: + +*cursor* + +Main view specific:: + +Appearance of the various columns in the main view, including the '~' used for +delimiting long author names and labels for tag and branch references. + +*main-date*, *main-author*, *main-commit*, *main-delim*, *main-tag*, +*main-ref* + +-- + +Highlighting +~~~~~~~~~~~~ + +The colors and attributes for text that is not highlighted can be controlled +by changing the *default* color option. + +-- + +Diff markup:: + +Options concerning diff start, chunks and lines added and deleted. + +*diff-header*, *diff-chunk*, *diff-add*, *diff-del* + +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-tree*, *diff-index* + +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. + +*pp-author*, *pp-commit*, *pp-merge*, *pp-date*, *pp-adate*, *pp-cdate* + +Raw commit header:: + +Usually shown when `--pretty=raw` is given, however 'commit' is pretty much +omnipresent. + +*commit*, *parent*, *tree*, *author*, *committer* + +Commit message:: + +For now only `Signed-off-by` lines are colorized. + +*signoff* + +-- + +COPYRIGHT +--------- +Copyright (c) 2006 Jonas Fonseca + +Licensed under the terms of the GNU General Public License. SEE ALSO -------- -tig(1) +gitlink:tig[1] and the http://jonas.nitro.dk/tig/tig.html[tig manual]. -- 2.32.0.93.g670b81a890