| blob | d3d99085096de39e00450da1a72baa925c91262a |
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)
66 . enter |:| command line with file prepopulated
68 *fugitive-:Gcommit*
69 :Gcommit [args] A wrapper around git-commit. If there is nothing
70 to commit, |:Gstatus| is called instead. Unless the
71 arguments given would skip the invocation of an editor
72 (e.g., -m), a split window will be used to obtain a
73 commit message, or a new tab if -v is given. Write
74 and close that window (:wq or |:Gwrite|) to finish the
75 commit. Unlike when running the actual git-commit
76 command, it is possible (but unadvisable) to alter the
77 index with commands like git-add and git-reset while a
78 commit message is pending.
80 *fugitive-:Gmerge*
81 :Gmerge [args] Calls git-merge and loads errors and conflicted files
82 into the |quickfix| list. Opens a |:Gcommit| style
83 split window for the commit message if the merge
84 succeeds. If called during a merge conflict, the
85 conflicted files from the current index are loaded
86 into the |quickfix| list.
88 *fugitive-:Gpull*
89 :Gpull [args] Like |:Gmerge|, but for git-pull.
91 *fugitive-:Grebase*
92 :Grebase [args] Like |:Gmerge|, but for git-rebase. Interactive
93 rebase not supported.
95 *fugitive-:Gpush*
96 :Gpush [args] Invoke git-push, load the results into the |quickfix|
97 list, and invoke |:cwindow| to reveal any errors.
98 |:Dispatch| is used if available for asynchronous
99 invocation.
101 *fugitive-:Gfetch*
102 :Gfetch [args] Like |:Gpush|, but for git-fetch.
104 *fugitive-:Ggrep*
105 :Ggrep[!] [args] |:grep|[!] with git-grep as 'grepprg'.
107 *fugitive-:Glgrep*
108 :Glgrep[!] [args] |:lgrep|[!] with git-grep as 'grepprg'.
110 *fugitive-:Glog*
111 :Glog [args] Load all previous revisions of the current file into
112 the |quickfix| list. Additional git-log arguments can
113 be given (for example, --reverse). If "--" appears as
114 an argument, no file specific filtering is done, and
115 previous commits rather than previous file revisions
116 are loaded.
118 :{range}Glog [args] Use git-log -L to load previous revisions of the given
119 range of the current file into the |quickfix| list.
120 The cursor is positioned on the first line of the
121 first diff hunk for each commit.
123 *fugitive-:Gllog*
124 :Gllog [args] Like |:Glog|, but use the location list instead of the
125 |quickfix| list.
127 *fugitive-:Gedit* *fugitive-:Ge*
128 :Gedit [object] |:edit| a |fugitive-object|.
130 *fugitive-:Gsplit*
131 :Gsplit [object] |:split| a |fugitive-object|.
133 *fugitive-:Gvsplit*
134 :Gvsplit [object] |:vsplit| a |fugitive-object|.
136 *fugitive-:Gtabedit*
137 :Gtabedit [object] |:tabedit| a |fugitive-object|.
139 *fugitive-:Gpedit*
140 :Gpedit [object] |:pedit| a |fugitive-object|.
142 :Gsplit! [args] *fugitive-:Gsplit!* *fugitive-:Gvsplit!*
143 :Gvsplit! [args] *fugitive-:Gtabedit!* *fugitive-:Gpedit!*
144 :Gtabedit! [args] Like |:Git!|, but open the resulting temp file in a
145 :Gpedit! [args] split, tab, or preview window.
147 *fugitive-:Gread*
148 :Gread [object] Empty the buffer and |:read| a |fugitive-object|.
149 When the argument is omitted, this is similar to
150 git-checkout on a work tree file or git-add on a stage
151 file, but without writing anything to disk.
153 :{range}Gread [object] |:read| in a |fugitive-object| 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 [object] Perform a |vimdiff| against the given file, or if a
183 commit is given, the current file in that commit.
184 With no argument, the version in the index is used
185 (which means a three-way diff during a merge conflict,
186 making it a git-mergetool alternative). The newer of
187 the two files is placed to the right or bottom,
188 depending on 'diffopt', and the width of the window
189 relative to 'textwidth'. Use |do| and |dp| and write
190 to the index file to simulate "git add --patch". For
191 the three-way diff, there is also d2o and d3o pulling
192 the hunk to the middle from the left or the right
193 window, respectively.
195 *fugitive-:Gsdiff*
196 :Gsdiff [object] Like |:Gdiff|, but always split horizontally.
198 *fugitive-:Gvdiff*
199 :Gvdiff [object] Like |:Gdiff|, but always split vertically.
201 *fugitive-:Gmove*
202 :Gmove {destination} Wrapper around git-mv that renames the buffer
203 afterward. Add a ! to pass -f.
205 *fugitive-:Grename*
206 :Grename {destination} Like |:Gmove| but operates relative to the parent
207 directory of the current file.
209 *fugitive-:Gdelete*
210 :Gdelete Wrapper around git-rm that deletes the buffer
211 afterward. When invoked in an index file, --cached is
212 passed. Add a ! to pass -f and forcefully discard the
213 buffer.
215 *fugitive-:Gremove*
216 :Gremove Like :Gdelete, but keep the (now empty) buffer around.
218 *fugitive-:Gblame*
219 :Gblame [flags] Run git-blame on the file and open the results in a
220 scroll bound vertical split. You can give any of
221 ltfnsewMC as flags and they will be passed along to
222 git-blame. The following maps, which work on the
223 cursor line commit where sensible, are provided:
225 g? show this help
226 A resize to end of author column
227 C resize to end of commit column
228 D resize to end of date/time column
229 q close blame and return to blamed window
230 gq q, then |:Gedit| to return to work tree version
231 <CR> q, then open commit
232 o open commit in horizontal split
233 O open commit in new tab
234 p open commit in preview window
235 - reblame at commit
236 ~ reblame at [count]th first grandparent
237 P reblame at [count]th parent (like HEAD^[count])
239 *fugitive-:Gbrowse*
240 :Gbrowse Open the current file, blob, tree, commit, or tag
241 in your browser at the upstream hosting provider.
242 If a range is given, it is appropriately appended to
243 the URL as an anchor.
245 Upstream providers can be added by installing an
246 appropriate Vim plugin. For example, GitHub can be
247 supported by installing rhubarb.vim, available at
248 <https://github.com/tpope/vim-rhubarb>.
250 :Gbrowse {object} Like :Gbrowse, but for a given |fugitive-object|.
252 :Gbrowse [...]@{remote} Force using the given remote rather than the remote
253 for the current branch. The remote is used to
254 determine which upstream repository to link to.
256 :{range}Gbrowse [args] Appends an anchor to the URL that emphasizes the
257 selected lines. This also forces the URL to include a
258 commit rather than a branch name so it remains valid
259 if the file changes. You can give a range of "0" to
260 force this behavior without including an anchor.
262 :[range]Gbrowse! [args] Like :Gbrowse, but put the URL on the clipboard rather
263 than opening it.
265 MAPPINGS *fugitive-mappings*
267 These maps are available everywhere.
269 *fugitive-c_CTRL-R_CTRL-G*
270 <C-R><C-G> On the command line, recall the path to the current
271 |fugitive-object| (that is, a representation of the
272 object recognized by |:Gedit|).
274 *fugitive-y_CTRL-G*
275 ["x]y<C-G> Yank the commit SHA and path to the current
276 |fugitive-object|.
278 These maps are available in committed Git objects.
280 *fugitive-<CR>*
281 <CR> Jump to the |fugitive-object| under the cursor.
283 *fugitive-o*
284 o Jump to the |fugitive-object| under the cursor in a
285 new split.
287 *fugitive-S*
288 S Jump to the |fugitive-object| under the cursor in a
289 new vertical split.
291 *fugitive-O*
292 O Jump to the |fugitive-object| under the cursor in a
293 new tab.
295 *fugitive--*
296 - Go to the tree containing the current tree or blob.
298 *fugitive-~*
299 ~ Go to the current file in the [count]th first
300 ancestor.
302 *fugitive-P*
303 P Go to the current file in the [count]th parent.
305 *fugitive-C*
306 C Go to the commit containing the current file.
308 *fugitive-a*
309 a Show the current tag, commit, or tree in an alternate
310 format.
312 SPECIFYING OBJECTS *fugitive-object* *fugitive-revision*
314 Fugitive objects are either work tree files or Git revisions as defined in the
315 "SPECIFYING REVISIONS" section in the git-rev-parse man page, with expansions
316 inspired by |cmdline-special| layered on top. For commands that accept an
317 optional object, the default is the file in the index for work tree files and
318 the work tree file for everything else. Example objects follow.
320 Object Meaning ~
321 HEAD .git/HEAD
322 refs/heads/x .git/refs/heads/x (in "common dir" if present)
323 @ The commit referenced by @ aka HEAD
324 master^ The parent of the commit referenced by master
325 master: The tree referenced by master
326 ./master The file named master in the working directory
327 Makefile The file named Makefile in the work tree
328 @^:Makefile The file named Makefile in the parent of HEAD
329 :Makefile The file named Makefile in the index (writable)
330 @~2:% The current file in the grandparent of HEAD
331 :% The current file in the index
332 :1:% The current file's common ancestor during a conflict
333 :2:# The alternate file in the target branch during a conflict
334 :3:#5 The file from buffer #5 in the merged branch during a conflict
335 ! The commit owning the current file
336 !:Makefile The file named Makefile in the commit owning the current file
337 !3^2 The second parent of the commit owning buffer #3
338 .git/config The repo config file
339 : Same as |:Gstatus|
341 STATUSLINE *fugitive-statusline*
343 *FugitiveStatusline()* *fugitive#statusline()*
344 Add %{FugitiveStatusline()} to your statusline to get an indicator including
345 the current branch and the currently edited file's commit. If you don't have
346 a statusline, this one matches the default when 'ruler' is set:
347 >
348 set statusline=%<%f\ %h%m%r%{FugitiveStatusline()}%=%-14.(%l,%c%V%)\ %P
349 <
350 *FugitiveHead(...)* *fugitive#head(...)*
351 Use FugitiveHead() to return the name of the current branch. If the current
352 HEAD is detached, FugitiveHead() will return the empty string, unless the
353 optional argument is given, in which case the hash of the current commit will
354 be truncated to the given number of characters.
356 ABOUT *fugitive-about*
358 Grab the latest version or report a bug on GitHub:
360 http://github.com/tpope/vim-fugitive
362 vim:tw=78:et:ft=help:norl: