GRV - Git Repository Viewer - is a TUI for viewing and modifying Git repositories. The sections below provide an overview of the ways to configure and interact with GRV.
- Command Line Arguments
- Key Bindings
- Configuration Variables
- Configuration Commands
- Shell Commands
- Filter Query Language
GRV accepts the following command line arguments:
-logFile string
Log file path (default "grv.log")
-logLevel string
Logging level [NONE|PANIC|FATAL|ERROR|WARN|INFO|DEBUG|TRACE] (default "NONE")
-readOnly
Run grv in read only mode
-repoFilePath string
Repository file path (default ".")
-version
Print version
-workTreeFilePath string
Work tree file path
The following tables contain default and user configured key bindings
Key Bindings | Action | Description
------------------+----------------------------+----------------------------------------------
z., zz | <grv-center-view> | Center view
L | <grv-cursor-bottom-view> | Move to the last line of the page
M | <grv-cursor-middle-view> | Move to the middle line of the page
H | <grv-cursor-top-view> | Move to the first line of the page
gg | <grv-first-line> | Move to first line
G | <grv-last-line> | Move to last line
<C-d> | <grv-next-half-page> | Move half page down
<Down>, j | <grv-next-line> | Move down one line
<PageDown>, <C-f> | <grv-next-page> | Move one page down
<C-u> | <grv-prev-half-page> | Move half page up
<Up>, k | <grv-prev-line> | Move up one line
<PageUp>, <C-b> | <grv-prev-page> | Move one page up
zb | <grv-scroll-cursor-bottom> | Scroll the screen so cursor is at the bottom
zt | <grv-scroll-cursor-top> | Scroll the screen so cursor is at the top
<Left>, h | <grv-scroll-left> | Scroll left
<Right>, l | <grv-scroll-right> | Scroll right
Key Bindings | Action | Description
-------------+-----------------------------+-------------------------------
None | <grv-clear-search> | Clear search
? | <grv-reverse-search-prompt> | Search backwards
n | <grv-search-find-next> | Move to next search match
N | <grv-search-find-prev> | Move to previous search match
/ | <grv-search-prompt> | Search forwards
Key Bindings | Action | Description
--------------------------+--------------------------+------------------------------------
<C-w>o, <C-w><C-o>, f | <grv-full-screen-view> | Toggle current view full screen
gt | <grv-next-tab> | Move to next tab
<C-w>w, <C-w><C-w>, <Tab> | <grv-next-view> | Move to next view
gT | <grv-prev-tab> | Move to previous tab
<C-w>W, <S-Tab> | <grv-prev-view> | Move to previous view
q | <grv-remove-view> | Close view (or close tab if empty)
<C-w>t | <grv-toggle-view-layout> | Toggle view layout
Key Bindings | Action | Description
-------------+------------------------------+--------------------------------------------------
None | <grv-exit> | Exit GRV
: | <grv-prompt> | GRV Command prompt
None | <grv-remove-tab> | Remove the active tab
<Enter> | <grv-select> | Select item (opens listener view if none exists)
<C-a> | <grv-show-available-actions> | Show available actions for the selected row
None | <grv-show-help> | Show the help view
<C-z> | <grv-suspend> | Suspend GRV
Key Bindings | Action | Description
-------------+----------------------------------+--------------------------------------------
- | <grv-checkout-previous-ref> | Checkout previous ref
c | <grv-checkout-ref> | Checkout ref
T | <grv-create-annotated-tag> | Create a new annotated tag
B | <grv-create-branch-and-checkout> | Create a new branch and checkout
b | <grv-create-branch> | Create a new branch
t | <grv-create-tag> | Create a new tag
D | <grv-delete-ref> | Delete ref
<C-q> | <grv-filter-prompt> | Add filter
m | <grv-merge-ref> | Merge ref into current branch
p | <grv-push-ref> | Push ref to remote
r | <grv-rebase> | Rebase current branch onto selected branch
<C-r> | <grv-remove-filter> | Remove filter
Key Bindings | Action | Description
-------------+----------------------------------+----------------------------------
c | <grv-checkout-commit> | Checkout commit
T | <grv-create-annotated-tag> | Create a new annotated tag
B | <grv-create-branch-and-checkout> | Create a new branch and checkout
b | <grv-create-branch> | Create a new branch
t | <grv-create-tag> | Create a new tag
<C-q> | <grv-filter-prompt> | Add filter
<C-r> | <grv-remove-filter> | Remove filter
Key Bindings | Action | Description
-------------+---------------------------+--------------
A | <grv-action-amend-commit> | Amend commit
C | <grv-action-commit> | Commit
c | <grv-checkout-file> | Checkout
a | <grv-stage-file> | Stage
u | <grv-unstage-file> | Unstage
Key Bindings | Action | Description
-------------------+-------------------+----------------------------
<Right>, l, <Tab> | <grv-next-button> | Select the next button
<Left>, h, <S-Tab> | <grv-prev-button> | Select the previous button
Key Bindings | Action | Description
-------------+-------------------+-------------
p | <grv-pull-remote> | Pull remote
Configuration variables allow features to be enabled, disabled and configured. They are specified using the set command in the grvrc file or at the command prompt
Variable | Type | Default Value | Description
---------------------------+--------+---------------+------------------------------------------------------------------------------
commit-graph | bool | false | Commit graph visible
commit-limit | string | 100000 | Limit the number of commits loaded. Allowed values: number, date, oid or tag
confirm-checkout | bool | true | Confirm before performing git checkout
default-view | string | | Command to generate a custom default view on start up
diff-display | string | fancy | Diff display format
git-binary-file-path | string | | File path to git binary. Required only when git binary is not in $PATH
input-prompt-after-command | bool | true | Display "Press any key to continue" after executing external command
mouse | bool | false | Mouse support enabled
mouse-scroll-rows | int | 3 | Number of rows scrolled for each mouse event
prompt-history-size | int | 1000 | Maximum number of prompt entries retained
tabwidth | int | 8 | Tab character screen width (minimum value: 1)
theme | string | solarized | The currently active theme
The behaviour of GRV can be customised through the use of commands specified in a configuration file GRV will look for the following configuration files on start up:
- $XDG_CONFIG_HOME/grv/grvrc
- $HOME/.config/grv/grvrc
GRV will attempt to process the first file which exists. Commands can also be specified within GRV using the command prompt :
Below are the set of configuration commands supported:
The addtab command creates a new named empty tab and switches to this new tab. The format of the command is:
addtab tabname
For example, to add a new tab titled "mycustomtab" the following command can be used:
addtab mycustomtab
The addview command allows a view to be added to the currently active tab. The form of the command is:
addview view viewargs...
Each view accepts a different set of arguments. This is described in the table below:
View | Args
--------------+------------
CommitView | ref or oid
DiffView | oid
GitStatusView | none
RefView | none
Examples usages for each view are given below:
addview CommitView origin/master
addview DiffView 4882ca9044661b49a26ae03ceb1be3a70d00c6a2
addview GitStatusView
addview RefView
The def command allows a custom GRV command to be defined. It has the form:
def NAME {
BODY
}
where NAME is the name of the new command and BODY is a sequence of commands to execute. For example, to define a command "maintab" to open a new tab containing the CommitView for master:
def maintab {
addtab Main
addview CommitView master
}
This command can be invoked at the command prompt with:
:maintab
The command body can contain argument placeholders that will be substituted on invocation.
Argument placeholders have the form
def maintab {
addtab Main
addview CommitView $1
}
To invoke this command for the branch "feature-branch" and open a new tab containing the commit view for this branch:
:maintab feature-branch
All arguments can be substituted using the placeholder
def vs { vsplit $@ }
and can be invoked with:
:vs CommitView master
Argument placeholders can be escaped by prepending a dollar sign.
For example, to specify the literal string
The evalkeys command executes the provided key string sequence. The format of the command is:
evalkeys keys
For example, running the following will switch to the next tab:
evalkeys <grv-next-tab>
The git command is an alias to the git cli command. It allows a non-interactive git command to run without having to leave GRV. A pop-up window displays the output of the command. For example, to run 'git status' from within GRV use the following key sequence
:git status
Only non-interactive git commands (i.e. those that require no user input) can be run using the git command. For interactive git commands the giti command can be used.
The git command is an alias to the git cli command. It allows an interactive git command (i.e. those that require user input) to be run without having to leave GRV. The command is executed in the controlling terminal and GRV is resumed on command completion. For example, to run 'git rebase -i HEAD~2' use the following key sequence:
:giti rebase -i HEAD~2
The help command opens a tab containing documentation for GRV. A search term can be provided as an argument. For example:
help vsplit
will display the section for the command vsplit in the help tab
The hsplit command creates a horizontal split between the currently selected view and the view specified in the command. The form of the command is:
hsplit view viewargs...
For example, to create a horizontal split between the currently selected view and a RefView:
hsplit RefView
The map command allows a key sequence to be mapped to an action, another key sequence or a shell command for a specified view. The form of the map command is:
map view fromkeys tokeys
For example, to map the key 'a' to the keys 'gg' in the Ref View:
map RefView a gg
When pressing 'a' in the Ref View, the first line would then become the selected line, as 'gg' moves the cursor to the first line. All is a valid view argument when a binding should apply to all views.
GRV also has a text representation of actions that are independent of key bindings. For example, the following commands can be used to make the key move a line down and the key move a line up:
map All <Up> <grv-next-line>
map All <Down> <grv-prev-line>
The map command also allows a key sequence to be mapped directly to a shell command. Prefix a shell command with the '!' character. For example, to map the key 'a' to the shell command 'ls -lh':
map All a !ls -lh
The set of actions available is described in the key binding tables above.
The quit command is used to exit GRV and can be used with the following keys:
:q<Enter>
The rmtab removes the currently active tab. If the tab removed is the last tab then GRV will exit.
The set command allows configuration variables to be set. It has the form:
set variable value
For example, to set the tab width to tab width to 4, the currently active theme to "mytheme" and enable mouse support:
set tabwidth 4
set theme mytheme
set mouse true
GRV currently has the following themes available:
- solarized
- classic
The solarized theme is the default theme for GRV and does not respect the terminals colour palette. The classic theme respects the terminals colour palette.
The sleep command causes grv to pause execution for the provided number of seconds. The format of the command is:
sleep seconds
For example, running the following will pause execution for 0.5 seconds:
sleep 0.5
The split command is similar to the vsplit and hsplit commands. It creates either a new vsplit or hsplit determined by the current dimensions of the active view. The form of the command is:
split view viewargs...
The theme command allows a custom theme to be defined. This theme can then be activated using the theme config variable described above. The form of the theme command is:
theme --name [ThemeName] --component [ComponentId] --bgcolor [BackgroundColor] --fgcolor [ForegroundColor]
- ThemeName: The name of the theme to be created/updated.
- ComponentId: The Id of the screen component (the part of the display to change).
- BackgroundColor: The background color.
- ForegroundColor: The foreground color.
Using a sequence of theme commands it is possible to define a theme. For example, to define a new theme "mytheme" and set it as the active theme:
theme --name mytheme --component CommitView.Date --bgcolor None --fgcolor Red
theme --name mytheme --component RefView.Tag --bgcolor Blue --fgcolor 36
theme --name mytheme --component StatusBarView.Normal --bgcolor None --fgcolor f14a98
set theme mytheme
GRV supports 256 colors (when available). Provided colors will be mapped to the nearest available color. The allowed color values are:
System colors:
None
Black
Red
Green
Yellow
Blue
Magenta
Cyan
White
Terminal Color Numbers:
0 - 255
Hex Colors:
000000 - ffffff
The set of screen components that can be customised is:
All.ActiveViewSelectedRow
All.Default
All.InactiveViewSelectedRow
All.SearchMatch
CommandOutputView.Command
CommandOutputView.Error
CommandOutputView.Footer
CommandOutputView.Normal
CommandOutputView.Success
CommandOutputView.Title
CommitView.Author
CommitView.CommitGraphBranch1
CommitView.CommitGraphBranch2
CommitView.CommitGraphBranch3
CommitView.CommitGraphBranch4
CommitView.CommitGraphBranch5
CommitView.CommitGraphBranch6
CommitView.CommitGraphBranch7
CommitView.CommitGraphCommit
CommitView.CommitGraphMergeCommit
CommitView.Date
CommitView.Footer
CommitView.LocalBranch
CommitView.RemoteBranch
CommitView.ShortOid
CommitView.Summary
CommitView.Tag
CommitView.Title
ContextMenuView.Content
ContextMenuView.Footer
ContextMenuView.KeyMapping
ContextMenuView.Title
DiffView.AddedLine
DiffView.CommitAuthor
DiffView.CommitAuthorDate
DiffView.CommitCommitter
DiffView.CommitCommitterDate
DiffView.CommitMessage
DiffView.FancyEmptyLineAdded
DiffView.FancyEmptyLineRemoved
DiffView.FancyFile
DiffView.FancyLineAdded
DiffView.FancyLineAddedChange
DiffView.FancyLineRemoved
DiffView.FancyLineRemovedChange
DiffView.FancySeparator
DiffView.FancyTrailingWhitespace
DiffView.Footer
DiffView.GitDiffExtendedHeader
DiffView.GitDiffHeader
DiffView.HunkHeader
DiffView.HunkStart
DiffView.Normal
DiffView.RemovedLine
DiffView.StatsFile
DiffView.Title
DiffView.UnifiedDiffHeader
ErrorView.Errors
ErrorView.Footer
ErrorView.Title
GRVVariableView.Footer
GRVVariableView.Title
GRVVariableView.Value
GRVVariableView.Variable
GitStatusView.ConflictedFile
GitStatusView.ConflictedTitle
GitStatusView.Message
GitStatusView.StagedFile
GitStatusView.StagedTitle
GitStatusView.UnstagedFile
GitStatusView.UnstagedTitle
GitStatusView.UntrackedFile
GitStatusView.UntrackedTitle
GitSummaryView.BranchAhead
GitSummaryView.BranchBehind
GitSummaryView.Header
GitSummaryView.NoModifiedFiles
GitSummaryView.Normal
GitSummaryView.StagedFile
GitSummaryView.UnstagedFile
HelpBarView.Normal
HelpBarView.Special
HelpView.Footer
HelpView.IndexSubTitle
HelpView.IndexTitle
HelpView.SectionCodeBlock
HelpView.SectionDescription
HelpView.SectionSubTitle
HelpView.SectionTableCellSeparator
HelpView.SectionTableHeader
HelpView.SectionTableRow
HelpView.SectionTableRowHighlighted
HelpView.SectionTitle
HelpView.Title
MainView.ActiveView
MainView.NormalView
MessageBoxView.Content
MessageBoxView.SelectedButton
MessageBoxView.Title
RefView.Footer
RefView.Head
RefView.LocalBranch
RefView.LocalBranchesHeader
RefView.RemoteBranch
RefView.RemoteBranchesHeader
RefView.Tag
RefView.TagsHeader
RefView.Title
RemoteView.Footer
RemoteView.Remote
RemoteView.Title
StatusBarView.Normal
The undef command removes a user defined command. The format of the command is:
undef commandname
For example, to undefine a comamnd "mycustomcommand" the following can be used:
undef mycustomcommand
The unmap command removes any defined key binding for a key sequence in the specified view. The form of the unmap command is:
unmap view fromkeys
For example, to unmap the key 'c' in the Ref View:
unmap RefView c
The vsplit command creates a vertical split between the currently selected view and the view specified in the command. The form of the command is:
vsplit view viewargs...
For example, to create a vertical split between the currently selected view and a CommitView displaying commits for master:
vsplit CommitView master
Shell commands can be specified by using the following prefixes: ! or @. The ! prefix runs the command and displays the output in a pop-up window. The @ prefix runs the command silently and does not display any output. For example, to run the command 'git pull' and see the output in a window:
:!git pull
Alternatively to run the command 'git pull' without seeing the output:
:@git pull
Key sequences can be mapped to shell commands. For example, to map 'gp' to run the command 'git pull' in the background:
:map All gp @git pull
GRV maintains a set of variables that can be embedded in shell commands. These variables represent the current state of the visible views. The set of variables available is:
Variable | Description
---------------+------------------------------------
head | Value of HEAD
branch | Selected branch
tag | Selected tag
commit | Selected commit
file | Selected file
diff-view-file | Selected DiffView file
line-text | Selected lines content
line-number | Selected line number
line-count | Number of lines in the active view
repo-path | Repository file path
repo-workdir | Work directory path
Variables can be specified in shell commands using the syntax:
${variable}
For example, to cherry-pick the currently selected commit:
:!git cherry-pick ${commit}
User input can also be specified in shell commands by specifying a custom prompt. The syntax for a custom prompt is:
?{prompt text}
For example, to create a new branch from the currently selected commit:
:!git branch ?{New Branch Name: } ${commit}
When the above command is run the user will be shown the prompt: 'New Branch Name: ' The value entered into the prompt will be substituted into the command when executed.
GRV has a built in query language which can be used to filter the content of the Ref and Commit views. All queries resolve to boolean values which are tested against each item listed in the view. A query is composed of at least one comparison:
field CMP value
CMP can be any of the following comparison operators, which are case-insensitive:
=, !=, >, >=, <, <=, GLOB, REGEXP
Value is one of the following types:
string (e.g. "test")
number (e.g. 123 or 123.0)
date (e.g. "2017-09-05 10:05:25" or "2017-09-05")
Field is specific to the view that is being filtered. For example, to filter commits to those whose commit messages start with "Bug Fix:":
summary GLOB "Bug Fix:*"
Or equivalently:
summary REGEXP "^Bug Fix:.*"
For more inforation about the supported GLOB syntax see: https://github.com/gobwas/glob
For more information about the supported regex syntax see: https://golang.org/s/re2syntax
Comparisons can be composed together using the following logical operators, which are case-insensitive:
AND, OR, NOT
For example, to filter commits to those authored by John Smith or Jane Roe in September 2017, ignoring merge commits:
authordate >= "2017-09-01" AND authordate < "2017-10-01" AND (authorname = "John Smith" OR authorname = "Jane Roe") AND parentcount < 2
As shown above, expressions can be grouped using parentheses.
The list of (case-insensitive) fields that can be used in the Commit View is:
Field | Type
---------------+--------
authordate | Date
authoremail | String
authorname | String
committerdate | Date
committeremail | String
committername | String
id | String
message | String
parentcount | Number
summary | String
The list of (case-insensitive) fields that can be used in the Ref View is:
Field | Type
------+--------
name | String