*gitsupport.txt* Git Support Oct 24 2014
Git Support *git-support* *gitsupport*
Plug-in version 0.9.2
for Vim version 7.0 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>|: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 |: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 usingCTRL-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.
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>]:GitBufExecutes "git<cmd>[<args>]<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! [Executes "git add ...". The second version forces the add. If no arguments are given, adds the current buffer. Examples: Add the current buffer:<args>]:GitAddSimilarly::GitAdd -- %Is equivalent to:git add --<currentfile>Add all the Vim scripts in the current directory::GitAdd! *.vimIs equivalent to:git add -f *.vim
*:GitBlame*:[range]GitBlame:[range]GitBlame<args>The first version opens a buffer containing the output of Git's blame for the current buffer. The second version runs blame for the given arguments. When a range is given, the output is limited to these lines. 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 cs commit under cursor: show
*:GitBranch*:GitBranch:GitBranchThe first version opens a buffer listing all branches, including remote ones. The second version executes "git branch ...". Map Meaning<args>
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 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 [Executes "git checkout ...". Examples: Check out the file in the current buffer:<args>]:GitCheckout -- %(Might require running ":e" to update the buffer itself.) Check out the branch "master"::GitCheckout masterSettings: - |g:Git_CheckoutExpandEmpty|
*:GitCommit* *:GitCommitFile* *:GitCommitMsg*:GitCommit [<args>]:GitCommitFile [<file>]:GitCommitMsgThe 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.<msg>NoteThe 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::GitCommitMergeThis 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 -FThe file MERGE_MSG contains the standard message for merges, which looks similar to this:<base>/.git/MERGE_MSGMerge remote-tracking branch 'origin/master'Conflicts:somedir/thefile.txtNoteI 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."Make a larger commit, take the commit message from a file::GitCommitFile commit.txtIs equivalent to:git commit -F commit.txtAmend the previous commit::GitCommit --amend -F commit.txtIs equivalent to:git commit --amend -F commit.txt
*:GitDiff*:GitDiff:GitDiff<args>Both version run diff for the given arguments. The behavior of the first version depends on the setting |g:Git_DiffExpandEmpty|. By default, the first version opens the diff showing all unstaged changes. If |g:Git_DiffExpandEmpty| is set to 'yes', only the diff of the current file is shown. This makes the behavior of :GitDiff more consistent with commands like |:GitAdd|. 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 position under the cursor
Example: Show the diff for the current file::GitDiff %Show the diff for a file Vector.cc and its header Vector.h::GitDiff Vector.*Is equivalent to:git diff Vector.*Settings: - |g:Git_DiffExpandEmpty|
*:GitFetch*
:GitFetch [<args>]
Executes "git fetch ...".
*:GitGrep* *:GitGrepTop*:GitGrep<args>:GitGrepTopThe 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<args>
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.
Map Meaning
S-F1 help: show a list of all maps q close the buffer
Example: Show the help for the add command::GitHelp addIs equivalent to:git help add
*:GitLog*:GitLog:GitLog<args>The first version opens a buffer containing the log for the current branch. The second version runs log for the given arguments. Map Meaning
S-F1 help: show a list of all maps q close the buffer u update the buffer
*:GitMerge* *:GitMergeUpstream*:GitMerge [<args>]:GitMergeUpstream [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:<args>]:GitMergeUpstream --ff-onlyIs equivalent to:git merge --ff-only<upstream-branch>
*:GitMove* *:GitMv*:GitMove [<args>]:GitMv [Both versions behave the same. Executes "git mv ...".<args>]
*:GitPull*
:GitPull [<args>]
Executes "git pull ...".
*:GitPush*
:GitPush [<args>]
Executes "git push ...".
*:GitRemote*:GitRemote:GitRemoteThe first version opens a buffer listing all the remotes together with their URLs. The second version executes "git remote ...". Map Meaning<args>
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 [Both versions behave the same. Executes "git rm ...". If no arguments are given, removes the current buffer. Example: Reset the current file:<args>]:GitRemoveIs equivalent to:git rm --<currentfile>
*:GitReset*:GitReset [<args>]Executes "git reset ...". Example: Reset the current file::GitReset -- %Settings: - |g:Git_ResetExpandEmpty|
*: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>]:GitSlistThe 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 [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:<path>]: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 of open file (edit) ol open log 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>...]]:GitTagThe first version opens a buffer listing the tags. The second version executes "git tag ...". Map Meaning<args>
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*:GitBashRuns git in an external terminal. Useful for interactive commands, for example:<args>:GitBash add --patch %Windows: If called without arguments, starts the git bash in interactive mode.
*:GitSupportHelp* *:GitSupportSettings*:GitSupportHelpOpens 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.
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=boldhighlight GitHighlight1 ctermfg=Green guifg=DarkGreenhighlight GitHighlight2 ctermfg=DarkYellow guifg=DarkYellowhighlight GitHighlight3 cterm=bold ctermfg=Cyan gui=bold guifg=DarkCyanhighlight GitAdd ctermfg=Green guifg=SeaGreenhighlight GitRemove ctermfg=Red guifg=Redhighlight GitConflict cterm=bold ctermfg=White ctermbg=Red\ gui=bold guifg=White guibg=RedExample:To display the current branch in yellow instead of green use: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 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
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
* :GitBlame does not work correctly when the visual area consists only of the
first line.
- This seems to be a weakness with Vim's support for ranges. At least I
could not find a way around this.
- Workaround: Run :GitBlame on the first two lines.
- The usefulness of :GitBlame supporting ranges by far outweighs this
downside, in my opinion.
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 (KingTiger): - the idea for command-line completion of branches, remotes, tags, ... (|gitsupport-cmds-cmd-line|) is taken from his plug-in "cmdline completion" ( http://www.vim.org/scripts/script.php?script_id=3531 )
vim:tw=78:noet:ts=2:ft=help:norl:expandtab:
Generated by vim2html on Mi 29. Okt 15:07:16 CET 2014