doc/fugitive.txt

   1 *fugitive.txt*  A Git wrapper so awesome, it should be illegal
   2
   3 Author:  Tim Pope <http://tpo.pe/>
   4 License: Same terms as Vim itself (see |license|)
   5
   6 This plugin is only available if 'compatible' is not set.
   7
   8 INTRODUCTION                                    *fugitive*
   9
  10 Whenever you edit a file from a Git repository, a set of commands is defined
  11 that serve as a gateway to Git.
  12
  13 COMMANDS                                        *fugitive-commands*
  14
  15 These commands are local to the buffers in which they work (generally, buffers
  16 that are part of Git repositories).
  17
  18                                                 *fugitive-:Git*
  19 :Git [args]             Run an arbitrary git command. Similar to :!git [args]
  20                         but chdir to the repository tree first.
  21
  22                                                 *fugitive-:Git!*
  23 :Git! [args]            Like |:Git|, but capture the output into a temp file,
  24                         and edit that temp file.
  25
  26                                                 *fugitive-:Gcd*
  27 :Gcd [directory]        |:cd| relative to the repository.
  28
  29                                                 *fugitive-:Glcd*
  30 :Glcd [directory]       |:lcd| relative to the repository.
  31
  32                                                 *fugitive-:Gstatus*
  33 :Gstatus                Bring up the output of git-status in the preview
  34                         window.  The following maps, which work on the cursor
  35                         line file where sensible, are provided:
  36
  37                         g?    show this help
  38                         <C-N> next file
  39                         <C-P> previous file
  40                         <CR>  |:Gedit|
  41                         -     |:Git| add
  42                         -     |:Git| reset (staged files)
  43                         cA    |:Gcommit| --amend --reuse-message=HEAD
  44                         ca    |:Gcommit| --amend
  45                         cc    |:Gcommit|
  46                         cva   |:Gcommit| --amend --verbose
  47                         cvc   |:Gcommit| --verbose
  48                         D     |:Gdiff|
  49                         ds    |:Gsdiff|
  50                         dp    |:Git!| diff (p for patch; use :Gw to apply)
  51                         dp    |:Git| add --intent-to-add (untracked files)
  52                         dv    |:Gvdiff|
  53                         O     |:Gtabedit|
  54                         o     |:Gsplit|
  55                         p     |:Git| add --patch
  56                         p     |:Git| reset --patch (staged files)
  57                         q     close status
  58                         r     reload status
  59                         S     |:Gvsplit|
  60
  61                                                 *fugitive-:Gcommit*
  62 :Gcommit [args]         A wrapper around git-commit.  If there is nothing
  63                         to commit, |:Gstatus| is called instead.  Unless the
  64                         arguments given would skip the invocation of an editor
  65                         (e.g., -m), a split window will be used to obtain a
  66                         commit message, or a new tab if -v is given.  Write
  67                         and close that window (:wq or |:Gwrite|) to finish the
  68                         commit.  Unlike when running the actual git-commit
  69                         command, it is possible (but unadvisable) to alter the
  70                         index with commands like git-add and git-reset while a
  71                         commit message is pending.
  72
  73                                                 *fugitive-:Gmerge*
  74 :Gmerge [args]          Calls git-merge and loads errors and conflicted files
  75                         into the quickfix list.  Opens a |:Gcommit| style
  76                         split window for the commit message if the merge
  77                         succeeds.  If called during a merge conflict, the
  78                         conflicted files from the current index are loaded
  79                         into the quickfix list.
  80
  81                                                 *fugitive-:Gpull*
  82 :Gpull [args]           Like |:Gmerge|, but for git-pull.
  83
  84                                                 *fugitive-:Gpush*
  85 :Gpush [args]           Invoke git-push, load the results into the quickfix
  86                         list, and invoke |:cwindow| to reveal any errors.
  87                         |:Dispatch| is used if available for asynchronous
  88                         invocation.
  89
  90                                                 *fugitive-:Gfetch*
  91 :Gfetch [args]          Like |:Gpush|, but for git-fetch.
  92
  93                                                 *fugitive-:Ggrep*
  94 :Ggrep [args]           |:grep| with git-grep as 'grepprg'.
  95
  96                                                 *fugitive-:Glgrep*
  97 :Glgrep [args]          |:lgrep| with git-grep as 'grepprg'.
  98
  99                                                 *fugitive-:Glog*
 100 :Glog [args]            Load all previous revisions of the current file into
 101                         the quickfix list.  Additional git-log arguments can
 102                         be given (for example, --reverse).  If "--" appears as
 103                         an argument, no file specific filtering is done, and
 104                         previous commits rather than previous file revisions
 105                         are loaded.
 106
 107 :{range}Glog [args]     Use git-log -L to load previous revisions of the given
 108                         range of the current file into the quickfix list.  The
 109                         cursor is positioned on the first line of the first
 110                         diff hunk for each commit.
 111
 112                                                 *fugitive-:Gllog*
 113 :Gllog [args]           Like |:Glog|, but use the location list instead of the
 114                         quickfix list.
 115
 116                                         *fugitive-:Gedit* *fugitive-:Ge*
 117 :Gedit [revision]       |:edit| a |fugitive-revision|.
 118
 119                                                 *fugitive-:Gsplit*
 120 :Gsplit [revision]      |:split| a |fugitive-revision|.
 121
 122                                                 *fugitive-:Gvsplit*
 123 :Gvsplit [revision]     |:vsplit| a |fugitive-revision|.
 124
 125                                                 *fugitive-:Gtabedit*
 126 :Gtabedit [revision]    |:tabedit| a |fugitive-revision|.
 127
 128                                                 *fugitive-:Gpedit*
 129 :Gpedit [revision]      |:pedit| a |fugitive-revision|.
 130
 131 :Gsplit! [args]                 *fugitive-:Gsplit!* *fugitive-:Gvsplit!*
 132 :Gvsplit! [args]                *fugitive-:Gtabedit!* *fugitive-:Gpedit!*
 133 :Gtabedit! [args]       Like |:Git!|, but open the resulting temp file in a
 134 :Gpedit! [args]         split, tab, or preview window.
 135
 136                                                 *fugitive-:Gread*
 137 :Gread [revision]       Empty the buffer and |:read| a |fugitive-revision|.
 138                         When the argument is omitted, this is similar to
 139                         git-checkout on a work tree file or git-add on a stage
 140                         file, but without writing anything to disk.
 141
 142 :{range}Gread [revision]
 143                         |:read| in a |fugitive-revision| after {range}.
 144
 145                                                 *fugitive-:Gread!*
 146 :Gread! [args]          Empty the buffer and |:read| the output of a Git
 147                         command.  For example, :Gread! show HEAD:%.
 148
 149 :{range}Gread! [args]  |:read| the output of a Git command after {range}.
 150
 151                                         *fugitive-:Gw* *fugitive-:Gwrite*
 152 :Gwrite                 Write to the current file's path and stage the results.
 153                         When run in a work tree file, it is effectively git
 154                         add.  Elsewhere, it is effectively git-checkout.  A
 155                         great deal of effort is expended to behave sensibly
 156                         when the work tree or index version of the file is
 157                         open in another buffer.
 158
 159 :Gwrite {path}          You can give |:Gwrite| an explicit path of where in
 160                         the work tree to write.  You can also give a path like
 161                         :0:foo.txt or even :0 to write to just that stage in
 162                         the index.
 163
 164                                                 *fugitive-:Gwq*
 165 :Gwq [path]             Like |:Gwrite| followed by |:quit| if the write
 166                         succeeded.
 167
 168 :Gwq! [path]            Like |:Gwrite|! followed by |:quit|! if the write
 169                         succeeded.
 170
 171                                                 *fugitive-:Gdiff*
 172 :Gdiff [revision]       Perform a |vimdiff| against the current file in the
 173                         given revision.  With no argument, the version in the
 174                         index is used (which means a three-way diff during a
 175                         merge conflict, making it a git-mergetool
 176                         alternative).  The newer of the two files is placed
 177                         to the right or bottom, depending on 'diffopt' and
 178                         the width of the window relative to 'textwidth'.  Use
 179                         |do| and |dp| and write to the index file to simulate
 180                         "git add --patch".
 181
 182                                                 *fugitive-:Gsdiff*
 183 :Gsdiff [revision]      Like |:Gdiff|, but always split horizontally.
 184
 185                                                 *fugitive-:Gvdiff*
 186 :Gvdiff [revision]      Like |:Gdiff|, but always split vertically.
 187
 188                                                 *fugitive-:Gmove*
 189 :Gmove {destination}    Wrapper around git-mv that renames the buffer
 190                         afterward.  The destination is relative to the current
 191                         directory except when started with a /, in which case
 192                         it is relative to the work tree.  Add a ! to pass -f.
 193
 194                                                 *fugitive-:Gremove*
 195 :Gremove                Wrapper around git-rm that deletes the buffer
 196                         afterward.  When invoked in an index file, --cached is
 197                         passed.  Add a ! to pass -f and forcefully discard the
 198                         buffer.
 199
 200                                                 *fugitive-:Gblame*
 201 :Gblame [flags]         Run git-blame on the file and open the results in a
 202                         scroll bound vertical split.  You can give any of
 203                         ltfnsewMC as flags and they will be passed along to
 204                         git-blame.  The following maps, which work on the
 205                         cursor line commit where sensible, are provided:
 206
 207                         g?    show this help
 208                         A     resize to end of author column
 209                         C     resize to end of commit column
 210                         D     resize to end of date/time column
 211                         q     close blame and return to blamed window
 212                         gq    q, then |:Gedit| to return to work tree version
 213                         <CR>  q, then open commit
 214                         o     open commit in horizontal split
 215                         O     open commit in new tab
 216                         -     reblame at commit
 217                         ~     reblame at [count]th first grandparent
 218                         P     reblame at [count]th parent (like HEAD^[count])
 219
 220 :[range]Gblame [flags]  Run git-blame on the given range.
 221
 222                                                 *fugitive-:Gbrowse*
 223 :Gbrowse                Open the current file, blob, tree, commit, or tag
 224                         in your browser at the upstream hosting provider
 225                         indicated by the "origin" remote.  If a range is
 226                         given, it is appropriately appended to the URL as an
 227                         anchor.
 228
 229                         Upstream providers can be added by installing an
 230                         appropriate Vim plugin.  For example, GitHub can be
 231                         supported by installing rhubarb.vim, available at
 232                         <https://github.com/tpope/vim-rhubarb>.  (Native
 233                         support for GitHub is currently included, but that is
 234                         slated to be removed.)
 235
 236                         If no upstream support is available, a local instance
 237                         of git-instaweb will be started and used instead.
 238
 239 :Gbrowse {revision}     Like :Gbrowse, but for a given |fugitive-revision|.  A
 240                         useful value here is -, which ties the URL to the
 241                         latest commit rather than a volatile branch.
 242
 243 :Gbrowse [...]@{remote} Force using the given remote rather than the remote
 244                         for the current branch.  The remote is used to
 245                         determine which GitHub repository to link to.
 246
 247 :{range}Gbrowse [args]  Appends an anchor to the URL that emphasizes the
 248                         selected lines.  You almost certainly want to give a
 249                         "-" argument in this case to force the URL to include
 250                         an exact revision.
 251
 252 :[range]Gbrowse! [args] Like :Gbrowse, but put the URL on the clipboard rather
 253                         than opening it.
 254
 255 MAPPINGS                                        *fugitive-mappings*
 256
 257 These maps are available everywhere.
 258
 259                                                 *fugitive-c_CTRL-R_CTRL-G*
 260 <C-R><C-G>              On the command line, recall the path to the current
 261                         object (that is, a representation of the object
 262                         recognized by |:Gedit|).
 263
 264                                                 *fugitive-y_CTRL-G*
 265 ["x]y<C-G>              Yank the commit SHA and path to the current object.
 266
 267 These maps are available in Git objects.
 268
 269                                                 *fugitive-<CR>*
 270 <CR>                    Jump to the revision under the cursor.
 271
 272                                                 *fugitive-o*
 273 o                       Jump to the revision under the cursor in a new split.
 274
 275                                                 *fugitive-S*
 276 S                       Jump to the revision under the cursor in a new
 277                         vertical split.
 278
 279                                                 *fugitive-O*
 280 O                       Jump to the revision under the cursor in a new tab.
 281
 282                                                 *fugitive--*
 283 -                       Go to the tree containing the current tree or blob.
 284
 285                                                 *fugitive-~*
 286 ~                       Go to the current file in the [count]th first
 287                         ancestor.
 288
 289                                                 *fugitive-P*
 290 P                       Go to the current file in the [count]th parent.
 291
 292                                                 *fugitive-C*
 293 C                       Go to the commit containing the current file.
 294
 295                                                 *fugitive-.*
 296 .                       Start a |:| command line with the current revision
 297                         prepopulated at the end of the line.
 298
 299                                                 *fugitive-a*
 300 a                       Show the current tag, commit, or tree in an alternate
 301                         format.
 302
 303 SPECIFYING REVISIONS                            *fugitive-revision*
 304
 305 Fugitive revisions are similar to Git revisions as defined in the "SPECIFYING
 306 REVISIONS" section in the git-rev-parse man page.  For commands that accept an
 307 optional revision, the default is the file in the index for work tree files
 308 and the work tree file for everything else.  Example revisions follow.
 309
 310 Revision        Meaning ~
 311 HEAD            .git/HEAD
 312 master          .git/refs/heads/master
 313 HEAD^{}         The commit referenced by HEAD
 314 HEAD^           The parent of the commit referenced by HEAD
 315 HEAD:           The tree referenced by HEAD
 316 /HEAD           The file named HEAD in the work tree
 317 Makefile        The file named Makefile in the work tree
 318 HEAD^:Makefile  The file named Makefile in the parent of HEAD
 319 :Makefile       The file named Makefile in the index (writable)
 320 -               The current file in HEAD
 321 ^               The current file in the previous commit
 322 ~3              The current file 3 commits ago
 323 :               .git/index (Same as |:Gstatus|)
 324 :0              The current file in the index
 325 :1              The current file's common ancestor during a conflict
 326 :2              The current file in the target branch during a conflict
 327 :3              The current file in the merged branch during a conflict
 328 :/foo           The most recent commit with "foo" in the message
 329
 330 STATUSLINE                                      *fugitive-statusline*
 331
 332                                                 *fugitive#statusline()*
 333 Add %{fugitive#statusline()} to your statusline to get an indicator including
 334 the current branch and the currently edited file's commit.  If you don't have
 335 a statusline, this one matches the default when 'ruler' is set:
 336 >
 337     set statusline=%<%f\ %h%m%r%{fugitive#statusline()}%=%-14.(%l,%c%V%)\ %P
 338 <
 339                                                 *fugitive#head(...)*
 340 Use fugitive#head() to return the name of the current branch. If the current
 341 HEAD is detached, fugitive#head() will return the empty string, unless the
 342 optional argument is given, in which case the hash of the current commit will
 343 be truncated to the given number of characters.
 344
 345 ABOUT                                           *fugitive-about*
 346
 347 Grab the latest version or report a bug on GitHub:
 348
 349 http://github.com/tpope/vim-fugitive
 350
 351  vim:tw=78:et:ft=help:norl: