X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=tigrc.5.txt;h=247afdf901299a8c1ba078a1c577ffccdf9d6b96;hb=914710a2bf5947fabefe24da086b0e680277a8fd;hp=522dad409f0403ee72ea0bf5d8ba71c341abf18b;hpb=cb7f42cdc1a07d0f88b8af211d214da5febd6223;p=tig.git diff --git a/tigrc.5.txt b/tigrc.5.txt index 522dad4..247afdf 100644 --- a/tigrc.5.txt +++ b/tigrc.5.txt @@ -3,120 +3,538 @@ tigrc(5) NAME ---- -tigrc - tig user configuration file +tigrc - tig 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. + +Alternatively, options can be set by putting them in one of the git +configuration files, which are read by tig on startup. See 'git-config(1)' for +which files to use. + +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-rev-graph = yes # Show revision graph? +set show-refs = yes # Show references? +set show-line-numbers = no # Show line numbers? +set line-number-interval = 5 # Interval between line numbers +set commit-encoding = "UTF-8" # Commit encoding +set horizontal-scroll = 33% # Scroll 33% of the view width +-------------------------------------------------------------------------- + +Or in the git configuration files: + +-------------------------------------------------------------------------- +[tig] + show-date = yes # Show commit date? + author-width = 10 # Set width of the author column + line-graphics = no # Disable graphics characters + tab-size = 8 # Number of spaces per tab +-------------------------------------------------------------------------- + +The type of variables are either bool, int, string, or mixed. + +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. + +Valid mixed values:: + + These values are composites of the above types. The valid values are + specified in the description. + +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. -Color options +'line-graphics' (bool):: + + 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. + +'horizontal-scroll' (mixed):: + + Interval to scroll horizontally in each step. Can be specified either + as the number of columns, e.g. '5', or as a percentage of the view + width, e.g. '33%', where the maximum is 100%. For percentages it is + always ensured that at least one column is scrolled. The default is to + scroll '50%' of the view width. + +'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 +# An external command to update from upstream +bind generic F !git fetch +-------------------------------------------------------------------------- + +Or in the git configuration files: + +-------------------------------------------------------------------------- +[tig "bind"] + # 'unbind' the default quit key binding + main = Q none + # Cherry-pick current commit onto current branch + 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*, +*tree*, *blob*, *blame*, *branch*, 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)". If your external command +require use of dynamic features, such as subshells, expansion of environment +variables and process control, this can be achieved by using a combination of +git aliases and tig external commands. The following example entries can be +put in either the .gitconfig or .git/config file: + +-------------------------------------------------------------------------- +[alias] + gitk-bg = !"gitk HEAD --not $(git rev-parse --remotes) &" + publish = !"for i in origin public; do git push $i; done" +[tig "bind"] + generic = V !git gitk-bg + generic = > !git publish +-------------------------------------------------------------------------- + +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-branch Show branch 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-up Scroll one page up +scroll-page-down Scroll one page down +scroll-left Scroll one column left +scroll-right Scroll one column right +------------------------------------------------------------------------------ + +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 +-------------------------------------------------------------------------- + +Or in the git configuration files: + +-------------------------------------------------------------------------- +[tig "color"] + # A strange looking cursor line + cursor red default underline + # UI colors + title-blur white blue + 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. ++ +Colors can also be specified using the keywords color0, color1, ..., colorN-1 +(N being the number of colors supported by your terminal). This is useful when +you remap the colors for your display or want to enable colors supported by +256-color terminals. + +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. +author The commit author. +mode The file mode holding the permissions and type. +------------------------------------------------------------------------------ + +ifdef::backend-xhtml11[] +[frame="none"] +`-----------------------`----------------------------------------------------- +endif::backend-xhtml11[] +Main view colors: +------------------------------------------------------------------------------ +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. +------------------------------------------------------------------------------ + +ifdef::backend-xhtml11[] +[frame="none"] +`-----------------------`----------------------------------------------------- +endif::backend-xhtml11[] +Tree view: +------------------------------------------------------------------------------ +tree-head The "Directory /"-line +tree-dir The directory name. +tree-file The file name. +------------------------------------------------------------------------------ + +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 -~~~~~~~~~~~~~~ - -For now only `Signed-off-by lines` are colorized. +Commit message:: -*signoff* +For now only `Signed-off-by` and `Acked-by` lines are colorized. -UI colors -~~~~~~~~~ +*signoff*, *acked* -Colors for text not matching any of the above: *default* +Tree markup:: -Status window colors: *status* +Colors for information of the tree view. -Title window colors: *title-blur*, *title-focus* +*tree-dir*, *tree-file* -Cursor line colors: *cursor* +-- -Main view specific: *main-date*, *main-author*, *main-commit*, *main-delim*, -*main-tag*, *main-ref* +COPYRIGHT +--------- +Copyright (c) 2006-2009 Jonas Fonseca - -EXAMPLES --------- - -Some sample options: - -========================================================================== - # 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], git-config(1), +and the http://jonas.nitro.dk/tig/manual.html[tig manual].