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)
     * [MessageBoxView Specific](#messageboxview-specific)
     * [RemoteView Specific](#remoteview-specific)
 - [Configuration Variables](#configuration-variables)
 - [Configuration Commands](#configuration-commands)
     * [addtab](#addtab)
     * [addview](#addview)
     * [def](#def)
     * [evalkeys](#evalkeys)
     * [git](#git)
     * [giti](#giti)
     * [help](#help)
     * [hsplit](#hsplit)
     * [map](#map)
     * [q](#q)
     * [rmtab](#rmtab)
     * [set](#set)
     * [sleep](#sleep)
     * [split](#split)
     * [theme](#theme)
     * [undef](#undef)
     * [unmap](#unmap)
     * [vsplit](#vsplit)
 - [Shell Commands](#shell-commands)
 - [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|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
```


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

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


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