fugitive.vim 2.5

* Support :source and :write on Fugitive URLs.
* Support :Gedit +cmd ++opt.
* Support :Gedit /absolute/path and ./relative/path.
* Support expansion flags, like :Gedit %:h.
* Support completion of commits for --fixup=/--squash=.
* Support :Gread commit to read commit message.
* Adjust :Gbrowse line range for upstream head.
* Map <CR> in blobs to jump to blamed commit.
* Map p to jump to file in preview window.
* Make :Gmove always relative to repository root.
* Load Projectionist config from .git/info/projections.json.
* Drop instaweb support.
* New public function API.
* Major robustness and error handling improvements.
* Bug fixes.

.gitattributes

@@ -0,0 +1,2 @@
+.git* export-ignore
+*.markdown export-ignore

CONTRIBUTING.markdown

@@ -8,8 +8,14 @@ platform issues, and interactions with other plugins.  I end up bisecting a
 lot more than other projects, and thus I'm especially meticulous here about
 maintaining a clean, readable, history.  Squash and force push any requested
 changes to a pull request.  And if your [commit message
-sucks](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html),
-I'm not going to accept it.  Period.
+sucks](https://commit.style), I'm not going to accept it.  Period.
+
+If your contribution involves adding a configuration option, you are going to
+need a very compelling justification for it.  Options add a maintenance
+burden, support burden, and documentation bloat, and oftentimes can be
+achieved much more simply with a custom map or autocommand.  If your option
+controls an underlying Git command, ask yourself why Git itself does not offer
+such configuration.
 
 Beyond that, don't be shy about asking before patching.  What takes you hours
 might take me minutes simply because I have both domain knowledge and a

README.markdown

@@ -11,8 +11,9 @@ Vim's diff handling capabilities to stage a subset of the file's
 changes.
 
 Bring up the output of `git status` with `:Gstatus`.  Press `-` to
-`add`/`reset` a file's changes, or `p` to `add`/`reset` `--patch`.  And guess
-what `:Gcommit` does!
+`add`/`reset` a file's changes, or `p` to `add`/`reset` `--patch`.  Use
+`:Gcommit %` to commit the current file, editing the commit message inside
+the currently running Vim.
 
 `:Gblame` brings up an interactive vertical split with `git blame`
 output.  Press enter on a line to edit the commit where the line
@@ -20,7 +21,7 @@ changed, or `o` to open it in a split.  When you're done, use `:Gedit`
 in the historic buffer to go back to the work tree version.
 
 `:Gmove` does a `git mv` on a file and simultaneously renames the
-buffer.  `:Gremove` does a `git rm` on a file and simultaneously deletes
+buffer.  `:Gdelete` does a `git rm` on a file and simultaneously deletes
 the buffer.
 
 Use `:Ggrep` to search the work tree (or any arbitrary commit) with
@@ -35,11 +36,16 @@ and you never get any warnings about the file changing outside Vim.
 making it like `git add` when called from a work tree file and like
 `git checkout` when called from the index or a blob in history.
 
-Use `:Gbrowse` to open the current file on GitHub, with optional line
-range (try it in visual mode!).  If your current repository isn't on
-GitHub, `git instaweb` will be spun up instead.
+Use `:Gbrowse` to open the current file on the web front-end of your favorite
+hosting provider, with optional line range (try it in visual mode!).  Plugins
+are available for popular providers such as [GitHub][rhubarb.vim],
+[GitLab][fugitive-gitlab.vim], and [Bitbucket][fubitive.vim].
 
-Add `%{fugitive#statusline()}` to `'statusline'` to get an indicator
+[rhubarb.vim]: https://github.com/tpope/vim-rhubarb
+[fugitive-gitlab.vim]: https://github.com/shumphrey/fugitive-gitlab.vim
+[fubitive.vim]: https://github.com/tommcdo/vim-fubitive
+
+Add `%{FugitiveStatusline()}` to `'statusline'` to get an indicator
 with the current branch in (surprise!) your statusline.
 
 Last but not least, there's `:Git` for running any arbitrary command,
@@ -60,7 +66,7 @@ If you don't have a preferred installation method, one option is to install
 and paste:
 
     cd ~/.vim/bundle
-    git clone git://github.com/tpope/vim-fugitive.git
+    git clone https://github.com/tpope/vim-fugitive.git
     vim -u NONE -c "helptags vim-fugitive/doc" -c q
 
 If your Vim version is below 7.2, I recommend also installing
@@ -69,24 +75,11 @@ other Git niceties.
 
 ## FAQ
 
-> I installed the plugin and started Vim.  Why don't any of the commands
-> exist?
+> Why don't any of the commands exist?
 
-Fugitive cares about the current file, not the current working
-directory.  Edit a file from the repository.
-
-> I opened a new tab.  Why don't any of the commands exist?
-
-Fugitive cares about the current file, not the current working
-directory.  Edit a file from the repository.
-
-> Why is `:Gbrowse` not using the right browser?
-
-`:Gbrowse` delegates to `git web--browse`, which is less than perfect
-when it comes to finding the right browser.  You can tell it the correct
-browser to use with `git config --global web.browser ...`.  On OS X, for
-example, you might want to set this to `open`.  See `git web--browse --help`
-for details.
+Fugitive cares about the current file, not the current working directory.
+Edit a file from the repository.  To avoid the blank window problem, favor
+commands like `:split` and `:tabedit` over commands like `:new` and `:tabnew`.
 
 > Here's a patch that automatically opens the quickfix window after
 > `:Ggrep`.

doc/fugitive.txt

@@ -40,10 +40,12 @@ that are part of Git repositories).
                         <CR>  |:Gedit|
                         -     |:Git| add
                         -     |:Git| reset (staged files)
-                        cA    |:Gcommit| --amend --reuse-message=HEAD
+                        a     Show alternative format
                         ca    |:Gcommit| --amend
                         cc    |:Gcommit|
-                        cva   |:Gcommit| --amend --verbose
+                        ce    |:Gcommit| --amend --no-edit
+                        cw    |:Gcommit| --amend --only
+                        cva   |:Gcommit| --verbose --amend
                         cvc   |:Gcommit| --verbose
                         D     |:Gdiff|
                         ds    |:Gsdiff|
@@ -52,11 +54,16 @@ that are part of Git repositories).
                         dv    |:Gvdiff|
                         O     |:Gtabedit|
                         o     |:Gsplit|
-                        p     |:Git| add --patch
-                        p     |:Git| reset --patch (staged files)
+                        P     |:Git| add --patch
+                        P     |:Git| reset --patch (staged files)
                         q     close status
                         r     reload status
                         S     |:Gvsplit|
+                        U     |:Git| checkout
+                        U     |:Git| checkout HEAD (staged files)
+                        U     |:Git| clean (untracked files)
+                        U     |:Git| rm (unmerged files)
+                        .     enter |:| command line with file prepopulated
 
                                                 *fugitive-:Gcommit*
 :Gcommit [args]         A wrapper around git-commit.  If there is nothing
@@ -72,17 +79,21 @@ that are part of Git repositories).
 
                                                 *fugitive-:Gmerge*
 :Gmerge [args]          Calls git-merge and loads errors and conflicted files
-                        into the quickfix list.  Opens a |:Gcommit| style
+                        into the |quickfix| list.  Opens a |:Gcommit| style
                         split window for the commit message if the merge
                         succeeds.  If called during a merge conflict, the
                         conflicted files from the current index are loaded
-                        into the quickfix list.
+                        into the |quickfix| list.
 
                                                 *fugitive-:Gpull*
 :Gpull [args]           Like |:Gmerge|, but for git-pull.
 
+                                                *fugitive-:Grebase*
+:Grebase [args]         Like |:Gmerge|, but for git-rebase.  Interactive
+                        rebase not supported.
+
                                                 *fugitive-:Gpush*
-:Gpush [args]           Invoke git-push, load the results into the quickfix
+:Gpush [args]           Invoke git-push, load the results into the |quickfix|
                         list, and invoke |:cwindow| to reveal any errors.
                         |:Dispatch| is used if available for asynchronous
                         invocation.
@@ -91,42 +102,42 @@ that are part of Git repositories).
 :Gfetch [args]          Like |:Gpush|, but for git-fetch.
 
                                                 *fugitive-:Ggrep*
-:Ggrep [args]           |:grep| with git-grep as 'grepprg'.
+:Ggrep[!] [args]        |:grep|[!] with git-grep as 'grepprg'.
 
                                                 *fugitive-:Glgrep*
-:Glgrep [args]          |:lgrep| with git-grep as 'grepprg'.
+:Glgrep[!] [args]       |:lgrep|[!] with git-grep as 'grepprg'.
 
                                                 *fugitive-:Glog*
 :Glog [args]            Load all previous revisions of the current file into
-                        the quickfix list.  Additional git-log arguments can
+                        the |quickfix| list.  Additional git-log arguments can
                         be given (for example, --reverse).  If "--" appears as
                         an argument, no file specific filtering is done, and
                         previous commits rather than previous file revisions
                         are loaded.
 
 :{range}Glog [args]     Use git-log -L to load previous revisions of the given
-                        range of the current file into the quickfix list.  The
-                        cursor is positioned on the first line of the first
-                        diff hunk for each commit.
+                        range of the current file into the |quickfix| list.
+                        The cursor is positioned on the first line of the
+                        first diff hunk for each commit.
 
                                                 *fugitive-:Gllog*
 :Gllog [args]           Like |:Glog|, but use the location list instead of the
-                        quickfix list.
+                        |quickfix| list.
 
                                         *fugitive-:Gedit* *fugitive-:Ge*
-:Gedit [revision]       |:edit| a |fugitive-revision|.
+:Gedit [object]         |:edit| a |fugitive-object|.
 
                                                 *fugitive-:Gsplit*
-:Gsplit [revision]      |:split| a |fugitive-revision|.
+:Gsplit [object]        |:split| a |fugitive-object|.
 
                                                 *fugitive-:Gvsplit*
-:Gvsplit [revision]     |:vsplit| a |fugitive-revision|.
+:Gvsplit [object]       |:vsplit| a |fugitive-object|.
 
                                                 *fugitive-:Gtabedit*
-:Gtabedit [revision]    |:tabedit| a |fugitive-revision|.
+:Gtabedit [object]      |:tabedit| a |fugitive-object|.
 
                                                 *fugitive-:Gpedit*
-:Gpedit [revision]      |:pedit| a |fugitive-revision|.
+:Gpedit [object]        |:pedit| a |fugitive-object|.
 
 :Gsplit! [args]                 *fugitive-:Gsplit!* *fugitive-:Gvsplit!*
 :Gvsplit! [args]                *fugitive-:Gtabedit!* *fugitive-:Gpedit!*
@@ -134,13 +145,12 @@ that are part of Git repositories).
 :Gpedit! [args]         split, tab, or preview window.
 
                                                 *fugitive-:Gread*
-:Gread [revision]       Empty the buffer and |:read| a |fugitive-revision|.
+:Gread [object]         Empty the buffer and |:read| a |fugitive-object|.
                         When the argument is omitted, this is similar to
                         git-checkout on a work tree file or git-add on a stage
                         file, but without writing anything to disk.
 
-:{range}Gread [revision]
-                        |:read| in a |fugitive-revision| after {range}.
+:{range}Gread [object]  |:read| in a |fugitive-object| after {range}.
 
                                                 *fugitive-:Gread!*
 :Gread! [args]          Empty the buffer and |:read| the output of a Git
@@ -169,34 +179,42 @@ that are part of Git repositories).
                         succeeded.
 
                                                 *fugitive-:Gdiff*
-:Gdiff [revision]       Perform a |vimdiff| against the current file in the
-                        given revision.  With no argument, the version in the
-                        index is used (which means a three-way diff during a
-                        merge conflict, making it a git-mergetool
-                        alternative).  The newer of the two files is placed
-                        to the right or bottom, depending on 'diffopt' and
-                        the width of the window relative to 'textwidth'.  Use
-                        |do| and |dp| and write to the index file to simulate
-                        "git add --patch".
+:Gdiff [object]         Perform a |vimdiff| against the given file, or if a
+                        commit is given, the current file in that commit.
+                        With no argument, the version in the index is used
+                        (which means a three-way diff during a merge conflict,
+                        making it a git-mergetool alternative).  The newer of
+                        the two files is placed to the right or bottom,
+                        depending on 'diffopt', and the width of the window
+                        relative to 'textwidth'.  Use |do| and |dp| and write
+                        to the index file to simulate "git add --patch". For
+                        the three-way diff, there is also d2o and d3o pulling
+                        the hunk to the middle from the left or the right
+                        window, respectively.
 
                                                 *fugitive-:Gsdiff*
-:Gsdiff [revision]      Like |:Gdiff|, but always split horizontally.
+:Gsdiff [object]        Like |:Gdiff|, but always split horizontally.
 
                                                 *fugitive-:Gvdiff*
-:Gvdiff [revision]      Like |:Gdiff|, but always split vertically.
+:Gvdiff [object]        Like |:Gdiff|, but always split vertically.
 
                                                 *fugitive-:Gmove*
 :Gmove {destination}    Wrapper around git-mv that renames the buffer
-                        afterward.  The destination is relative to the current
-                        directory except when started with a /, in which case
-                        it is relative to the work tree.  Add a ! to pass -f.
+                        afterward.  Add a ! to pass -f.
 
-                                                *fugitive-:Gremove*
-:Gremove                Wrapper around git-rm that deletes the buffer
+                                                *fugitive-:Grename*
+:Grename {destination}  Like |:Gmove| but operates relative to the parent
+                        directory of the current file.
+
+                                                *fugitive-:Gdelete*
+:Gdelete                Wrapper around git-rm that deletes the buffer
                         afterward.  When invoked in an index file, --cached is
                         passed.  Add a ! to pass -f and forcefully discard the
                         buffer.
 
+                                                *fugitive-:Gremove*
+:Gremove                Like :Gdelete, but keep the (now empty) buffer around.
+
                                                 *fugitive-:Gblame*
 :Gblame [flags]         Run git-blame on the file and open the results in a
                         scroll bound vertical split.  You can give any of
@@ -213,41 +231,33 @@ that are part of Git repositories).
                         <CR>  q, then open commit
                         o     open commit in horizontal split
                         O     open commit in new tab
+                        p     open commit in preview window
                         -     reblame at commit
                         ~     reblame at [count]th first grandparent
                         P     reblame at [count]th parent (like HEAD^[count])
 
-:[range]Gblame [flags]  Run git-blame on the given range.
-
                                                 *fugitive-:Gbrowse*
 :Gbrowse                Open the current file, blob, tree, commit, or tag
-                        in your browser at the upstream hosting provider
-                        indicated by the "origin" remote.  If a range is
-                        given, it is appropriately appended to the URL as an
-                        anchor.
+                        in your browser at the upstream hosting provider.
+                        If a range is given, it is appropriately appended to
+                        the URL as an anchor.
 
                         Upstream providers can be added by installing an
                         appropriate Vim plugin.  For example, GitHub can be
                         supported by installing rhubarb.vim, available at
-                        <https://github.com/tpope/vim-rhubarb>.  (Native
-                        support for GitHub is currently included, but that is
-                        slated to be removed.)
+                        <https://github.com/tpope/vim-rhubarb>.
 
-                        If no upstream support is available, a local instance
-                        of git-instaweb will be started and used instead.
-
-:Gbrowse {revision}     Like :Gbrowse, but for a given |fugitive-revision|.  A
-                        useful value here is -, which ties the URL to the
-                        latest commit rather than a volatile branch.
+:Gbrowse {object}       Like :Gbrowse, but for a given |fugitive-object|.
 
 :Gbrowse [...]@{remote} Force using the given remote rather than the remote
                         for the current branch.  The remote is used to
-                        determine which GitHub repository to link to.
+                        determine which upstream repository to link to.
 
 :{range}Gbrowse [args]  Appends an anchor to the URL that emphasizes the
-                        selected lines.  You almost certainly want to give a
-                        "-" argument in this case to force the URL to include
-                        an exact revision.
+                        selected lines. This also forces the URL to include a
+                        commit rather than a branch name so it remains valid
+                        if the file changes.  You can give a range of "0" to
+                        force this behavior without including an anchor.
 
 :[range]Gbrowse! [args] Like :Gbrowse, but put the URL on the clipboard rather
                         than opening it.
@@ -258,26 +268,29 @@ These maps are available everywhere.
 
                                                 *fugitive-c_CTRL-R_CTRL-G*
 <C-R><C-G>              On the command line, recall the path to the current
-                        object (that is, a representation of the object
-                        recognized by |:Gedit|).
+                        |fugitive-object| (that is, a representation of the
+                        object recognized by |:Gedit|).
 
                                                 *fugitive-y_CTRL-G*
-["x]y<C-G>              Yank the commit SHA and path to the current object.
+["x]y<C-G>              Yank the commit SHA and path to the current
+                        |fugitive-object|.
 
-These maps are available in Git objects.
+These maps are available in committed Git objects.
 
                                                 *fugitive-<CR>*
-<CR>                    Jump to the revision under the cursor.
+<CR>                    Jump to the |fugitive-object| under the cursor.
 
                                                 *fugitive-o*
-o                       Jump to the revision under the cursor in a new split.
+o                       Jump to the |fugitive-object| under the cursor in a
+                        new split.
 
                                                 *fugitive-S*
-S                       Jump to the revision under the cursor in a new
-                        vertical split.
+S                       Jump to the |fugitive-object| under the cursor in a
+                        new vertical split.
 
                                                 *fugitive-O*
-O                       Jump to the revision under the cursor in a new tab.
+O                       Jump to the |fugitive-object| under the cursor in a
+                        new tab.
 
                                                 *fugitive--*
 -                       Go to the tree containing the current tree or blob.
@@ -292,53 +305,51 @@ P                       Go to the current file in the [count]th parent.
                                                 *fugitive-C*
 C                       Go to the commit containing the current file.
 
-                                                *fugitive-.*
-.                       Start a |:| command line with the current revision
-                        prepopulated at the end of the line.
-
                                                 *fugitive-a*
 a                       Show the current tag, commit, or tree in an alternate
                         format.
 
-SPECIFYING REVISIONS                            *fugitive-revision*
+SPECIFYING OBJECTS                      *fugitive-object* *fugitive-revision*
 
-Fugitive revisions are similar to Git revisions as defined in the "SPECIFYING
-REVISIONS" section in the git-rev-parse man page.  For commands that accept an
-optional revision, the default is the file in the index for work tree files
-and the work tree file for everything else.  Example revisions follow.
+Fugitive objects are either work tree files or Git revisions as defined in the
+"SPECIFYING REVISIONS" section in the git-rev-parse man page, with expansions
+inspired by |cmdline-special| layered on top.  For commands that accept an
+optional object, the default is the file in the index for work tree files and
+the work tree file for everything else.  Example objects follow.
 
-Revision        Meaning ~
+Object          Meaning ~
 HEAD            .git/HEAD
-master          .git/refs/heads/master
-HEAD^{}         The commit referenced by HEAD
-HEAD^           The parent of the commit referenced by HEAD
-HEAD:           The tree referenced by HEAD
-/HEAD           The file named HEAD in the work tree
+refs/heads/x    .git/refs/heads/x (in "common dir" if present)
+@               The commit referenced by @ aka HEAD
+master^         The parent of the commit referenced by master
+master:         The tree referenced by master
+./master        The file named master in the working directory
 Makefile        The file named Makefile in the work tree
-HEAD^:Makefile  The file named Makefile in the parent of HEAD
+@^:Makefile     The file named Makefile in the parent of HEAD
 :Makefile       The file named Makefile in the index (writable)
--               The current file in HEAD
-^               The current file in the previous commit
-~3              The current file 3 commits ago
-:               .git/index (Same as |:Gstatus|)
-:0              The current file in the index
-:1              The current file's common ancestor during a conflict
-:2              The current file in the target branch during a conflict
-:3              The current file in the merged branch during a conflict
-:/foo           The most recent commit with "foo" in the message
+@~2:%           The current file in the grandparent of HEAD
+:%              The current file in the index
+:1:%            The current file's common ancestor during a conflict
+:2:#            The alternate file in the target branch during a conflict
+:3:#5           The file from buffer #5 in the merged branch during a conflict
+!               The commit owning the current file
+!:Makefile      The file named Makefile in the commit owning the current file
+!3^2            The second parent of the commit owning buffer #3
+.git/config     The repo config file
+:               Same as |:Gstatus|
 
 STATUSLINE                                      *fugitive-statusline*
 
-                                                *fugitive#statusline()*
-Add %{fugitive#statusline()} to your statusline to get an indicator including
+                                *FugitiveStatusline()* *fugitive#statusline()*
+Add %{FugitiveStatusline()} to your statusline to get an indicator including
 the current branch and the currently edited file's commit.  If you don't have
 a statusline, this one matches the default when 'ruler' is set:
 >
-    set statusline=%<%f\ %h%m%r%{fugitive#statusline()}%=%-14.(%l,%c%V%)\ %P
+    set statusline=%<%f\ %h%m%r%{FugitiveStatusline()}%=%-14.(%l,%c%V%)\ %P
 <
-                                                *fugitive#head(...)*
-Use fugitive#head() to return the name of the current branch. If the current
-HEAD is detached, fugitive#head() will return the empty string, unless the
+                                *FugitiveHead(...)* *fugitive#head(...)*
+Use FugitiveHead() to return the name of the current branch. If the current
+HEAD is detached, FugitiveHead() will return the empty string, unless the
 optional argument is given, in which case the hash of the current commit will
 be truncated to the given number of characters.
 

ftdetect/fugitive.vim

@@ -0,0 +1 @@
+autocmd BufReadPost *.fugitiveblame setfiletype fugitiveblame