diff --git a/README.markdown b/README.markdown index 6948fd9..6af99e8 100644 --- a/README.markdown +++ b/README.markdown @@ -1,54 +1,65 @@ # 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: +Fugitive is the premiere Vim plugin for Git. Or maybe it's the premiere Git +plugin for Vim? Either way, it's "so awesome, it should be illegal". That's +why it's called Fugitive. -Bring up an enhanced version of `git status` with `:G` (also known as -`:Gstatus`). Press `g?` to bring up a list of maps for numerous operations -including diffing, staging, committing, rebasing, and stashing. +The crown jewel of Fugitive is `:Git` (or just `:G`), which calls any +arbitrary Git command. If you know how to use Git at the command line, you +know how to use `:Git`. It's vaguely akin to `:!git` but with numerous +improvements: -View any blob, tree, commit, or tag in the repository with `:Gedit` (and -`:Gsplit`, `:Gvsplit`, `:Gtabedit`, ...). Edit a file in the index and -write to it to stage the changes. Use `:Gdiffsplit` to bring up the staged -version of the file side by side with the working tree version and use -Vim's diff handling capabilities to stage a subset of the file's -changes. +* The default behavior is to directly echo the command's output. Quiet + commands like `:Git add` avoid the dreaded "Press ENTER or type command to + continue" prompt. +* `:Git commit`, `:Git rebase -i`, and other commands that invoke an editor do + their editing in the current Vim instance. +* `:Git diff`, `:Git log`, and other verbose, paginated commands have their + output loaded into a temporary buffer. Force this behavior for any command + with `:Git --paginate` or `:Git -p`. +* `:Git blame` uses a temporary buffer with maps for additional triage. Press + enter on a line to view the commit where the line changed, or `g?` to see + other available maps. Omit the filename argument and the currently edited + file will be blamed in a vertical, scroll-bound split. +* `:Git grep` loads matches into the quickfix list, just like `:grep`. +* `:Git mergetool` and `:Git difftool` load their changesets into the quickfix + list. +* Called with no arguments, `:Git` opens a summary window with dirty files and + unpushed and unpulled commits. Press `g?` to bring up a list of maps for + numerous operations including diffing, staging, committing, rebasing, and + stashing. (This is the successor to the old `:Gstatus`.) +* This command (along with all other commands) always uses the current + buffer's repository, so you don't need to worry about the current working + directory. -Commit, merge, and rebase with `:Gcommit`, `:Gmerge`, and `:Grebase`, using -the current Vim instance to edit commit messages and the rebase todo list. -Use `:Gpush`, `:Gfetch`, and `:Gpull` to send and retrieve upstream changes. +Additional commands are provided for higher level operations: -`:Gblame` brings up an interactive vertical split with `git blame` -output. Press enter on a line to edit the commit where the line -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. `: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 -`git grep`, skipping over that which is not tracked in the repository. -`:Gclog` and `:Gllog` load all previous commits into the quickfix or location -list. Give them a range (e.g., using visual mode and `:'<,'>Gclog`) to -iterate over every change to that portion of the current file. - -`:Git mergetool` loads conflicts into the quickfix list. `:Git difftool` does -the same for any arbitrary set of changes. - -`:Gread` is a variant of `git checkout -- filename` that operates on the -buffer rather than the filename. This means you can use `u` to undo it -and you never get any warnings about the file changing outside Vim. -`:Gwrite` writes to both the work tree and index versions of a file, -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 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], [Bitbucket][fubitive.vim], -[Gitee][fugitive-gitee.vim], [Pagure][pagure], and -[Phabricator][vim-phabricator]. +* View any blob, tree, commit, or tag in the repository with `:Gedit` (and + `:Gsplit`, etc.). For example, `:Gedit HEAD~3:%` loads the current file as + it existed 3 commits ago. +* `:Gdiffsplit` brings up the staged version of the file side by side with the + working tree version. Use Vim's diff handling capabilities to apply changes + to the staged version, and write that buffer to stage the changes. You can + also give an arbitrary `:Gedit` argument to diff against older versions of + the file. +* `:Gread` is a variant of `git checkout -- filename` that operates on the + buffer rather than the file itself. This means you can use `u` to undo it + and you never get any warnings about the file changing outside Vim. +* `:Gwrite` writes to both the work tree and index versions of a file, 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. +* `:GMove` does a `git mv` on the current file and changes the buffer name to + match. `:GRename` does the same with a destination filename relative to the + current file's directory. +* `:GDelete` does a `git rm` on the current file and simultaneously deletes + the buffer. `:GRemove` does the same but leaves the (now empty) buffer + open. +* `: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], [Bitbucket][fubitive.vim], + [Gitee][fugitive-gitee.vim], [Pagure][pagure], and + [Phabricator][vim-phabricator]. [rhubarb.vim]: https://github.com/tpope/vim-rhubarb [fugitive-gitlab.vim]: https://github.com/shumphrey/fugitive-gitlab.vim @@ -60,8 +71,6 @@ are available for popular providers such as [GitHub][rhubarb.vim], Add `%{FugitiveStatusline()}` to `'statusline'` to get an indicator with the current branch in your statusline. -Last but not least, there's `:Git` for running any arbitrary command. - For more information, see `:help fugitive`. ## Screencasts @@ -83,7 +92,7 @@ Install using your favorite package manager, or use Vim's built-in package suppo ## FAQ -> Why can't I enter my password when I `:Gpush`? +> Why can't I enter my password when I `:Git push`? It is highly recommended to use SSH keys or [credentials caching][] to avoid entering your password on every upstream interaction. If this isn't an