Permalink
Find file Copy path
876 lines (664 sloc) 25.1 KB

GRV Documentation

Introduction

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.

Table Of Contents

Command Line Arguments

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] (default "NONE")
-readOnly
	Run grv in read only mode
-repoFilePath string
	Repository file path (default ".")
-version
	Print version
-workTreeFilePath string
	Work tree file path

Key Bindings

The following tables contain default and user configured key bindings

Movement

 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                                

Search

 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              

View Navigation

 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                

General

 Key Bindings | Action                       | Description                                     
 -------------+------------------------------+--------------------------------------------------
 None         | <grv-checkout-previous-ref>  | Checkout previous ref                           
 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                                     

RefView Specific

 Key Bindings | Action                           | Description                               
 -------------+----------------------------------+--------------------------------------------
 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                             

CommitView Specific

 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                   

GitStatusView Specific

 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     

MessageBoxView Specific

 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

RemoteView Specific

 Key Bindings | Action            | Description
 -------------+-------------------+-------------
 p            | <grv-pull-remote> | Pull remote

Configuration Variables

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 |               | 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                       
 git-binary-file-path | string |               | File path to git binary. Required only when git binary is not in $PATH      
 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                                                  

Configuration Commands

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:

addtab

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

addview

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

def

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 $n or ${n} where n is an integer greater than zero corresponding to the argument to substitute. For example, the "maintab" command defined earlier can be altered to accept the branch in as an argument:

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 $@ or ${@} For example, the following command acts as an alias for the vsplit command:

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 $1 in a command body specify $$1.

evalkeys

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>

git

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.

giti

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

help

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

hsplit

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

map

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.

q

The quit command is used to exit GRV and can be used with the following keys:

:q<Enter>

rmtab

The rmtab removes the currently active tab. If the tab removed is the last tab then GRV will exit.

set

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
  • cold

The solarized theme is the default theme for GRV and does not respect the terminals colour palette. The classic and cold themes do respect the terminals colour palette.

sleep

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

split

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...

theme

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.Title

DiffView.AddedLine
DiffView.CommitAuthor
DiffView.CommitAuthorDate
DiffView.CommitCommitter
DiffView.CommitCommitterDate
DiffView.CommitMessage
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

undef

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

unmap

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

vsplit

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

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                     
 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.

Filter Query Language

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