path: root/doc/documentation.md

<!-- DO NOT EDIT -->
<!-- This file is auto-generated by grv -->

# 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](#command-line-arguments)
 - [Key Bindings](#key-bindings)
     * [Movement](#movement)
     * [Search](#search)
     * [View Navigation](#view-navigation)
     * [General](#general)
     * [RefView Specific](#refview-specific)
     * [CommitView Specific](#commitview-specific)
     * [GitStatusView Specific](#gitstatusview-specific)
 - [Configuration Variables](#configuration-variables)
 - [Configuration Commands](#configuration-commands)
     * [addtab](#addtab)
     * [addview](#addview)
     * [git](#git)
     * [giti](#giti)
     * [help](#help)
     * [hsplit](#hsplit)
     * [map](#map)
     * [q](#q)
     * [rmtab](#rmtab)
     * [set](#set)
     * [split](#split)
     * [theme](#theme)
     * [unmap](#unmap)
     * [vsplit](#vsplit)
 - [Filter Query Language](#filter-query-language)


## 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-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        
 -------------+--------------------------+---------------------
 b            | <grv-branch-name-prompt> | Create a new branch
 c            | <grv-checkout-ref>       | Checkout ref       
 <C-q>        | <grv-filter-prompt>      | Add filter         
 <C-r>        | <grv-remove-filter>      | Remove filter      
```

### CommitView Specific

```
 Key Bindings | Action                   | Description        
 -------------+--------------------------+---------------------
 b            | <grv-branch-name-prompt> | Create a new branch
 c            | <grv-checkout-commit>    | Checkout commit    
 <C-q>        | <grv-filter-prompt>      | Add filter         
 <C-r>        | <grv-remove-filter>      | Remove filter      
```

### GitStatusView Specific

```
 Key Bindings | Action              | Description
 -------------+---------------------+-------------
 c            | <grv-action-commit> | Commit     
 a            | <grv-stage-file>    | Stage      
 u            | <grv-unstage-file>  | Unstage    
```


## 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                                                  
 confirm-checkout     | bool   | true          | Confirm before performing git checkout                                
 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
```

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

### 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 or another key sequence 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 <Up> key move a line down and the <Down> key move a line up:

```
map All <Up> <grv-next-line>
map All <Down> <grv-prev-line>
```

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.

### 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.Error
CommandOutputView.Footer
CommandOutputView.Normal
CommandOutputView.Success
CommandOutputView.Title

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

GitStatusView.ConflictedFile
GitStatusView.ConflictedTitle
GitStatusView.StagedFile
GitStatusView.StagedTitle
GitStatusView.UnstagedFile
GitStatusView.UnstagedTitle
GitStatusView.UntrackedFile
GitStatusView.UntrackedTitle

HelpBarView.Normal
HelpBarView.Special

HelpView.Footer
HelpView.SectionDescription
HelpView.SectionTableHeader
HelpView.SectionTableRow
HelpView.SectionTableRowHighlighted
HelpView.SectionTitle
HelpView.Title

MainView.ActiveView
MainView.NormalView

RefView.Footer
RefView.Head
RefView.LocalBranch
RefView.LocalBranchesHeader
RefView.RemoteBranch
RefView.RemoteBranchesHeader
RefView.Tag
RefView.TagsHeader
RefView.Title

StatusBarView.Normal
```

### 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
```


## 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
```