3 AUTHOR: Greg Sexton <gregsexton@gmail.com> *gitv-author*
4 WEBSITE: http://www.gregsexton.org/portfolio/gitv/
5 LICENSE: Same terms as Vim itself (see :help license).
6 NOTES: Much of the credit for gitv goes to Tim Pope and the fugitive plugin
7 where this plugin either uses functionality directly or was inspired
12 1. Introduction |gitv-introduction|
13 2. Installation |gitv-installation|
15 4. Configuration Options |gitv-config-options|
16 5. Changelog |gitv-changelog|
19 ==============================================================================
20 1. Introduction *gitv-introduction*
22 |gitv| is a 'gitk clone' plugin for the text editor Vim. The goal is to give
23 you a similar set of functionality as a repository viewer. Using this plugin
24 you can view a repository's history including branching and merging, you can
25 see which commits refs point to. You can quickly and easily view what changed
26 to which files and when. You can perform arbitrary diffs (using Vim's
27 excellent built in diff functionality) and you can easily check out whole
28 commits and branches or just individual files if need be.
30 Throw in the fact that it is running in Vim and you get for free: the ability
31 to move over repository history quickly and precisely using Vim's built in
32 movement operators. You get excellent code syntax highlighting due to Vim's
33 built in ability. You can open up all sorts of repository views in multiple
34 windows and position them exactly how you like. You can take advantage of
35 Vim's registers to copy multiple fragments of code from previous commits. The
38 This plugin is an extension of the |fugitive| plugin.
42 ==============================================================================
43 2. Installation *gitv-installation*
45 Install in ~/.vim, or in ~\vimfiles if you're on Windows. This plugin should
46 be fully pathogen compatible if you want to install it this way.
48 |gitv| was developed against Vim 7.3 but earlier versions of Vim should work.
49 Vim 7.2+ is recommended as it ships with syntax highlighting for many Git file
50 types. You will also need the |fugitive| plugin installed and working for
53 ==============================================================================
56 |gitv| defines the following command.
58 :Gitv[!] [args] Invoking this command on a buffer that belongs to a git
59 repository causes the gitv browser to open. '!' causes gitv
60 to open in file mode rather than browser mode. Any [args]
61 supplied are passed on to the gitv viewer and can be used to
62 narrow the commits that are shown. If this command is run
63 on a buffer not belonging to a git repository a message
64 stating 'Not a git repository.' is displayed.
66 The following abbreviation is also defined so that you can type :gitv without
74 |gitv| has two distinct modes. Browser mode and file mode. The browser mode is
75 opened in a new tab and allows the repository history to be viewed for all
76 files. This is activated by running :Gitv without a '!'.
78 In this mode you can view the entire repository history and see which files
79 were changed with each commit. This mode tries to closely resemble gitk.
83 File mode is opened in a |preview-window| above the buffer you are currently in.
84 This view is tailored to act on the buffer that :Gitv! was run from, the
85 "focused" file. Whilst in this mode all actions performed are specific to the
86 single focused file. The browser only shows commits where the focused file
87 changed. Selecting a commit, views the focused file as it was in that commit.
88 Performing a check out only checks the focused file out as it was in the
89 commit. And so on. See 3.4 for the differences.
93 You can pass arguments to the :Gitv command. These allow you to filter and
94 narrow the commits shown. Essentially, gitv is a glorified 'git log' wrapper
95 and so any flag that 'git log' accepts so will gitv. gitv does not inspect the
96 arguments passed on to 'git log' and so may not work if they don't make sense.
98 Without any arguments gitv behaves just like gitk and git log without
99 arguments. It will display the commit history for the currently checked out
102 Here are some particularly useful examples of arguments that could be
103 passed to :Gitv. For more info see 'git help log' and in particular the
104 section: "Commit Limiting".
108 --all View repository history for all refs.
110 <since>..<until> Show only commits between the named two commits. When
111 either <since> or <until> is omitted, it defaults to
112 HEAD, i.e. the tip of the current branch. For a more
113 complete list of ways to spell <since> and <until>,
116 --merges View only merge commits.
118 -S<string> Look for differences that introduce or remove an
119 instance of <string>. Note that this is different than
120 the string simply appearing in diff output; see the
121 pickaxe entry in gitdiffcore(7) for more details.
123 -G<regex> Look for differences whose added or removed line
124 matches the given <regex>.
128 This is a list of key mappings that will work only in the gitv browser window.
129 Where appropriate the differences in action is described for the two modes.
131 Mode Map Description~
133 normal <cr> Opens a commit. In browser mode this will show the
134 commit header information including the commit
135 message. It will also dispaly a full diff showing all the
138 Tip: if you press <cr> on anything sensible you can
139 view the expected output. For example pressing <cr> on
140 the line beginning a file diff, it will display the
141 diff using Vim's built in diff viewing capability.
142 Pressing <cr> on the tree sha will list all the files
143 in the commit and pressing <cr> on one of these will
144 show that file as it was in the commit. And so on.
146 Pressing <cr> on the line "-- Load More --" will load
147 |g:Gitv_CommitStep| more commits.
149 In file mode this will open the focused file as it was
150 in the currently selected diff. This allows you to
151 easily go back in time and look at the focused file.
153 Pressing <cr> on the top line in file mode opens the
154 current working copy of the focused file.
156 normal o The same as <cr> but opens in a new |split|.
157 normal O The same as <cr> but opens in a new |tab|.
158 normal s The same as <cr> but opens in a new |vsplit|.
160 normal <c-cr> This performs the same thing as <cr> in browser mode.
161 In file mode it opens the commit details rather than
164 normal q Quits gitv. In browser mode this will close the entire
165 tab. In file mode this closes only the |preview-window|.
166 Note: in browser mode this will close the tab
167 regardless of any windows you may have opened as well
170 normal u Forces an update of the content of the browser window.
172 normal co Performs a 'git checkout' of the commit the cursor is
173 on. In both modes this will present you with a choice
174 of whether you would like to checkout the sha or any
175 ref that might point to this commit.
177 File mode differs in that it doesn't check out the
178 entire commit but just the focused file in that
181 Tip: in gVim this will present you with a pop up dialog.
182 You can make this a text choice by performing ':set
185 normal D Performs a diff using Vim's built in diff viewing
186 capabilities. This does nothing in browser mode. In
187 file mode it will diff the current file with the
188 focused file in the commit under the cursor.
190 visual D In visual mode this performs a diff against the file
191 in the commit at the top of the selection against the
192 file in the commit at the bottom of the selection. The
193 newest file is always on the right.
195 normal S This works for both browser and file mode. It opens a
196 diffstat of everything that has changed since the
197 commit under the cursor.
199 visual S In visual mode this works in exactly the same way as
200 normal mode. However, it only shows what has changed in
201 the range of commits that are highlighted.
203 Here is a list of extra key mappings that can be used to efficiently move
204 around a repository history in the browser window.
206 Mode Map Description~
208 normal x Jumps the cursor forward to the next branching point
211 normal X Jumps the cursor backward to the previous branching
212 point in the history.
214 normal r Jumps the cursor forward to the next ref in the
217 normal R Jumps the cursor backward to the previous ref in the
220 normal P Jumps the cursor to the commit referenced by HEAD.
224 Running the |:Git| command in the commit browser window, in either mode, will
225 cause the |:Git| command to be run as expected but the commit history will
226 automatically update to reflect any changes too.
230 In browser mode, two windows are opened initially. The "browser window" that
231 displays the commit history and the "preview window" that shows the currently
234 In file mode, a |preview-window| is opened above the current file. This is a
235 browser window filtered to show commits only affecting the focused file. The
236 window holding the focused file acts as the preview window in this mode.
238 NOTE: In both modes the buffer in the preview window is wiped after replacing
239 it. This is to stop the quick build up of fugitive buffers. A buffer will not
240 be wiped if it contains unsaved changes. Buffers are not wiped when opening a
241 commit in a split, vsplit or a new tab.
243 When opening a commit, the window it will be opened in is determined by simple
244 rules. If in browser mode and the layout is vertical it will open in the
245 window to the immediate right (exactly as if you performed <c-w>l). If in a
246 horizontal layout, it will be opened in the window immediately below (exactly
247 as if you performed <c-w>j). If in file mode, it will open exactly like
248 browser mode split horizontally. NOTE: It is for this reason that you should
249 not move the browser window as it will cause commits to be opened in
254 Folding of branches is supported in the browser window. Initially all folds
255 are always open and will open on a reload. You can collapse any branch by
256 using Vim's built in fold operators. See |folding| for more details.
258 ==============================================================================
259 4. Configuration Options *gitv-config-options*
261 You can set the following options in your .vimrc to override the values used
262 by |gitv|. The defaults are shown.
266 This is the number of commits to show each time. When pressing <cr> on
267 "-- Load More --", the number of extra commits loaded is g:Gitv_CommitStep.
268 The default is a screen's worth of lines. This should be set to an integer
269 number. Setting this to a value _really_ high will load the entire repo in one
272 g:Gitv_CommitStep = &lines
277 This is the default layout to use in browser mode. If set to 0 then browser
278 mode will open in a vertical split. If set to 1 then browser mode will open in
279 a horizontal split. If set to 'auto' then browser mode will open in a vertical
280 split unless the content fits better in a horizontal split, in which case it
281 will open horizontally.
283 The commit browser width and height is automatically sized to best fit the
284 content in all modes and settings.
286 g:Gitv_OpenHorizontal = 0
291 This is the name of the git executable to use to run commands. This should be
294 g:Gitv_GitExecutable = 'git'
296 4.4 Wipe All on Close
298 This option should be set to either 0 (to disable) or 1 (to enable). If set to
299 1 then on closing the browser mode by using the q key all buffers displayed in
300 a window in the tab will be wiped before the tab is closed. This option allows
301 you to limit the number of fugitive buffers that accumulate in the use of gitv.
303 NOTE: This will not wipe any buffer with unsaved content. It will however
304 mercilessly wipe all buffers in the tab regardless of the file they hold.
306 g:Gitv_WipeAllOnClose = 0
311 If set to 1 then line wrapping is enabled. This is useful if you have
312 occasional very long commit messages.
317 4.6 Truncate Commit Subjects
319 If set to 1 then commit subject truncation is enabled. This will truncate
320 commit subjects, where necessary, so that the whole line will fit in one
321 screen width. If this is set, then automatically switching to a horizontal
322 layout will no longer work as commits will be truncated to always fit in a
323 vertical split. NOTE: It is possible that this can truncate any refs pointing
324 at a commit. In this situation it will not be possible to check out any of
325 these refs. This is due to gitv being unable to recognise that they are refs.
327 g:Gitv_TruncateCommitSubjects = 0
329 ==============================================================================
330 5. Changelog *gitv-changelog*
332 1.0 First release. I hope you enjoy gitv!
334 ==============================================================================
339 I use the following mappings to make working with |gitv| easier.
341 nmap <leader>gv :Gitv --all<cr>
342 nmap <leader>gV :Gitv! --all<cr>
345 The following abbreviation makes running arbitrary git commands much easier.
350 The function: 'Gitv_OpenGitCommand(command, windowCmd)' is provided to allow
351 the more advanced user to create their own commands. This function will
352 execute the git command provided in the new window created using windowCmd.
354 By using this function you get for free: the buffer set up for read only git
355 output, including syntax highlighting and many other tailored options. You
356 also get mappings for 'u' to update the output and 'q' to easily close the
359 Here is an example of getting diff output both cached and not, in a vertical
360 and horizontal split respectively.
362 call Gitv_OpenGitCommand("diff --no-color --cached", 'vnew')
363 call Gitv_OpenGitCommand("diff --no-color", 'new')
366 I like my diff colors to be green for added lines and red for removed lines,
367 just like in the shell. Adding this to your vimrc will accomplish this.
369 highlight diffAdded guifg=#00bf00
370 highlight diffRemoved guifg=#bf0000
373 I highly recommend adding to your vimrc:
378 This stops Vim from redrawing the screen during complex operations and results
379 in much smoother looking plugins.
382 6.2 Bugs, issues, features and contributing.
384 There are no known bugs. Hopefully there are not too many unknown. Please see
387 Bugs, suggestions, pull requests and patches are all very welcome. If you find
388 issues with |gitv| please add them to the issues page on the github project.
389 Anything else, feel free to email me: gregsexton@gmail.com.
391 vim:tw=78:ts=8:ft=help:norl: