README.markdown

   1 # fugitive.vim
   2
   3 Fugitive is the premier Vim plugin for Git.  Or maybe it's the premier Git
   4 plugin for Vim?  Either way, it's "so awesome, it should be illegal".  That's
   5 why it's called Fugitive.
   6
   7 The crown jewel of Fugitive is `:Git` (or just `:G`), which calls any
   8 arbitrary Git command.  If you know how to use Git at the command line, you
   9 know how to use `:Git`.  It's vaguely akin to `:!git` but with numerous
  10 improvements:
  11
  12 * The default behavior is to directly echo the command's output.  Quiet
  13   commands like `:Git add` avoid the dreaded "Press ENTER or type command to
  14   continue" prompt.
  15 * `:Git commit`, `:Git rebase -i`, and other commands that invoke an editor do
  16   their editing in the current Vim instance.
  17 * `:Git diff`, `:Git log`, and other verbose, paginated commands have their
  18   output loaded into a temporary buffer.  Force this behavior for any command
  19   with `:Git --paginate` or `:Git -p`.
  20 * `:Git blame` uses a temporary buffer with maps for additional triage.  Press
  21   enter on a line to view the commit where the line changed, or `g?` to see
  22   other available maps.  Omit the filename argument and the currently edited
  23   file will be blamed in a vertical, scroll-bound split.
  24 * `:Git mergetool` and `:Git difftool` load their changesets into the quickfix
  25   list.
  26 * Called with no arguments, `:Git` opens a summary window with dirty files and
  27   unpushed and unpulled commits.  Press `g?` to bring up a list of maps for
  28   numerous operations including diffing, staging, committing, rebasing, and
  29   stashing.  (This is the successor to the old `:Gstatus`.)
  30 * This command (along with all other commands) always uses the current
  31   buffer's repository, so you don't need to worry about the current working
  32   directory.
  33
  34 Additional commands are provided for higher level operations:
  35
  36 * View any blob, tree, commit, or tag in the repository with `:Gedit` (and
  37   `:Gsplit`, etc.).  For example, `:Gedit HEAD~3:%` loads the current file as
  38   it existed 3 commits ago.
  39 * `:Gdiffsplit` (or `:Gvdiffsplit`) brings up the staged version of the file
  40   side by side with the working tree version.  Use Vim's diff handling
  41   capabilities to apply changes to the staged version, and write that buffer
  42   to stage the changes.  You can also give an arbitrary `:Gedit` argument to
  43   diff against older versions of the file.
  44 * `:Gread` is a variant of `git checkout -- filename` that operates on the
  45   buffer rather than the file itself.  This means you can use `u` to undo it
  46   and you never get any warnings about the file changing outside Vim.
  47 * `:Gwrite` writes to both the work tree and index versions of a file, making
  48   it like `git add` when called from a work tree file and like `git checkout`
  49   when called from the index or a blob in history.
  50 * `:Ggrep` is `:grep` for `git grep`.  `:Glgrep` is `:lgrep` for the same.
  51 * `:GMove` does a `git mv` on the current file and changes the buffer name to
  52   match.  `:GRename` does the same with a destination filename relative to the
  53   current file's directory.
  54 * `:GDelete` does a `git rm` on the current file and simultaneously deletes
  55   the buffer.  `:GRemove` does the same but leaves the (now empty) buffer
  56   open.
  57 * `:GBrowse` to open the current file on the web front-end of your favorite
  58   hosting provider, with optional line range (try it in visual mode).  Plugins
  59   are available for popular providers such as [GitHub][rhubarb.vim],
  60   [GitLab][fugitive-gitlab.vim], [Bitbucket][fubitive.vim],
  61   [Gitee][fugitive-gitee.vim], [Pagure][pagure],
  62   [Phabricator][vim-phabricator], [Azure DevOps][fugitive-azure-devops.vim],
  63   and [sourcehut][srht.vim].
  64
  65 [rhubarb.vim]: https://github.com/tpope/vim-rhubarb
  66 [fugitive-gitlab.vim]: https://github.com/shumphrey/fugitive-gitlab.vim
  67 [fubitive.vim]: https://github.com/tommcdo/vim-fubitive
  68 [fugitive-gitee.vim]: https://github.com/linuxsuren/fugitive-gitee.vim
  69 [pagure]: https://github.com/FrostyX/vim-fugitive-pagure
  70 [vim-phabricator]: https://github.com/jparise/vim-phabricator
  71 [fugitive-azure-devops.vim]: https://github.com/cedarbaum/fugitive-azure-devops.vim
  72 [srht.vim]: https://git.sr.ht/~willdurand/srht.vim
  73
  74 Add `%{FugitiveStatusline()}` to `'statusline'` to get an indicator
  75 with the current branch in your statusline.
  76
  77 For more information, see `:help fugitive`.
  78
  79 ## Screencasts
  80
  81 * [A complement to command line git](http://vimcasts.org/e/31)
  82 * [Working with the git index](http://vimcasts.org/e/32)
  83 * [Resolving merge conflicts with vimdiff](http://vimcasts.org/e/33)
  84 * [Browsing the git object database](http://vimcasts.org/e/34)
  85 * [Exploring the history of a git repository](http://vimcasts.org/e/35)
  86
  87 ## Installation
  88
  89 Install using your favorite package manager, or use Vim's built-in package
  90 support:
  91
  92     mkdir -p ~/.vim/pack/tpope/start
  93     cd ~/.vim/pack/tpope/start
  94     git clone https://tpope.io/vim/fugitive.git
  95     vim -u NONE -c "helptags fugitive/doc" -c q
  96
  97 ## FAQ
  98
  99 > What happened to the dispatch.vim backed asynchronous `:Gpush` and
 100 > `:Gfetch`?
 101
 102 This behavior was divisive, confusing, and complicated inputting passwords, so
 103 it was removed.  Use `:Git! push` to use Fugitive's own asynchronous
 104 execution, or retroactively make `:Git push` asynchronous by pressing
 105 `CTRL-D`.
 106
 107 > Why am I getting `core.worktree is required when using an external Git dir`?
 108
 109 Git generally sets `core.worktree` for you automatically when necessary, but
 110 if you're doing something weird, or using a third-party tool that does
 111 something weird, you may need to set it manually:
 112
 113     git config core.worktree "$PWD"
 114
 115 This may be necessary even when simple `git` commands seem to work fine
 116 without it.
 117
 118 > So I have a symlink and...
 119
 120 Stop.  Just stop.  If Git won't deal with your symlink, then Fugitive won't
 121 either.  Consider using a [plugin that resolves
 122 symlinks](https://github.com/aymericbeaumet/symlink.vim), or even better,
 123 using fewer symlinks.
 124
 125 ## Self-Promotion
 126
 127 Like fugitive.vim? Follow the repository on
 128 [GitHub](https://github.com/tpope/vim-fugitive) and vote for it on
 129 [vim.org](http://www.vim.org/scripts/script.php?script_id=2975).  And if
 130 you're feeling especially charitable, follow [tpope](http://tpo.pe/) on
 131 [Twitter](http://twitter.com/tpope) and
 132 [GitHub](https://github.com/tpope).
 133
 134 ## License
 135
 136 Copyright (c) Tim Pope.  Distributed under the same terms as Vim itself.
 137 See `:help license`.