gitsupport.txt Git Support Jul 18 2020
Git Support git-support gitsupport
Plug-in version 0.9.4-1
for Vim version 7.4 and above
Wolfgang Mehner <wolfgang-mehner at web.de>
Integration of Git for Vim/gVim. The plug-in at hand allows to use Git from
within Vim, eliminating the need for context switches. The output of commands
like "git status" is written into buffers, and the commit can be manipulated
from right there. Further commands allow to quickly add the file in the
current buffer or show its diff. See the chapter gitsupport-introduction for
a quick overview and a short guide to this documentation.
==============================================================================
0. TABLE OF CONTENTS gitsupport-contents
==============================================================================
1. Introduction gitsupport-introduction
2. Overview gitsupport-overview
2.1 Menu gitsupport-overview-menu
2.2 Workflow gitsupport-overview-work
3. Commands gitsupport-commands
3.1 Command-Line Completion gitsupport-cmds-cmd-line
4. Syntax Highlighting gitsupport-syntax
4.1 Branch gitsupport-syn-branch
4.2 Commit gitsupport-syn-commit
4.3 Diff gitsupport-syn-diff
4.4 Grep gitsupport-syn-grep
4.5 Log gitsupport-syn-log
4.6 Status gitsupport-syn-status
5. Custom Menus gitsupport-menus
6. Configuration gitsupport-configuration
6.1 Executable gitsupport-config-executable
6.2 Menus gitsupport-config-menus
6.3 Maps gitsupport-config-maps
6.4 Settings gitsupport-config-settings
6.5 Xterm gitsupport-config-xterm
A. Troubleshooting - Known Issues gitsupport-troubleshooting
B. Release Notes - Change Log gitsupport-release-notes
C. Credits gitsupport-credits
==============================================================================
1. INTRODUCTION gitsupport-introduction
==============================================================================
Git Support defines two types of commands. The first kind provides convenient
access to various Git commands which manipulate the working directory and
staging area. The second kind redirects the output from Git commands like "git
status" into buffers. For each such buffer maps are defined which can be used
to run other commands. For example, after running :GitStatus, you can use maps
like "a" and "c" to add or check out the file under the cursor, provided its
name appears in the section "Changes not staged for commit:". Each buffer has
a map <SHIFT-F1> for showing a short help.
All commands are listed in a menu "Git". It provides convenient access to all
the commands and gives an overview of the plug-in's functionality. The plug-in
supports custom menu entries, which can be configured easily.
The next chapter gitsupport-overview gives an overview of the plug-in, fol-
lowed by a detailed description of the commands in gitsupport-commands. The
customization of the syntax highlighting is explained in gitsupport-syntax,
the customizable menu entries in gitsupport-menus. The chapter
gitsupport-configuration documents further configurations.
==============================================================================
2. OVERVIEW gitsupport-overview
==============================================================================
The following commands are provided by Git Support. Each command is executed
in the current working directory, just as it would work on the shell. You can
run the commands in every subdirectory of the project.
Command Short Description
----------------------------------------------------------------------------
:Git <cmd> [<args>] (run) git <cmd> <args>
:Git! <cmd> [<args>] (buf) git <cmd> <args>
:GitRun <cmd> [<args>] (run) git <cmd> <args>
:GitBuf <cmd> [<args>] (buf) git <cmd> <args>
:GitAdd [<args>] (run) git add <args>
:GitBlame [<args>] (buf) git blame <args> (supports ranges)
:GitBranch (buf) git branch
:GitBranch <args> (run) git branch <args>
:GitCheckout [<args>] (run) git checkout <args>
:GitCommit [<args>] (run) git commit <args>
:GitCommit --dry-run [<args>] (buf) git commit --dry-run <args>
:GitCommitFile [<file>] (run) git commit -F <file>
:GitCommitMerge (run) git commit -F <base>/.git/MERGE_MSG
:GitCommitMsg <msg> (run) git commit -m "<msg>"
:GitDiff [<args>] (buf) git diff <args>
:GitFetch [<args>] (run) git fetch <args>
:GitGrep <args> (buf) git grep <args>
:GitGrepTop <args> (buf) git grep <args> (^1)
:GitHelp [<args>] (buf) git help <args>
:GitLog [<args>] (buf) git log <args> (supports ranges)
:GitMerge [<args>] (run) git merge <args>
:GitMergeUpstream [<args>] (run) git merge <args> <upstream-branch>
:GitMove [<args>] (run) git mv <args>
:GitMv [<args>] (run) git mv <args>
:GitPull [<args>] (run) git pull <args>
:GitPush [<args>] (run) git push <args>
:GitRemote (buf) git remote
:GitRemote <args> (run) git remote <args>
:GitRemove [<args>] (run) git rm <args>
:GitRm [<args>] (run) git rm <args>
:GitReset [<args>] (run) git reset <args>
:GitShow [<args>] (buf) git show <args>
:GitStash [<args>] (run) git stash <args>
:GitStash list [<args>] (buf) git stash list <args>
:GitStash show [<args>] (buf) git stash show <args>
:GitSlist (buf) git stash list
:GitStatus [<path>] (buf) git status
:GitTag (buf) git tag
:GitTag <args> (run) git tag <args>
:GitK <args> start gitk with the given arguments
:GitBash <args> run git in an external terminal
:GitTerm <args> run git in a terminal window
:GitEdit <fileid> edit the file referred to by <fileid>
:GitSupportHelp show plug-in help
:GitSupportSettings show plug-in settings
----------------------------------------------------------------------------
(run) runs the command after asking for confirmation
(buf) runs the command and redirects its output in a new buffer
(^1) runs the command within the context of the top-level directory
When a command opens a new buffer, several maps are defined for this buffer.
Hitting <SHIFT-F1> always prints a short help with all available maps.
The default argument for GitAdd, GitBlame, GitCheckout, GitCommitFile, GitRm,
GitRemove and GitReset is the current buffer.
When called without arguments, the commands GitBranch and GitRemote open a
buffer, otherwise they run the respective Git command with the given
arguments.
Names of Git objects can be completed while on the Vim command-line, similar
to the way words can be completed in buffers using CTRL-P (see i_CTRL-P).
The names of branches, commands, remotes and tags can be completed that way.
This feature has to be enabled by hand, see gitsupport-cmds-cmd-line for
details.
------------------------------------------------------------------------------
2.1 MENU gitsupport-overview-menu
------------------------------------------------------------------------------
Git Support comes with a menu "Git" which contains all commands for convenient
access. The menu contains several entries which open buffers for a quick
overview of your repository: branch, log, status, ...
All commands are listed in the menu "git ...". Each entry opens the command-
line and inserts the respective command, awaiting further input. This menu
provides an overview of the plug-in's functionality.
The menu "file" contains several commands which can be run on the current
buffer. Each entry runs the command directly. This is designed to support the
work on the current file: viewing diffs, adding or checking out the file, ...
Some special commands are provided in the menu "specials". See their documen-
tation for further help.
The menu "custom" is configurable by the user. It can be used to list Git
commands with regularly used combination of flags. (see gitsupport-menus)
To quickly jump to important files, such as config and ignore files, use the
menu "edit". (or the command :GitEdit)
------------------------------------------------------------------------------
2.2 WORKFLOW gitsupport-overview-work
------------------------------------------------------------------------------
To be completely honest, the plug-in in its current state is probably best
suited for my own workflow. This is the main reason why simply running
:GitCommit without arguments currently does not work, and why there is a
:GitCommitFile command.
I keep a file like 'project/commit.txt' around and protocol the changes while
working on the files. This has the advantage that names of variables,
functions or classes can quickly be inserted using <CTRL-P>. Intermediate
results can be staged using :GitAdd, so the output of :GitDiff is clean
again. After a look at the output of :GitStatus and assembling the release
in the status buffer, I finalize the commit message in 'project/commit.txt'.
Running :GitCommitFile on the buffer commits the changes using the contents
of the file as the message.
I am convinced, since you do not have to leave Vim to manage your repository,
that this is a better way of doing things. Editing the commit message in a
window gives you the chance to browse around your project in the environment
your already working in. You furthermore can have a look at logs, compare
different branches or add another file while writing the commit message. And
seeing how you use Vim for a big project like the kinds of projects you manage
in a version control system, you obviously do not have a problem dealing with
one further file.
==============================================================================
3. COMMANDS gitsupport-commands
==============================================================================
Whenever a command opens a buffer, several maps are defined for this buffer.
Hitting <SHIFT-F1> always prints a short help with all available maps. All
buffers can be closed via <q> and updated via <u>.
------------------------------------------------------------------------------
:Git :GitRun :GitBuf
:Git <cmd> [<args>]
:GitRun <cmd> [<args>]
:Git! <cmd> [<args>]
:GitBuf <cmd> [<args>]
Executes "git <cmd> ...". The last two versions redirect the output into a
buffer.
Map Meaning
----------------------------------------------------------------------------
S-F1 help: show a list of all maps
q close the buffer
u update the buffer
----------------------------------------------------------------------------
------------------------------------------------------------------------------
:GitAdd
:GitAdd [<args>]
:GitAdd! [<args>]
Executes "git add ...". The second version forces the add. If no arguments are
given, adds the current buffer.
Examples:
Add the current buffer:
:GitAdd
Similarly:
:GitAdd -- %
Is equivalent to:
git add -- <currentfile>
:GitAdd! *.vim
Is equivalent to:
git add -f *.vim
------------------------------------------------------------------------------
:GitBlame
:[range]GitBlame :[range]GitBlame <args> ------------------------------------------------------------------------------
:GitBranch
:GitBranch
:GitBranch <args>
The first version opens a buffer listing all branches, including remote ones.
The second version executes "git branch ...".
Map Meaning
----------------------------------------------------------------------------
S-F1 help: show a list of all maps
q close the buffer
u update the buffer
branch under the cursor ...
ch checkout
cr use as starting point for creating a new branch
Ch / CH create new branch and check it out
de delete
De / DE delete (via -D)
me merge with current branch
re use as upstream for rebase
rn rename
su set as upstream from current branch
cs show the commit
----------------------------------------------------------------------------
------------------------------------------------------------------------------
:GitCheckout
:GitCheckout [<args>]
Executes "git checkout ...".
Examples:
Check out the file in the current buffer:
:GitCheckout -- %
(Might require running ":e" to update the buffer itself.)
Check out the branch "master":
:GitCheckout master
------------------------------------------------------------------------------
:GitCommit :GitCommitFile :GitCommitMsg
:GitCommit [<args>]
:GitCommitFile [<file>]
:GitCommitMsg <msg>
The first version runs "git commit" with the given arguments. If the arguments
include the "--dry-run" flag, the output is redirected into a buffer. The
second version takes the commit message from the given file (default: current
buffer). The third version uses the commit message provided on the command
line.
Note The command :GitCommit currently can not be run without arguments. Supply
the commit message using either the -m or -F options, or by using the
other versions :GitCommitFile or :GitCommitMsg.
:GitCommitMerge
Commit a merge:
:GitCommitMerge
This version commits changes from a merge conflict. It first looks for the
base (toplevel) directory of the repository (<base>) and checks whether there
is a file <base>/.git/MERGE_HEAD located there. Then the changes are committed
via:
git commit -F <base>/.git/MERGE_MSG
The file MERGE_MSG contains the standard message for merges, which looks
similar to this:
Merge remote-tracking branch 'origin/master'
Conflicts:
somedir/thefile.txt
Note I do not know whether this is a "proper" usage of Git. However, it seems
to work and even the files in the .git/ directory which indicate the
merge conflict (MERGE_HEAD, MERGE_MSG, ...) are gone afterwards.
Examples:
Make a small commit:
:GitCommitMsg Minor changes.
Is equivalent to:
git commit -m "Minor changes."
:GitCommitFile commit.txt
Is equivalent to:
git commit -F commit.txt
:GitCommit --amend -F commit.txt
Is equivalent to:
git commit --amend -F commit.txt
------------------------------------------------------------------------------
:GitDiff
:GitDiff :GitDiff <args> :GitDiff %
:GitDiff Vector.*
Is equivalent to:
git diff Vector.*
------------------------------------------------------------------------------
:GitFetch
:GitFetch [<args>]
Executes "git fetch ...".
------------------------------------------------------------------------------
:GitGrep :GitGrepTop
:GitGrep <args>
:GitGrepTop <args>
The first version opens a buffer containing the output of Git's grep. The
second version runs grep within the context of the top-level directory of the
repository.
Map Meaning
----------------------------------------------------------------------------
S-F1 help: show a list of all maps
q close the buffer
u update the buffer
of file under cursor: open file (edit)
oj file under cursor: open and jump to the corresponding line
<Enter> file under cursor: open and jump to the corresponding line
----------------------------------------------------------------------------
------------------------------------------------------------------------------
:GitHelp
:GitHelp [<args>]
Opens a buffer containing the help for one of Git's commands. If no command is
given, opens the help for Git itself. Use tab-completion for convenience.
Map Meaning
----------------------------------------------------------------------------
S-F1 help: show a list of all maps
q close the buffer
----------------------------------------------------------------------------
Example:
Show the help for the add command:
:GitHelp add
Is equivalent to:
git help add
------------------------------------------------------------------------------
:GitLog
:GitLog :GitLog <args> :[range]GitLog <args>
The third version shows the log for the given range. In this case the
arguments can not list further files.
(this version uses the cmd.-line option `git log -L line1,line2:buffername`)
Map Meaning
----------------------------------------------------------------------------
S-F1 help: show a list of all maps
q close the buffer
u update the buffer
commit under the cursor ...
ch checkout
cr use as starting point for creating a new branch
sh / cs show the commit
ta tag the commit
----------------------------------------------------------------------------
------------------------------------------------------------------------------
:GitMerge :GitMergeUpstream
:GitMerge [<args>]
:GitMergeUpstream [<args>]
The first version executes "git merge ...". The second version automatically
obtains the name of the upstream branch and merges it into the current branch.
arguments can still be given:
:GitMergeUpstream --ff-only
Is equivalent to:
git merge --ff-only <upstream-branch>
------------------------------------------------------------------------------
:GitMove :GitMv
:GitMove [<args>]
:GitMv [<args>]
Both versions behave the same. Executes "git mv ...".
------------------------------------------------------------------------------
:GitPull
:GitPull [<args>]
Executes "git pull ...".
------------------------------------------------------------------------------
:GitPush
:GitPush [<args>]
Executes "git push ...".
------------------------------------------------------------------------------
:GitRemote
:GitRemote
:GitRemote <args>
The first version opens a buffer listing all the remotes together with their
URLs. The second version executes "git remote ...".
Map Meaning
----------------------------------------------------------------------------
S-F1 help: show a list of all maps
q close the buffer
u update the buffer
remote under the cursor ...
fe fetch
ph push
pl pull
rm remove
rn rename
su set-url
sh show
----------------------------------------------------------------------------
------------------------------------------------------------------------------
:GitRemove :GitRm
:GitRemove [<args>]
:GitRm [<args>]
Both versions behave the same. Executes "git rm ...". If no arguments are
given, removes the current buffer.
Example:
Reset the current file:
:GitRemove
Is equivalent to:
git rm -- <currentfile>
------------------------------------------------------------------------------
:GitReset
:GitReset [<args>] :GitReset -- %
------------------------------------------------------------------------------
:GitShow
:GitShow [<args>]
Opens a buffer containing the output of "git show ...". For commits and
annotated tags, shows the commit/tag message and the diff. For blobs a
separate buffer is opened.
Map Meaning
----------------------------------------------------------------------------
S-F1 help: show a list of all maps
q close the buffer
u update the buffer
----------------------------------------------------------------------------
------------------------------------------------------------------------------
:GitStash :GitSlist
:GitStash [<args>]
:GitStash list [<args>]
:GitStash show [<args>]
:GitSlist
The first version executes "git stash ...". The second and third version open
buffers listing the stashes or showing a stash. The command ":GitSlist" is a
shorthand for ":GitStash list"
The buffer for ":GitStash list" defines the following maps:
Map Meaning
----------------------------------------------------------------------------
S-F1 help: show a list of all maps
q close the buffer
u update the buffer
sh show the stash under the cursor
sp show the stash in patch form
sa save with a message
pu create a new stash (push)
stash under the cursor ...
ap apply
po pop
dr drop
br create and checkout a new branch
----------------------------------------------------------------------------
The buffer for ":GitStash show" defines the following maps:
Map Meaning
----------------------------------------------------------------------------
S-F1 help: show a list of all maps
q close the buffer
----------------------------------------------------------------------------
------------------------------------------------------------------------------
:GitStatus
:GitStatus [<path>]
Opens a buffer showing the current status. Several different actions can be
performed for the file under the cursor, see below.
A path can be given as an argument to restrict the output to changes in that
folder, for example the current one:
:GitStatus .
The paths will be printed relative to the given path, not the current working
directory, as Git would do it. The special argument "/" has the same effect as
passing the top-level directory of the repository:
:GitStatus /
In any case, :GitStatus respects the option "status.relativePaths".
The map 'od' opens the diff for the file under the cursor. The normal behavior
is to open the "default" diff between the index and the working tree. In the
section containing the staged files, titled "Changes to be committed", this
behavior is different. The default behavior is to open the diff displaying the
staged changes. This can be modified using g:Git_StatusStagedOpenDiff.
The map 'D' to remove untracked files is special, in that it does not run a
Git command.
Map Meaning
----------------------------------------------------------------------------
S-F1 help: show a list of all maps
q close the buffer
u update the buffer
toggle ...
i show ignored files
s short output
v verbose output
file under cursor ...
a add
ap add --patch (^1)
c checkout
cp checkout --patch (^1)
ch checkout HEAD (set index and working tree to HEAD)
od open diff
ow open diff (with --color-words)
of open file (edit)
oj open file (edit)
ol open log (with --stat)
r reset
rp reset --patch (^1)
D delete from file system (only untracked files)
----------------------------------------------------------------------------
(^1) requires working "git bash"
Settings:
- g:Git_StatusStagedOpenDiff
------------------------------------------------------------------------------
:GitTag
:GitTag [-n[<num>]] [--contains <commit>] [-l [<pattern>...]]
:GitTag <args>
The first version opens a buffer listing the tags. The second version executes
"git tag ...".
Map Meaning
----------------------------------------------------------------------------
S-F1 help: show a list of all maps
q close the buffer
u update the buffer (list only)
tag under cursor ...
ch checkout
cr use as starting point for creating a new branch
de delete
me merge with current branch
sh show the tag
cs show the commit
----------------------------------------------------------------------------
------------------------------------------------------------------------------
:GitK
:GitK <args>
Starts gitk with the given arguments.
------------------------------------------------------------------------------
:GitBash
:GitBash <args>
Runs git in an external terminal. Useful for interactive commands, for
example:
:GitBash add --patch %
Windows: If called without arguments, starts the git bash in interactive mode.
------------------------------------------------------------------------------
:GitTerm
:GitTerm <args>
Runs git in a terminal window. Useful for interactive commands, for example:
:GitTerm diff --color-words %
Requires +terminal.
------------------------------------------------------------------------------
:GitEdit
:GitEdit <fileid>
Edit the file referred to by <fileid>, which must be one of the IDs below.
Use tab-completion for convenience.
ID File
----------------------------------------------------------------------------
config-global $HOME/.gitconfig
config-local $GIT_CONFIG or .git/config
description .git/description
hooks .git/hooks/
ignore-global -> value of "core.excludesfile"
ignore-local .gitignore
ignore-private .git/info/exclude
modules .gitmodules
----------------------------------------------------------------------------
------------------------------------------------------------------------------
:GitSupportHelp :GitSupportSettings
:GitSupportHelp
Opens the help for Git Support.
:GitSupportSettings
:GitSupportSettings!
Shows the plug-in settings. The second version is verbose.
------------------------------------------------------------------------------
3.1 COMMAND-LINE COMPLETION gitsupport-cmds-cmd-line
------------------------------------------------------------------------------
g:Git_MapCompleteBranch g:Git_MapCompleteCommand
g:Git_MapCompleteRemote g:Git_MapCompleteTag
The user can configure maps to complete the names of branches, remotes, tags
and Git-commands on the command-line. The command-line is set up to complete
filenames using "tab". Other elements are completed using special keys, which
may be configured like this:
let g:Git_MapCompleteBranch = '<c-b>' " complete branches, CTRL-B
let g:Git_MapCompleteCommand = '<c-s>' " complete commands, CTRL-S
let g:Git_MapCompleteRemote = '<c-r>' " complete remotes, CTRL-R
let g:Git_MapCompleteTag = '<c-t>' " complete tags, CTRL-T
These maps are not set up by default. Only if one of these variables is set,
then the corresponding map is created.
Normally, the part between the cursor and the last space is completed. For
example, with the cursor at ^:
:GitShow ma
^
Using CTRL-B (for completing branches) would result in:
:GitShow master
^
Using CTRL-B again would go back to the beginning or another branch starting
with "ma...":
:GitShow maintain-v1.1
^
For completing branches and tags a special rule is used. If the part between
the cursor and the last space contains a ".." or "...", then only the part
starting at the dots is completed:
:GitShow feature.dev..ma
^
Using CTRL-B will still result in:
:GitShow feature.dev..master
^
If the part after the last space starts with "--some-option=", the part follow
the "=" is completed:
:GitK --select-commit=ma
^
Using CTRL-B will also correctly complete the name of the branch:
:GitK --select-commit=master
^
Completing for Git commands and options is performed with the maps configured
via g:Git_MapCompleteCommand. For the first word after :Git, :GitRun,
:GitBash, ..., the names of Git commands are complete:
:GitBash a
:GitBash add
:GitBash apply
:GitBash a...
If the Git command has been recognized, such as:
:GitDiff
:Git! diff
:GitBash diff
:GitTerm diff
then command-line options are completed:
:GitTerm diff --c
:GitTerm diff --cached
:GitTerm diff --color-words
:GitTerm diff --c...
==============================================================================
4. SYNTAX HIGHLIGHTING gitsupport-syntax
==============================================================================
Git Support comes with syntax highlighting for various kinds of Git output.
The appearance can be changed by the user, by adding custom settings to the
file .vimrc.
The default configuration is to use Vim's own syntax categories as fallbacks,
which should achieve a certain interoperability with Vim's colorschemes.
Category Short Description Example
----------------------------------------------------------------------------
GitComment comments (uses 'Comment') see :GitStatus
GitHeading a heading (bold font) diff header
GitHighlight1 a highlight (uses 'Identifier') current branch
GitHighlight2 another highlight (uses 'PreProc') commit hash
GitHighlight3 another highlight (underlined) diff range
GitWarning a warning (uses 'WarningMsg')
GitSevere a stern warning (uses 'ErrorMsg')
GitAdd an added file/line (uses 'DiffAdd') diff output
GitRemove a removed file/line (uses 'DiffDelete') diff output
GitConflict a (merge) conflict (uses 'DiffText') diff output
GitGrepPath a path (uses 'Directory') grep output
GitGrepLineNr a line number (uses 'LineNr') grep output
----------------------------------------------------------------------------
Suggestions for a syntax highlighting which resemble Git's own highlighting
can be found in the file "git-support/rc/additions.vimrc". For a bright
background it suggests the following settings:
highlight GitHeading cterm=bold gui=bold
highlight GitHighlight1 ctermfg=Green guifg=DarkGreen
highlight GitHighlight2 ctermfg=DarkYellow guifg=DarkYellow
highlight GitHighlight3 cterm=bold ctermfg=Cyan gui=bold guifg=DarkCyan
highlight GitAdd ctermfg=Green guifg=SeaGreen
highlight GitRemove ctermfg=Red guifg=Red
highlight GitConflict cterm=bold ctermfg=White ctermbg=Red
\ gui=bold guifg=White guibg=Red
highlight GitBranchCurrent ctermfg=Yellow guifg=DarkYellow
------------------------------------------------------------------------------
4.1 BRANCH gitsupport-syn-branch
------------------------------------------------------------------------------
Only the current branch is highlighted.
Category Short Description
----------------------------------------------------------------------------
GitBranchCurrent the current branch (line starting with "*")
-> uses GitHighlight1
----------------------------------------------------------------------------
------------------------------------------------------------------------------
4.2 COMMIT gitsupport-syn-commit
------------------------------------------------------------------------------
Highlights characters exceeding the maximal length of a line:
1st line - max. 50 characters
2st line - should be empty
others - max. 76 characters
Category Short Description
----------------------------------------------------------------------------
GitWarning characters exceeding the maximal length of the line
----------------------------------------------------------------------------
------------------------------------------------------------------------------
4.3 DIFF gitsupport-syn-diff
------------------------------------------------------------------------------
The headers of the output for each file are highlighted, as well as each range
"@@ <range> @@" and inserted and deleted lines. Folds are created for each
file and subfolds for each block (starting with "@@ <range> @@"). For unmerged
files, regions with conflicts are highlighted as well.
This highlighting is also used for ":GitStash show"
Category Short Description
----------------------------------------------------------------------------
GitDiffHeader the header generated for each file
(lines like "diff ...", "index ...", ...)
-> uses GitHeading
GitWhiteTab whitespaces before a tab in an inserted line
-> uses GitSevere
GitTrailingWhite trailing whitespaces in an inserted line
-> uses GitSevere
----------------------------------------------------------------------------
GitDiffRange the range of a single block of the output
(line "@@ <range> @@ ...")
-> uses GitHighlight3
GitDiffLineP inserted lines (lines starting with "+")
-> uses GitAdd
GitDiffLineM removed lines (lines starting with "-")
-> uses GitRemove
----------------------------------------------------------------------------
GitMergeRange the range of a single block of the output
(line "@@@ <range> @@@ ...")
-> uses GitHighlight3
GitMergeLineP inserted lines (lines starting with "+ " or " +")
-> uses GitAdd
GitMergeLineM removed lines (lines starting with "- " or " -")
-> uses GitRemove
GitMergeConflict lines signaling regions with conflicts
(lines like "++<<<<<<< HEAD", "++=======" or
"++>>>>>>> master")
-> uses GitConflict
----------------------------------------------------------------------------
------------------------------------------------------------------------------
4.4 GREP gitsupport-syn-grep
------------------------------------------------------------------------------
Highlights the path and (optional) line number at the beginning of each line.
Category Short Description
----------------------------------------------------------------------------
GitGrepPath the path at the beginning of each line
GitGrepLineNr the line number following it
----------------------------------------------------------------------------
------------------------------------------------------------------------------
4.5 LOG gitsupport-syn-log
------------------------------------------------------------------------------
The name of each commit and the information about the author, date, ... are
highlighted. Folds are created for each commit.
This highlighting is also used for ":GitStash list", ":GitShow <commit>" and
":GitShow <tag>".
Category Short Description
----------------------------------------------------------------------------
GitLogHash the name of the commit (line "commit <hash>")
-> uses GitHighlight2
GitLogRef refs obtained with "git log --decorate"
-> uses GitHighlight1
GitLogInfo information about the commit
(lines like "Author: ..." or "Date: ...")
-> uses GitHighlight1
GitStashName the name of a stash (line "stash@{123}: ...")
-> no highlighting by default
GitTagName the name of the tag (line "tag <name>")
-> uses GitHighlight2
----------------------------------------------------------------------------
------------------------------------------------------------------------------
4.6 STATUS gitsupport-syn-status
------------------------------------------------------------------------------
Various items are hightlighted, like the headlines of each section and the
files (in green and red). Adds a fold for each section "Changes to be
committed:", "Changes not staged for commit:", ...
Category Short Description
----------------------------------------------------------------------------
GitStatusHeader the header of each section
(lines like "# Changes not staged for commit:")
-> uses GitHeading
GitStatusComment additional help inserted into the output
(lines like "# (use 'git add <file>...' to ...)")
-> uses GitComment
GitStagedFile files listed as "to be committed"
-> uses GitAdd
GitModifiedFile files listed as "not staged for commit"
-> uses GitRemove
GitUntrackedFile files listed as "untracked"
-> uses GitRemove
GitIgnoredFile files listed as "ignored"
-> uses GitRemove
GitUnmergedFile files listed as "unmerged"
-> uses GitRemove
----------------------------------------------------------------------------
==============================================================================
5. CUSTOM MENUS gitsupport-menus
==============================================================================
g:Git_CustomMenu
The custom menu entries offer convenient access to often used Git commands,
especially those with regularly used combinations of flags. All custom menu
entries appear in the sub menu "Git->custom". They are defined via the global
variable 'g:Git_CustomMenu':
let g:Git_CustomMenu = [
\ [ 'log, grep &commit msg..', ':GitLog', ':GitLog -i --grep="<CURSOR>"' ],
\ [ 'log, grep &diff output', ':GitLog', ':GitLog -p -S "<CURSOR>"' ],
\ [ 'log, &graph', ':GitLog', ':GitLog --graph<EXECUTE>' ],
\ [ '-SEP1-', '', '' ],
\ [ '&merge, ff only', ':GitMerge', ':GitMerge --ff-only <CURSOR>' ],
\ [ '&merge, no commit', ':GitMerge', ':GitMerge --no-commit <CURSOR>' ],
\ [ '&merge, abort', ':GitMerge', ':GitMerge --abort<EXECUTE>' ],
\ ]
The variable must contain a list of lists of strings. A List is constructed
using square brackets containing a number of comma-separated entries. Each
list contained in 'g:Git_CustomMenu' defines a menu entry. It consists of
three strings. The first defines the submenu and the menu entry, the second
the right-aligned side of the menu entry and the third the command triggered
by the entry.
The menu entry is a string, where dots and ampersands have special meanings.
Dots structure the menu by defining submenus. To put the entries from above
into a submenu "log", use:
let g:Git_CustomMenu = [
\ [ '&log.grep &commit msg..', ':GitLog', ':GitLog -i --grep="<CURSOR>"' ],
\ [ '&log.grep &diff output', ':GitLog', ':GitLog -p -S "<CURSOR>"' ],
\ [ '&log.-SEP1-', '', '' ],
\ [ '&log.&graph', ':GitLog', ':GitLog --graph<EXECUTE>' ],
...
Ampersands set shortcuts for menu entries and submenus. To include a literal
dot or ampersands use '..' or '&&' respectively. Separators are inserted if
the name of the entry starts and ends with a minus. They can also appear in
submenus.
The third string defines the command associated with the entry. If it contains
the <EXECUTE> tag at the end, the command will be executed directly. The <CR>
tag, which advanced Vim users will be familiar with, is also supported. If the
command contains the <CURSOR> tag instead, the command will be shown on the
command line, with the cursor at that position. Now the user can configure the
call before executing it.
Furthermore, <WORD> is replaced with the word under the cursor (<cword> or
<cWORD> can be used as well). The tag <FILE> is replaced with the name of the
file under the cursor, <BUFFER> with the name of the file loaded in the
current buffer.
These tags are available:
Tag Short Description
----------------------------------------------------------------------------
<EXECUTE> execute the command immediately
<CURSOR> open the command-line with the cursor at this position
<BUFFER> the name of the current buffer
<FILE> the file under the cursor (see <cfile>)
<WORD> the word under the cursor (see <cword>)
----------------------------------------------------------------------------
The file "git-support/rc/additions.vimrc" contains the standard value for
'g:Git_CustomMenu', as a basis for customization.
==============================================================================
6. CONFIGURATION gitsupport-configuration
==============================================================================
The configuration is done via a number of global variables, which can be set
in the .vimrc file.
Variable Default Description and further information
----------------------------------------------------------------------------
g:Git_BinPath '' the path to the Git binaries (^1)
g:Git_Executable 'git' the Git executable (^1)
g:Git_GitKExecutable 'gitk' the gitk executable (^1)
g:Git_GitKScript '' the gitk script (^1)
g:Git_GitBashExecutable 'xterm' the git bash executable (^1) (^2)
g:Git_LoadMenus 'yes' whether to load the menus
('yes' or 'no')
g:Git_RootMenu '&Git' name and shortcut of the root menu
g:Git_CustomMenu [ ... ] custom menu entries
expansion of empty argument lists to the current file:
g:Git_CheckoutExpandEmpty 'no' for :GitCheckout
g:Git_DiffExpandEmpty 'no' for :GitDiff
g:Git_ResetExpandEmpty 'no' for :GitReset
g:Git_OpenFoldAfterJump 'yes' whether commands which open a file
open the folds under the cursor
g:Git_StatusStagedOpenDiff 'cached' how to execute "open diff" from
inside the status buffer in section
"Changes to be committed"
g:Xterm_Executable 'xterm' the xterm executable (^3)
g:Xterm_Options '...' the xterm default settings (^3)
----------------------------------------------------------------------------
(^1)
The Unix defaults are as follows:
g:Git_BinPath - -empty-
g:Git_Executable - g:Git_BinPath + git
g:Git_GitKExecutable - g:Git_BinPath + gitk
g:Git_GitKScript - -empty-
the Windows defaults are as follows:
g:Git_BinPath - C:\Program Files\Git\bin\
g:Git_Executable - g:Git_BinPath + git.exe
g:Git_GitKExecutable - g:Git_BinPath + tclsh.exe
g:Git_GitKScript - g:Git_BinPath + gitk
g:Git_GitBashExecutable - g:Git_BinPath + sh.exe
(^2) under UNIX, the default for g:Git_GitBashExecutable is the value of
g:Xterm_Executable, which in turn is "xterm"
(^3) UNIX only, see gitsupport-config-xterm
------------------------------------------------------------------------------
6.1 EXECUTABLE gitsupport-config-executable
------------------------------------------------------------------------------
g:Git_BinPath
The path to the executables is set by g:Git_BinPath:
let g:Git_BinPath = '/usr/local/bin/'
Since git and gitk will be on the path, this will not be necessary on most
UNIX systems.
For Windows, set up the binary path similar to this:
let g:Git_BinPath = 'C:\Program Files\Git\bin\'
The defaults for g:Git_Executable, g:Git_GitKExecutable, g:Git_GitKScript
and g:Git_GitBashExecutable are derived from g:Git_BinPath. However, the
setting g:Git_BinPath is only used to derive the defaults. If one of the
executables is set explicitly, it has to be set with the whole path.
g:Git_Executable
The executable is set by g:Git_Executable. You should use the English language
environment:
let g:Git_Executable = 'LANG=en_US git'
For Windows, set up the executable similar to this:
let g:Git_Executable = 'C:\Program Files\Git\bin\git.exe'
g:Git_GitKExecutable g:Git_GitKScript
Sets the gitk executable. You should use the English language environment:
let g:Git_Executable = 'LANG=en_US gitk'
For Windows, set up gitk similar to this, the interpreter and the gitk script
have to be given separately:
let g:Git_GitKExecutable = 'C:\Program Files\Git\bin\tclsh.exe'
let g:Git_GitKScript = 'C:\Program Files\Git\bin\gitk'
g:Git_GitBashExecutable
Sets the git bash executable. Under UNIX "xterm" is used.
For Windows, set up the executable similar to this:
let g:Git_GitBashExecutable= 'C:\Program Files\Git\bin\sh.exe'
------------------------------------------------------------------------------
6.2 MENUS gitsupport-config-menus
------------------------------------------------------------------------------
g:Git_LoadMenus
The creation of the menus is controlled by g:Git_LoadMenus. The default
setting:
let g:Git_LoadMenus = 'yes'
causes the menus to appear right away after starting Vim.
The automatic creation of the menus is prevented by:
let g:Git_LoadMenus = 'no'
Now the menus can only be loaded by using the tool menu entry 'Tools->Load
Git Support'.
------------------------------------------------------------------------------
g:Git_RootMenu
The name and shortcut of the root menu is set via g:Git_RootMenu. The
character prefixed by '&' will be the shortcut.
Example:
let g:Git_RootMenu = 'G&it'
Sets the shortcut to 'i'.
------------------------------------------------------------------------------
6.3 MAPS gitsupport-config-maps
------------------------------------------------------------------------------
You can add hotkeys for your favorite commands by adding maps to your .vimrc.
With these lines, <F10> will open the status buffer:
noremap <silent> <F10> :GitStatus<CR>
inoremap <silent> <F10> <C-C>:GitStatus<CR>
------------------------------------------------------------------------------
6.4 SETTINGS gitsupport-config-settings
------------------------------------------------------------------------------
g:Git_CheckoutExpandEmpty g:Git_DiffExpandEmpty
g:Git_ResetExpandEmpty
The default behavior of :GitDiff, when called without arguments, is to show
a diff containing all unstaged changes.
In order to make the behavior more consistent with commands like :GitAdd,
this can be changed by setting:
let g:Git_DiffExpandEmpty = 'yes'
Now calling ":GitDiff" without any arguments opens a buffer displaying only
the changes of the file in the current buffer, which is the same as calling:
:GitDiff %
So the empty argument list is "expanded".
But even with g:Git_DiffExpandEmpty == 'yes', you can still display a diff
containing all changes by calling:
:GitDiff --
This is not detected to be an empty argument list.
Similarly, the behavior of :GitCheckout and :GitReset can be changed to
operate on the file in the current buffer when called without arguments, by
setting:
let g:Git_CheckoutExpandEmpty = 'yes'
let g:Git_ResetExpandEmpty = 'yes'
The possible settings are listed below:
Value Meaning :GitDiff expands to ...
----------------------------------------------------------------------------
'yes' expand empty argument list git diff -- <file>
'no' (default) Git's standard behavior git diff
----------------------------------------------------------------------------
The behavior can be changed on the fly by settings the variable to a different
value on the command line.
------------------------------------------------------------------------------
g:Git_OpenFoldAfterJump
Some maps jump from Git buffers to files. By default they open all the folds
under the cursor via zv. This behavior can be switched off by settings:
let g:Git_OpenFoldAfterJump = 'no'
The possible settings are listed below:
Value Meaning
----------------------------------------------------------------------------
'yes' (default) open all the folds under the cursor
'no' do not
----------------------------------------------------------------------------
The behavior can be changed on the fly by settings the variable to a different
value on the command line.
------------------------------------------------------------------------------
g:Git_StatusStagedOpenDiff
Within the status buffer, the map 'od' can be used to display the diff for the
file under the cursor. The normal behavior is to open the "default" diff
between the index and the working tree. In the section containing the staged
files, titled "Changes to be committed", this behavior is different and can be
controlled by g:Git_StatusStagedOpenDiff. Setting
let g:Git_StatusStagedOpenDiff = 'cached'
means the diff will be opened displaying the staged changes.
The other possible settings are listed below:
Value Meaning Open diff via ...
----------------------------------------------------------------------------
'cached' (default) staged changes git diff --cached -- <file>
'head' all changes git diff HEAD -- <file>
any other unstaged changes git diff -- <file>
----------------------------------------------------------------------------
The behavior can be changed on the fly by settings the variable to a different
value on the command line.
------------------------------------------------------------------------------
6.5 XTERM gitsupport-config-xterm
------------------------------------------------------------------------------
The xterm related functionality is only available under UNIX. It is used to
run interactive commands.
g:Xterm_Executable
The xterm executable is set by g:Xterm_Executable, for example:
let g:Xterm_Executable = '/usr/local/bin/xterm'
g:Xterm_Options
Set additional options for xterm. The default is:
let g:Xterm_Options = '-fa courier -fs 12 -geometry 80x24'
For example, use these arguments for black letters on a white background:
let g:Xterm_Options = '-fg black -bg white -fs 12 -geometry 80x24'
See the man-page of xterm for the possible options.
The behavior can be changed on the fly by settings the variable to a different
value on the command line.
==============================================================================
A. TROUBLESHOOTING - KNOWN ISSUES gitsupport-troubleshooting
==============================================================================
* How can I see what was loaded?
- Use ':scriptnames' from the Vim command line.
* git is not running.
- Is "git" executable from the command line?
- Is the $PATH variable set correctly?
- Are the settings correct? See:
:help gitsupport-config-executable
* Windows: When entered on the Vim command line, commands containing filenames
as arguments cause errors such as "... file not found ...".
- This may happen if filenames contain special characters such as spaces.
The Vim command line escapes those differently then Windows expects them
to be escaped.
- However, a filename containing spaces can always be escape using quotes:
:GitAdd "help 1.txt"
- If you already are in the corresponding buffer, simply use:
:GitAdd
==============================================================================
B. RELEASE NOTES - CHANGE LOG gitsupport-release-notes
==============================================================================
See files 'git-support/README.md' and 'git-support/doc/ChangeLog'.
==============================================================================
C. CREDITS gitsupport-credits
==============================================================================
Jinhu Lu (vim.org user name: KingTiger):
- the idea for command-line completion of branches, remotes, tags, ...
(gitsupport-cmds-cmd-line) is taken from his plug-in "cmdline completion"
( https://www.vim.org/scripts/script.php?script_id=3531 )
==============================================================================
vim:tw=78:expandtab:ts=2:ft=help:norl:
Generated by vim2html (modified) on So 22. Nov 12:39:55 CET 2020