Support worktrees

Closes https://github.com/tpope/vim-fugitive/issues/655
DRY up refs/ paths
2026-04-25 16:44:13 +08:00 · 2016-02-24 16:20:52 -05:00 · 2016-02-24 15:53:51 -05:00 · 2016-01-22 20:03:58 -05:00 · 2016-01-08 17:05:54 -05:00 · 2016-01-01 16:55:17 -05:00
4 changed files with 1076 additions and 493 deletions
@@ -0,0 +1,18 @@
 Before reporting a bug, you should try stripping down your Vim configuration
 and removing other plugins.  The sad truth about VimScript is that it is
 fraught with incompatibilities waiting to happen.  I'm happy to work around
 them where I can, but it's up to you to isolate the conflict.
 Fugitive is particularly prone to regressions due to Git version issues,
 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.
 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
 perverse knowledge of VimScript so vast that many would consider it a symptom
 of mental illness.  On the flip side, some ideas I'll reject no matter how
 good the implementation is.  "Send a patch" is an edge case answer in my book.
@@ -1,5 +1,4 @@
-fugitive.vim
+# fugitive.vim
 ============
 I'm not going to lie to you; fugitive.vim may very well be the best
 Git wrapper of all time.  Check out these features:
@@ -12,13 +11,13 @@ 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` that
+`add`/`reset` a file's changes, or `p` to `add`/`reset` `--patch`.  And guess
-mofo.  And guess what `:Gcommit` does!
+what `:Gcommit` does!
 `:Gblame` brings up an interactive vertical split with `git blame`
-output.  Press enter on a line to reblame the file as it stood in that
+output.  Press enter on a line to edit the commit where the line
-commit, or `o` to open that commit in a split.  When you're done, use
+changed, or `o` to open it in a split.  When you're done, use `:Gedit`
-`:Gedit` in the historic buffer to go back to the work tree version.
+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
@@ -46,8 +45,7 @@ with the current branch in (surprise!) your statusline.
 Last but not least, there's `:Git` for running any arbitrary command,
 and `Git!` to open the output of a command in a temp file.
-Screencasts
+## Screencasts
 -----------
 * [A complement to command line git](http://vimcasts.org/e/31)
 * [Working with the git index](http://vimcasts.org/e/32)
@@ -55,25 +53,21 @@ Screencasts
 * [Browsing the git object database](http://vimcasts.org/e/34)
 * [Exploring the history of a git repository](http://vimcasts.org/e/35)
-Installation
+## Installation
 ------------
-If you don't have a preferred installation method, I recommend
+If you don't have a preferred installation method, one option is to install
-installing [pathogen.vim](https://github.com/tpope/vim-pathogen), and
+[pathogen.vim](https://github.com/tpope/vim-pathogen), and then copy
-then simply copy and paste:
+and paste:
    cd ~/.vim/bundle
    git clone git://github.com/tpope/vim-fugitive.git
-
+    vim -u NONE -c "helptags vim-fugitive/doc" -c q
 Once help tags have been generated, you can view the manual with
 `:help fugitive`.
 If your Vim version is below 7.2, I recommend also installing
 [vim-git](https://github.com/tpope/vim-git) for syntax highlighting and
 other Git niceties.
-FAQ
+## FAQ
 ---
 > I installed the plugin and started Vim.  Why don't any of the commands
 > exist?
@@ -109,32 +103,7 @@ to open after any grep invocation:
    autocmd QuickFixCmdPost *grep* cwindow
-Contributing
+## Self-Promotion
 ------------
 Before reporting a bug, you should try stripping down your Vim
 configuration and removing other plugins.  The sad nature of VimScript
 is that it is fraught with incompatibilities waiting to happen.  I'm
 happy to work around them where I can, but it's up to you to isolate
 the conflict.
 If your [commit message sucks](http://stopwritingramblingcommitmessages.com/),
 I'm not going to accept your pull request.  I've explained very politely
 dozens of times that
 [my general guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
 are absolute rules on my own repositories, so I may lack the energy to
 explain it to you yet another time.  And please, if I ask you to change
 something, `git commit --amend`.
 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 perverse knowledge of VimScript so vast that many would consider
 it a symptom of mental illness.  On the flip side, some ideas I'll
 reject no matter how good the implementation is.  "Send a patch" is an
 edge case answer in my book.
 Self-Promotion
 --------------
 Like fugitive.vim? Follow the repository on
 [GitHub](https://github.com/tpope/vim-fugitive) and vote for it on
@@ -143,8 +112,7 @@ you're feeling especially charitable, follow [tpope](http://tpo.pe/) on
 [Twitter](http://twitter.com/tpope) and
 [GitHub](https://github.com/tpope).
-License
+## License
 -------
 Copyright (c) Tim Pope.  Distributed under the same terms as Vim itself.
 See `:help license`.
@@ -34,6 +34,7 @@ that are part of Git repositories).
                        window.  The following maps, which work on the cursor
                        line file where sensible, are provided:
                        g?    show this help
                        <C-N> next file
                        <C-P> previous file
                        <CR>  |:Gedit|
@@ -54,7 +55,7 @@ that are part of Git repositories).
                        p     |:Git| add --patch
                        p     |:Git| reset --patch (staged files)
                        q     close status
-                        R     reload status
+                        r     reload status
                        S     |:Gvsplit|
                                                *fugitive-:Gcommit*
@@ -62,12 +63,32 @@ that are part of Git repositories).
                        to commit, |:Gstatus| is called instead.  Unless the
                        arguments given would skip the invocation of an editor
                        (e.g., -m), a split window will be used to obtain a
-                        commit message.  Write and close that window (:wq or
+                        commit message, or a new tab if -v is given.  Write
-                        |:Gwrite|) to finish the commit.  Unlike when running
+                        and close that window (:wq or |:Gwrite|) to finish the
-                        the actual git-commit command, it is possible (but
+                        commit.  Unlike when running the actual git-commit
-                        unadvisable) to muck with the index with commands like
+                        command, it is possible (but unadvisable) to alter the
-                        git-add and git-reset while a commit message is
+                        index with commands like git-add and git-reset while a
-                        pending.
+                        commit message is pending.
                                                *fugitive-:Gmerge*
 :Gmerge [args]          Calls git-merge and loads errors and conflicted files
                        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.
                                                *fugitive-:Gpull*
 :Gpull [args]           Like |:Gmerge|, but for git-pull.
                                                *fugitive-:Gpush*
 :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.
                                                *fugitive-:Gfetch*
 :Gfetch [args]          Like |:Gpush|, but for git-fetch.
                                                *fugitive-:Ggrep*
 :Ggrep [args]           |:grep| with git-grep as 'grepprg'.
@@ -83,6 +104,11 @@ that are part of Git repositories).
                        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.
                                                *fugitive-:Gllog*
 :Gllog [args]           Like |:Glog|, but use the location list instead of the
                        quickfix list.
@@ -122,7 +148,7 @@ that are part of Git repositories).
 :{range}Gread! [args]  |:read| the output of a Git command after {range}.
-                                                *fugitive-:Gwrite*
+                                        *fugitive-:Gw* *fugitive-:Gwrite*
 :Gwrite                 Write to the current file's path and stage the results.
                        When run in a work tree file, it is effectively git
                        add.  Elsewhere, it is effectively git-checkout.  A
@@ -148,14 +174,16 @@ that are part of Git repositories).
                        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.  Use |do| and |dp| and write to the
+                        to the right or bottom, depending on 'diffopt' and
-                        index file to simulate "git add --patch".
+                        the width of the window relative to 'textwidth'.  Use
                        |do| and |dp| and write to the index file to simulate
                        "git add --patch".
                                                *fugitive-:Gsdiff*
-:Gsdiff [revision]      Like |:Gdiff|, but split horizontally.
+:Gsdiff [revision]      Like |:Gdiff|, but always split horizontally.
                                                *fugitive-:Gvdiff*
-:Gvdiff [revision]      Identical to |:Gdiff|.  For symmetry with |:Gsdiff|.
+:Gvdiff [revision]      Like |:Gdiff|, but always split vertically.
                                                *fugitive-:Gmove*
 :Gmove {destination}    Wrapper around git-mv that renames the buffer
@@ -171,18 +199,18 @@ that are part of Git repositories).
                                                *fugitive-:Gblame*
 :Gblame [flags]         Run git-blame on the file and open the results in a
-                        scroll bound vertical split.  Press enter on a line to
+                        scroll bound vertical split.  You can give any of
-                        reblame the file as it was in that commit.  You can
+                        ltfnsewMC as flags and they will be passed along to
-                        give any of ltfnsewMC as flags and they will be passed
+                        git-blame.  The following maps, which work on the
-                        along to git-blame.  The following maps, which work on
+                        cursor line commit where sensible, are provided:
                        the cursor line commit where sensible, are provided:
                        g?    show this help
                        A     resize to end of author column
                        C     resize to end of commit column
                        D     resize to end of date/time column
                        q     close blame and return to blamed window
                        gq    q, then |:Gedit| to return to work tree version
-                        i     q, then open commit
+                        <CR>  q, then open commit
                        o     open commit in horizontal split
                        O     open commit in new tab
                        -     reblame at commit
@@ -192,32 +220,40 @@ that are part of Git repositories).
 :[range]Gblame [flags]  Run git-blame on the given range.
                                                *fugitive-:Gbrowse*
-:[range]Gbrowse         If the remote for the current branch is on GitHub,
+:Gbrowse                Open the current file, blob, tree, commit, or tag
-                        open the current file, blob, tree, commit, or tag
+                        in your browser at the upstream hosting provider.
-                        (with git-web--browse) on GitHub.  Otherwise, open the
+                        If a range is given, it is appropriately appended to
-                        current file, blob, tree, commit, or tag in
+                        the URL as an anchor.
                        git-instaweb (if you have issues, verify you can run
                        "git instaweb" from a terminal).  If a range is given,
                        it is appropriately appended to the URL as an anchor.
-                        To use with GitHub FI, point g:fugitive_github_domains
+                        Upstream providers can be added by installing an
-                        at a list of domains:
+                        appropriate Vim plugin.  For example, GitHub can be
->
+                        supported by installing rhubarb.vim, available at
-                        let g:fugitive_github_domains = ['git.example.com']
+                        <https://github.com/tpope/vim-rhubarb>.  (Native
-~
+                        support for GitHub is currently included, but that is
-:[range]Gbrowse!        Like :Gbrowse, but put the URL on the clipboard rather
+                        slated to be removed.)
                        than opening it.
-:[range]Gbrowse {revision}
+                        The hosting provider is determined by looking at the
-                        Like :Gbrowse, but for a given |fugitive-revision|.  A
+                        remote for the current or specified branch and falls
                        back to "origin".  In the special case of a "."
                        remote, a local instance of git-instaweb will be
                        started and used.
 :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.
-:[range]Gbrowse [...]@{remote}
+:Gbrowse [...]@{remote} Force using the given remote rather than the 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.
 :{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.
 :[range]Gbrowse! [args] Like :Gbrowse, but put the URL on the clipboard rather
                        than opening it.
 MAPPINGS                                        *fugitive-mappings*
 These maps are available everywhere.
@@ -258,6 +294,10 @@ 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.