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 1890 additions and 675 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
@@ -43,14 +42,32 @@ GitHub, `git instaweb` will be spun up instead.
 Add `%{fugitive#statusline()}` to `'statusline'` to get an indicator
 with the current branch in (surprise!) your statusline.
-Oh, and of course there's `:Git` for running any arbitrary command.
+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.
-Like fugitive.vim? Follow the repository on
+## Screencasts
 [GitHub](http://github.com/tpope/vim-fugitive) and vote for it on
 [vim.org](http://www.vim.org/scripts/script.php?script_id=2975).
-FAQ
+* [A complement to command line git](http://vimcasts.org/e/31)
---
+* [Working with the git index](http://vimcasts.org/e/32)
 * [Resolving merge conflicts with vimdiff](http://vimcasts.org/e/33)
 * [Browsing the git object database](http://vimcasts.org/e/34)
 * [Exploring the history of a git repository](http://vimcasts.org/e/35)
 ## Installation
 If you don't have a preferred installation method, one option is to install
 [pathogen.vim](https://github.com/tpope/vim-pathogen), and then copy
 and paste:
    cd ~/.vim/bundle
    git clone git://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
 [vim-git](https://github.com/tpope/vim-git) for syntax highlighting and
 other Git niceties.
 ## FAQ
 > I installed the plugin and started Vim.  Why don't any of the commands
 > exist?
@@ -63,8 +80,39 @@ directory.  Edit a file from the repository.
 Fugitive cares about the current file, not the current working
 directory.  Edit a file from the repository.
-> I changed the current working directory.  Why do all the commands use
+> Why is `:Gbrowse` not using the right browser?
 > the old directory?
-Fugitive cares about the current file, not the current working
+`:Gbrowse` delegates to `git web--browse`, which is less than perfect
-directory.  Edit a file from the repository.
+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.
 > Here's a patch that automatically opens the quickfix window after
 > `:Ggrep`.
 This is a great example of why I recommend asking before patching.
 There are valid arguments to be made both for and against automatically
 opening the quickfix window.  Whenever I have to make an arbitrary
 decision like this, I ask what Vim would do.  And Vim does not open a
 quickfix window after `:grep`.
 Luckily, it's easy to implement the desired behavior without changing
 fugitive.vim.  The following autocommand will cause the quickfix window
 to open after any grep invocation:
    autocmd QuickFixCmdPost *grep* cwindow
 ## Self-Promotion
 Like fugitive.vim? Follow the repository on
 [GitHub](https://github.com/tpope/vim-fugitive) and vote for it on
 [vim.org](http://www.vim.org/scripts/script.php?script_id=2975).  And if
 you're feeling especially charitable, follow [tpope](http://tpo.pe/) on
 [Twitter](http://twitter.com/tpope) and
 [GitHub](https://github.com/tpope).
 ## License
 Copyright (c) Tim Pope.  Distributed under the same terms as Vim itself.
 See `:help license`.
@@ -1,38 +1,14 @@
 *fugitive.txt*  A Git wrapper so awesome, it should be illegal
-Author:  Tim Pope <vimNOSPAM@tpope.org>         *fugitive-author*
+Author:  Tim Pope <http://tpo.pe/>
 License: Same terms as Vim itself (see |license|)
 This plugin is only available if 'compatible' is not set.
 INTRODUCTION                                    *fugitive*
-Install in ~/.vim, or in ~\vimfiles if you're on Windows and feeling lucky.
+Whenever you edit a file from a Git repository, a set of commands is defined
-Vim 7.2 is recommended as it ships with syntax highlighting for many Git file
+that serve as a gateway to Git.
 types.
 If you're in a hurry to get started, here are some things to try:
 In any file in your repository, run |:Gedit| HEAD.  Press <CR> to jump to the
 current branch.  Press <CR> again to jump to the top most commit.  Keep using
 <CR> to explore parent commits, trees, and blobs.  Use C in a tree or blob to
 get back to the commit.
 Edit a file in the work tree and make some changes.  Use |:Gdiff| to open up
 the indexed version.  Use |do| and |dp| on various hunks to bring the files in
 sync, or use |:Gread| to pull in all changes.  Write the indexed version to
 stage the file.
 Run |:Gstatus| to check your repository's status.  Use "-" to stage and reset
 files and "p" to add/reset --patch them.  Invoke |:Gcommit| to commit your
 changes.
 Run |:Gblame| in a work tree file to see a blame in a vertical split.  Press
 <CR> on any line to reopen and reblame that file as it stood in that commit.
 Press o or O on any line to inspect that commit in a split or a tab.
 Run |:Ggrep| to search the work tree or history.  Run |:Gmove| to rename a
 file.  Run |:Gremove| to delete a file.
 COMMANDS                                        *fugitive-commands*
@@ -43,6 +19,10 @@ that are part of Git repositories).
 :Git [args]             Run an arbitrary git command. Similar to :!git [args]
                        but chdir to the repository tree first.
                                                *fugitive-:Git!*
 :Git! [args]            Like |:Git|, but capture the output into a temp file,
                        and edit that temp file.
                                                *fugitive-:Gcd*
 :Gcd [directory]        |:cd| relative to the repository.
@@ -51,37 +31,87 @@ that are part of Git repositories).
                                                *fugitive-:Gstatus*
 :Gstatus                Bring up the output of git-status in the preview
-                        window.  In addition to standard motions, you can
+                        window.  The following maps, which work on the cursor
-                        use <C-N> and <C-P> to jump from filename to
+                        line file where sensible, are provided:
-                        filename.  Press C to invoke |:Gcommit|.  Press D to
+
-                        |:Gdiff| the file on the cursor line, or ds to
+                        g?    show this help
-                        |:Gsdiff|.  Press - to stage or unstage the file on
+                        <C-N> next file
-                        the cursor line.  Press p to do so on a per hunk basis
+                        <C-P> previous file
-                        (--patch).  All of D, -, and p have a different,
+                        <CR>  |:Gedit|
-                        sensible (and hopefully intuitive) behavior when
+                        -     |:Git| add
-                        invoked on a heading rather than a file name.
+                        -     |:Git| reset (staged files)
                        cA    |:Gcommit| --amend --reuse-message=HEAD
                        ca    |:Gcommit| --amend
                        cc    |:Gcommit|
                        cva   |:Gcommit| --amend --verbose
                        cvc   |:Gcommit| --verbose
                        D     |:Gdiff|
                        ds    |:Gsdiff|
                        dp    |:Git!| diff (p for patch; use :Gw to apply)
                        dp    |:Git| add --intent-to-add (untracked files)
                        dv    |:Gvdiff|
                        O     |:Gtabedit|
                        o     |:Gsplit|
                        p     |:Git| add --patch
                        p     |:Git| reset --patch (staged files)
                        q     close status
                        r     reload status
                        S     |:Gvsplit|
                                                *fugitive-:Gcommit*
 :Gcommit [args]         A wrapper around git-commit.  If there is nothing
                        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'.
                                                *fugitive-:Glgrep*
 :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
                        be given (for example, --reverse).  If "--" appears as
                        an argument, no file specific filtering is done, and
-                        commits are loaded into the quickfix list.
+                        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.
                                        *fugitive-:Gedit* *fugitive-:Ge*
 :Gedit [revision]       |:edit| a |fugitive-revision|.
@@ -93,10 +123,15 @@ that are part of Git repositories).
 :Gvsplit [revision]     |:vsplit| a |fugitive-revision|.
                                                *fugitive-:Gtabedit*
-:Gtabedit [revision]    |:tabedit| a |fugitive-revision|
+:Gtabedit [revision]    |:tabedit| a |fugitive-revision|.
                                                *fugitive-:Gpedit*
-:Gpedit [revision]      |:pedit| a |fugitive-revision|
+:Gpedit [revision]      |:pedit| a |fugitive-revision|.
 :Gsplit! [args]                 *fugitive-:Gsplit!* *fugitive-:Gvsplit!*
 :Gvsplit! [args]                *fugitive-:Gtabedit!* *fugitive-:Gpedit!*
 :Gtabedit! [args]       Like |:Git!|, but open the resulting temp file in a
 :Gpedit! [args]         split, tab, or preview window.
                                                *fugitive-:Gread*
 :Gread [revision]       Empty the buffer and |:read| a |fugitive-revision|.
@@ -107,7 +142,13 @@ that are part of Git repositories).
 :{range}Gread [revision]
                        |:read| in a |fugitive-revision| after {range}.
-                                                *fugitive-:Gwrite*
+                                                *fugitive-:Gread!*
 :Gread! [args]          Empty the buffer and |:read| the output of a Git
                        command.  For example, :Gread! show HEAD:%.
 :{range}Gread! [args]  |:read| the output of a Git command after {range}.
                                        *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
@@ -133,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
@@ -156,37 +199,73 @@ 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 ltwfsMC as flags and they will be passed
+                        git-blame.  The following maps, which work on the
-                        along to git-blame.
+                        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
                        <CR>  q, then open commit
                        o     open commit in horizontal split
                        O     open commit in new tab
                        -     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*
-:[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.
-:[range]Gbrowse!        Like :Gbrowse, but put the URL on the clipboard rather
+                        Upstream providers can be added by installing an
-                        than opening it.
+                        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.)
-:[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.
                                                *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-y_CTRL-G*
 ["x]y<C-G>              Yank the commit SHA and path to the current object.
 These maps are available in Git objects.
                                                *fugitive-<CR>*
@@ -195,9 +274,16 @@ These maps are available in Git objects.
                                                *fugitive-o*
 o                       Jump to the revision under the cursor in a new split.
                                                *fugitive-S*
 S                       Jump to the revision under the cursor in a new
                        vertical split.
                                                *fugitive-O*
 O                       Jump to the revision under the cursor in a new tab.
                                                *fugitive--*
 -                       Go to the tree containing the current tree or blob.
                                                *fugitive-~*
 ~                       Go to the current file in the [count]th first
                        ancestor.
@@ -208,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.
@@ -248,6 +338,12 @@ a statusline, this one matches the default when 'ruler' is set:
 >
    set statusline=%<%f\ %h%m%r%{fugitive#statusline()}%=%-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
 optional argument is given, in which case the hash of the current commit will
 be truncated to the given number of characters.
 ABOUT                                           *fugitive-about*
 Grab the latest version or report a bug on GitHub: