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