X-Git-Url: https://git.distorted.org.uk/~mdw/tig/blobdiff_plain/2bc4f7bd461405083a225b7d43b1ddc947670259..8a6809884863eb60c9c0f8727ff77722d6b85414:/manual.txt diff --git a/manual.txt b/manual.txt index 5d811ca..4e8b402 100644 --- a/manual.txt +++ b/manual.txt @@ -47,11 +47,11 @@ 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 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 <> section below for an introduction @@ -65,6 +65,21 @@ 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 ~~~~~~~~~~~~~~~~~~~~~ @@ -120,6 +135,19 @@ TIG_MAIN_CMD:: the option: `--pretty=raw` since the main view parser expects to read that format. +[[tree-commands]] +Tree Commands +~~~~~~~~~~~~~ + +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 "git ls-tree %s %s". + +TIG_BLOB_CMD:: + The command used for the blob view. Takes one argument which is + the blob ID. Defaults to "git cat-file blob %s". + [[viewer]] The Viewer ---------- @@ -144,7 +172,7 @@ 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 +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. @@ -173,6 +201,26 @@ The diff view:: 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. @@ -200,100 +248,141 @@ be appended: ----------------------------------------------------------------------------- [[keys]] -Keys ----- +Default Keybindings +------------------- Below the default key bindings are shown. [[view-switching]] View Switching ~~~~~~~~~~~~~~ -m:: - Switch to main view. -d:: - Switch to diff view. -l:: - Switch to log view. -p:: - Switch to pager view. -h, ?:: - Show man page. + +`-------`-------------------------------------------------------------------- +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 +----------------------------------------------------------------------------- [[view-manipulation]] View Manipulation ~~~~~~~~~~~~~~~~~ -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 + +`-------`-------------------------------------------------------------------- +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. -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 - (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. +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. +Down Similar to 'Up' but will move down. +----------------------------------------------------------------------------- [[cursor-nav]] Cursor Navigation ~~~~~~~~~~~~~~~~~ -j:: - Move cursor one line up. -k:: - Move cursor one line down. -PgUp:: -b:: --:: - Move cursor one page up. -PgDown:: -Space:: - Move cursor one page down. -Home:: - Jump to first line. -End:: - Jump to last line. + +`-------`-------------------------------------------------------------------- +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. +----------------------------------------------------------------------------- [[view-scrolling]] Scrolling ~~~~~~~~~ -Insert:: - Scroll view one line up. -Delete:: - Scroll view one line down. -w:: - Scroll view one page up. -s:: - Scroll view one page down. + +`-------`-------------------------------------------------------------------- +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. +----------------------------------------------------------------------------- + +[[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. +----------------------------------------------------------------------------- [[misc-keys]] Misc ~~~~ -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 + +`-------`-------------------------------------------------------------------- +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. -n:: - Toggle line numbers on/off. -g:: - Toggle revision graph visualization on/off. -':':: - Open prompt. This allows you to specify what git command - to run. Example: - - :log -p +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` +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 ). 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). +',' Move tree view to the parent tree. +e Open file in editor. +----------------------------------------------------------------------------- + +[[external-commands]] +External Commands +~~~~~~~~~~~~~~~~~ + +Tig also comes with a few builtin external commands. These are simple shell +commands that are run and can take arguments from the current browsing state, +such as the current commit ID. The default commands are: + +`-------`-------------------------------------------------------------------- +Key Action +----------------------------------------------------------------------------- +C git cherry-pick %(commit) +G git gc +----------------------------------------------------------------------------- [[refspec]] Revision Specification @@ -301,7 +390,7 @@ Revision Specification 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). @@ -317,16 +406,16 @@ If you are interested only in those revisions that made changes to a specific 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 @@ -345,7 +434,7 @@ 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 @@ -359,7 +448,7 @@ Alternatively, commits can be limited to a specific range, such as "all 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 @@ -367,7 +456,7 @@ haven't been pushed to a remote branch. Assuming 'origin' is your upstream remote branch, using: ----------------------------------------------------------------------------- -$ tig log origin..HEAD +$ tig origin..HEAD ----------------------------------------------------------------------------- will list what will be pushed to the remote branch. Optionally, the ending @@ -386,7 +475,7 @@ If you prefer to specify which commit to preview in this way use the 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 @@ -401,7 +490,7 @@ say "show at most 20 commits from within the last month that changed files under the Documentation/ directory." ----------------------------------------------------------------------------- -$ tig -- --since=1.month -n20 -- Documentation/ +$ tig --since=1.month -n20 -- Documentation/ ----------------------------------------------------------------------------- [[refspec-all]] @@ -414,7 +503,7 @@ repository change a particular file within the last week". This can be accomplished using: ----------------------------------------------------------------------------- -$ tig -- --all --since=1.week -- Makefile +$ tig --all --since=1.week -- Makefile ----------------------------------------------------------------------------- include::BUGS[] @@ -423,7 +512,7 @@ include::BUGS[] Copyright --------- -Copyright (c) 2006 Jonas Fonseca +Copyright (c) 2006-2007 Jonas Fonseca 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 @@ -443,11 +532,6 @@ 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)