1 *perforce.txt* A feature Rich Perforce SCM Integration for Vim.
3 Last Change: 01-Sep-2006 @ 16:54
7 Author: Hari Krishna Dara (hari_vim at yahoo dot com)
9 *perforce-introduction*
11 This is a fairly complete integration with the perforce version control system
12 for the most commonly used operations, including many administrative commands.
13 It includes a great menu that is modelled very close to the p4win (the perforce
14 GUI client) and is quite extensive.
16 ==============================================================================
17 OVERVIEW *perforce-overview*
19 |perforce-installation| How to install the plugin.
21 |perforce-filetype| Perforce filetype plugin and setting it up for p4.
23 |perforce-settings| An explanation of how to configure the plugin, for
24 both the perforce related parameters and the plugin
25 customizations, such as enabling menu.
27 |perforce-ruler| Setting up the ruler to show an active status of the
30 |perforce-syntax| Perforce syntax plugin.
32 |perforce-help| Browse the p4 help conveniently from within vim.
34 |perforce-reinitialize| Describes how to reinitialize the plugin to load the
35 latest settings from the environment without
38 |perforce-commands| A description of various commands that can be
39 issued on Vim command-line.
41 |perforce-revisions| Specifying perforce revisions conveniently.
43 |perforce-interactive-commands|
44 How to execute interactive perforce commands.
46 |perforce-forms| How to edit the perforce forms (specifications) from
49 |perforce-submit| Special handling of submit command.
51 |perforce-list-commands| Commands that can be used in a list of items window.
53 |perforce-extensions| Some useful extensions in the form of new options
56 |perforce-misc-commands| Some additional useful commands.
58 |perforce-special-commands| Some useful commands and mappings.
60 |perforce-utils| Additional utilties (perforce/perforceutils.vim).
62 |perforce-API| New API provided by the plugin (experimental).
64 |perforce-tips| Some useful tips.
66 |perforce-limitations| Current limitations of the plugin.
68 |perforce-troubleshooting| Some notes how to trouble shoot problems.
70 |perforce-changes| A change list for current version from previous
73 |perforce-known-issues| A list of known bugs.
75 |perforce-wishlist| Wishlist items that may be worth doing for a future
78 |perforce-bugreporting| Reporting bugs.
80 |perforce-acknowledgements| Acknowledgements.
82 ==============================================================================
84 *perforce-installation*
86 To install, place the perforce.vim script in one of the runtime plugin
87 directories along with the genutils.vim scripts that it depends on. This
88 typically is .vim/plugin or vimfiles/plugin directory under your home directory.
89 To get the latest versions of these plugins, goto the following webplages:
90 perforce.vim: http://www.vim.org/script.php?script_id=240
91 genutils.vim: http://www.vim.org/script.php?script_id=197
93 The distribution contains the following files:
95 - Thin interface to the plugin (autoload/perforce.vim).
96 - autoload/perforce.vim
97 - The perforce plugin itself loaded on demand.
98 - ftplugin/perforce.vim
99 - The perforce filetype plugin file. See below on how to configure the
101 - syntax/perforce.vim.
102 - Syntax definition file for perforce forms.
104 - The online help file (this file).
105 - perforce/perforcemenu.vim.
106 - Additional module to install and configure a menu for the plugin.
108 - perforce/perforcebugrep.vim.
109 - An utility script that can be used to generate useful information
110 while sending bugreports about the plugin. See
111 |perforce-bugreporting|.
112 - perforce/perforceutils.vim.
113 - Thin interface to autoload/perforceutils.vim
114 - autoload/perforceutils.vim
115 - Additional misc. utilities loaded on demand.
117 If you obtained the plugin as a zip archive,
118 - Just extract it in your runtime directory.
119 - Start a new instance or go to an existing instance of vim.
122 :helpt <your runtime directory>/doc
124 This should generate the help tags for the perforce plugin help.
125 - Setup perforce filetype as described in |perforce-filetype| section.
126 - Make sure p4 command is in your path or set |p4CmdPath| property.
127 - Set the |p4ClientRoot| property and additionally any other
128 |perforce-settings| that you like.
129 - Optionally set 'cmdheight' property to at least 2 to avoid seeing the more
130 prompt for most of the messages the plugin gives.
131 - The plugin requires that you have Vim 7.0 version installed.
132 - If you want to enable the perforceutils.vim plugin, add the following line
135 runtime perforce/perforceutils.vim
137 - If you want to enable the menu, add the following line to your vimrc, at
138 the end of perforce configuration lines:
140 runtime perforce/perforcemenu.vim
142 - The core of the plugin is autoloaded by Vim the first time a perforce
143 command needs to be executed. This improves the startup time of Vim
144 considerably in some situations. If you want the plugin to be loaded
145 immediately, you can force an autoload by adding the following command to
151 Note: It is important to make sure your 'shellredir' properly set such that, vim
152 captures both the standard output and standard error messages from the external
153 perforce command. If this is not correctly set, the plugin will not be able to
154 show the error messages generated by p4 command to you.
156 Also note that on Windows, if you use a UNIX like shell for your 'shell'
157 setting, the plugin will not work correctly unless the 'shellslash' option is
161 Later, if you need to temporarily disable the plugin without needing to remove
162 the files, you can set the loaded_perforce variable in your vimrc. You can also
163 set the no_perforce_maps to disable just the mappings defined in this plugin or
164 no_plugin_maps to disable mappings in all the plugins (provided they all honor
165 this setting), in your vimrc.
166 ==============================================================================
170 The package comes with a perforce ftplugin (|filetype-plugin|) which sets a
171 few text mode options suitable for editing the forms and a syntax plugin to
172 colorize the spec files. The ftplugin also positions the cursor at the
173 appropriate line based on the type of spec you are editing. When you open
174 perforce forms from within vim using |perforce-interactive-commands|, you
175 don't have to do anything special for this to work, but if you want the same
176 to work while editing forms using p4 command directly, then you need to add
177 the following lines in your scripts.vim:
179 if getline(1) =~ '^# A Perforce '
183 If you do not have this file already, then you need to create it under
184 vimfiles or .vim directory (or anywhere in your 'rtp'). For details see help
185 on |new-filetype-scripts|. Note that you also need to enable filetype plugins
186 for this to work, see |filetype-plugin| for more information.
188 ==============================================================================
191 *perforce-customizing*
192 The plugin allows a lot of customization by reading some global variables. You
193 can define a set of global variables in your startup script (.vimrc/_vimrc) and
194 they are automatically read by the plugin during the Vim startup and are used
195 for customizing the behavior.
197 Note that all the setting names are case sensitive and the boolean settings can
198 be set to the value 0 to disable and any non-zero number (for the matter of
199 fact, any string will also do) to enable. All the settings can be changed at
200 runtime without restarting vim; see |perforce-reinitialize|.
202 The settings can also be changed at runtime, see |perforce-reinitialize|.
204 Here is a list of all the options:
205 |p4CmdPath|, |p4DefaultPreset|, |p4DefaultOptions|, |p4ClientRoot|,
206 |p4EnableRuler|, |p4RulerWidth|, |p4EnableActiveStatus|,
207 |p4ASIgnoreDefPattern|, |p4ASIgnoreUsrPattern|, |p4OptimizeActiveStatus|,
208 |p4UseGUIDialogs|, |p4PromptToCheckout|, |p4DefaultListSize|,
209 |p4DefaultDiffOptions|, |p4EnableMenu|, |p4UseExpandedMenu|,
210 |p4EnablePopupMenu|, |p4UseExpandedPopupMenu|, |p4Presets|,
211 |p4MaxLinesInDialog|, |p4CheckOutDefault|, |p4SortSettings|, |p4TempDir|,
212 |p4SplitCommand|, |p4UseVimDiff2|, |p4EnableFileChangedShell|,
213 |p4HideOnBufHidden|, |p4Depot|, |p4Autoread|, |p4FileLauncher|,
214 |p4CurPresetExpr|, |p4CurDirExpr|, |p4UseClientViewMap|
216 *perforce-command-path*
218 The plugin executes the external p4 command for all its operations. By default
219 the command is found in the PATH, but if it doesn't exist in the path you can
220 still specify the location by using the p4CmdPath variable.
222 :let g:p4CmdPath = '<path_to_p4_command>'
225 :let g:p4CmdPath = '~/bin/perforce/bin/p4'
229 This is a useful setting when you work with multiple perforce installations at
230 the same time. This allows you to predefine a set of configurations that you
231 can switch between without needing to restart vim or manually enter the
232 details while using the |PFSwitch| command. Set this variable in your vimrc
233 with a comma separated list of settings. Each setting should be of
234 the form (separated with one or more spaces):
236 <port> <client> <user>
238 You can include as many of these specifications as you want, just separate them
241 :let g:p4Presets = 'port1 client1 user1,port2 client2 user2'
243 Once set, you can use the |PFSwitch| command in one of three ways to choose the
246 1. If you know the index of the setting to which you want to
247 switch to (starting with 0), just pass that as an argument to the
250 " Switch to the third setting.
253 2. If you don't know the index, just invoke the command without any
254 arguments. You will be prompted to enter the index after displaying
255 a list of available settings.
257 3. If you have expanded menu enabled (see |p4UseExpandedMenu| or
258 |p4UseExpandedPopupMenu|), then you can choose the desired setting
259 to switch to using the "Settings" sub-menu under "Perforce" group.
263 As a special case, you can have one of the specifications as "P4CONFIG",
264 allowing you to switch to the P4CONFIG feature of external p4 command
265 interactively, see |perforce-dynamic-client|.
267 :let g:p4Presets = 'p1 c1 u1,P4CONFIG,p2 c2 u2'
269 Setting port field to "P4CONFIG" also has the same effect. This results in
270 plugin not passing the options for port, client and user explicitly such that p4
271 can determine them based on the P4CONFIG file. However you can still override
272 them by explicitly specifying the corresponding option to PF command.
275 If you don't have the P4CLIENT, P4USER and P4PORT environment variables set, you
276 can use this setting to initialize the plugin with corresponding values. The
277 format for the value is exactly same as a single entry in |p4Presets| setting.
278 In fact, you can also set this to an index in the |p4Presets|.
280 :let g:p4DefaultPreset = '<your_perforce_port> <your_perforce_client_name> <your_perforce_user_name>'
283 :let g:p4DefaultPreset = 'localhost:1666 hari_client hari'
284 :let g:p4DefaultPreset = 2 " Start with the second setting in p4Presets.
286 Note that the plugin automatically chooses some defaults for the above based on
287 your environment, if you don't explicitly set them in your startup script.
289 *perforce-default-options*
290 *perforce-common-options*
292 If you need to pass in additional arguments every time the external p4 command
293 is run, you can use the following setting. The arguments are passed to p4
294 literally. For the set of options that you can specify here, see perforce help
295 for "usage" (use ":PH usage" command, see |perforce-help|)
297 :let g:p4DefaultOptions = '<default_options_to_p4>'
300 :let g:p4DefaultOptions = '-H hkrishna'
302 *perforce-buffer-local-options*
303 In addition you can also use the buffer local variables "b:p4Options",
304 "b:p4Client", "b:p4User", "b:p4Port" and "b:clientRoot" to override the global
305 options (see ":PH usage" for option list) at a buffer level. The plugin
306 automatically sets these options whenever you create a new perforce result
307 window such that any future commands originating from the same window
308 automatically inherit them. This is especially useful when you temporarily
309 switch to a different client/user by providing one at command-line, and later do
310 more operations on the results (provided the given client/user is valid on the
313 :PF -c hari_tmp opened
316 The PFileDiff will automatically use the "hari_tmp" client as b:p4Client is set
317 to that value. You can also use b:p4Options to set any option that is accepted
318 in the global options section of PF command (see |perforce-global-options|),
319 however for the client view mapping to work correctly, you need to have
320 b:p4Client and b:clientRoot set. >
322 :let b:p4Options = '-H my_host'
324 All commands executed when this buffer is active will automatically inherit
325 these global options.
327 NOTE: Currently the b:clientRoot variable needs to be set manually.
329 *perforce-client-root*
331 The client root is required for certain commands (it is same as what you
332 specify in the Root: property in the client settings), so if not specified and
333 if the |p4EnableActiveStatus| setting is enabled, the plugin will run the "p4
334 info" command to read the client root setting from the perforce server. But
335 this will introduce a short delay in autoload time (especially if you are
336 talking to a perforce server that is installed out side your network). To avoid
337 this, use the following setting to specify the client root.
339 :let g:p4ClientRoot = '<client_root_directory>'
342 :let g:p4ClientRoot = 'c:/dev'
344 If |p4EnableActiveStatus| is disabled, the current directory is used as the
347 *perforce-gui-dialogs*
349 By default the plugin uses console dialogs for some of the prompts. This is
350 convenient as you can then use the input-history and expression register
351 |quote=|. But if you like, you can enable this setting to force using GUI
352 dialogs for all the prompts.
354 :let g:p4UseGUIDialogs = 1
357 *perforce-automatic-checkout*
359 The plugin by default prompts you to checkout, when you start editing a
360 readonly file under the client root. You can disable this behavior by using the
363 :let g:p4PromptToCheckout = 0
365 Note that you can still manually checkout (or edit) the file even when this
366 option is disabled by using "PE" or "PF edit" command.
368 When the checkout prompt is given, you have the option saying Yes, No or Cancel.
369 When accidental changes to the buffer bring up the checkout prompt, you can
370 select Cancel to revert the state of the buffer as much as possible (you may
371 still have to press <Esc> sometimes). One advantage of selecting Cancel in these
372 cases is that the next time you start making a genuine change, you will get the
373 checkout prompt as expected (otherwise, you will only get this prompt once).
376 *perforce-default-list-size*
378 When you execute "changes", "jobs" and "filelog" perforce commands, the number
379 of entries is limited to 100 to avoid generating a large volume of data. But you
380 can change the value to whatever you like:
382 :let g:p4DefaultListSize = 1000
384 To disabling it completely (show the entire list) set it to a negative number:
386 :let g:p4DefaultListSize = -1
389 *perforce-default-diff-options*
390 *p4DefaultDiffOptions*
391 You can set the default diff options to be passed to all the "diff" and "diff2"
392 operations (both direct and indirect execution of these commands), by using the
395 :let g:p4DefaultDiffOptions = '-dwbu5'
397 For the options that you can set here, see the help for "diff" or "diff2" by
398 running the "PH diff" or "PH diff2" command.
400 Note, this setting can't be used to specify options to the external diff
405 The distribution comes with an additional module called perforcemenu.vim to
406 install a Perforce sub-menu on the main or PopUp menu. By default the menu is
407 not added as many people (including myself) don't use menus (I have the entire
408 menu bar disabled). Use the following setting to enable the Perforce sub-menu:
410 :let g:p4EnableMenu = 1
412 The above setting will create a very basic menu with the most needed commands.
413 This makes it easy to use shortcut keys if you have the |winaltkeys| correctly
414 configured. To enable a more full featured menu, see |p4UseExpandedMenu|.
416 *perforce-expanded-menu*
418 By default the |p4EnableMenu| option creates a full-featured menu that is
419 modelled closely after the p4Win utility, which comes with perforce. But you can
420 disable this and have only a basic menu with the most commonly used set of
421 commands (this was the default for older versions of the plugin). Use the
422 following setting in your startup script:
424 :let g:p4UseExpandedMenu = 0
426 If you want a basic menu on the main menu (for the ease of using the shortcut
427 keys), then you can consider having the full-featured version on the popup
428 menu, see |p4EnablePopupMenu| and |p4UseExpandedPopupMenu| settings.
430 *perforce-popup-menu*
432 This is similar to |p4EnableMenu| except that enabling this option, adds a
433 Perforce sub-menu on the PopUp menu instead of the main menu.
435 :let g:p4EnablePopupMenu = 1
437 *perforce-expanded-popup-menu*
438 *p4UseExpandedPopupMenu*
439 This is similar to |p4UseExpandedMenu| except that enabling this option, adds a
440 more full-featured Perforce sub-menu on the PopUp menu.
442 :let g:p4UseExpandedPopupMenu = 1
444 *loaded_perforcemenu*
445 Note: If you never use the menu features of the plugin, consider setting
446 "loaded_perforcemenu" to a non-zero value, to avoid getting this module sourced.
448 *perforce-max-lines-in-dialog*
450 Commands that use a dialog box to show the result (such as |PEdit|) assume
451 that the messages generated by the perforce command are only a few lines. But
452 depending on the arguments (e.g., "PEdit ..." and there are many files under
453 the current directory ...), there can be too many lines to display in a dialog
454 so the display mode is automatically switched to a new window instead of the
455 dialog. Though the default limit is 1, which helps to draw your attention for
456 the conditions that you normally expect a one line result (e.g., you checkout a
457 file and someone else already checked out the file), you can change it by
458 setting the following line:
460 :let g:p4MaxLinesInDialog = <number of lines>
464 :let g:p4MaxLinesInDialog = 5
467 When you start modifying a read-only file, the plugin prompts you to checkout
468 the file from perforce. Set this option to 1 to make the default option to
469 "Yes" and 2 for "No". The default is 2 to avoid accidentally checking out a
472 :let g:p4CheckOutDefault = <option number>
476 :let g:p4CheckOutDefault = 1
479 The |PFSettings| command by default sorts the setting so that they are in
480 alphabetical order. But this will alter the position of the settings as new
481 settings get added, so if you want them to always appear in the same familiar
482 order, then set this to 0 to disable sorting. >
484 :let p4SortSettings = 0
487 This setting points to the directory which should be used by the plugin for
488 creating any temporary files. This setting is used for vdiff and vdiff2
489 commands, but currently these commands don't really create any files on the
490 filesystem, as the directory is used to merely generate the filenames for
491 temporary files (the filename is still such that it is valid on the filesystem,
492 so that you can write the contents to it for any reason, but you will have to
493 reset the 'buftype' option first). But this may change in future when new
494 features/commands get added which require the temporary files to be on
497 :let p4TempDir = "c:/temp/vim-p4"
500 When the plugin creates new windows as a result of issuing perforce commands, it
501 by default uses |:split| command, which creates a horizontally split window above
502 or below the current window depending on your 'splitbelow' setting. But if you
503 would like to change the way the windows are created, you can set this setting
504 to any split command that is valid (such as |:vsplit| or "topleft split"). For
505 all possible commands see |:vertical|. >
507 :let p4SplitCommand = "vsplit"
510 If this option is set, the plugin uses vdiff2 instead of diff2 in the filelog
511 window. See |perforce-vim-diff|. >
513 :let p4UseVimDiff2 = 1
515 *p4EnableFileChangedShell*
516 The plugin normally listens to the |FileChangedShell| events and refreshes the
517 ruler automatically (See |perforce-ruler|), keeping the status up to date. But
518 because of the way this event works, the plugin has to emulate the |timestamp|
519 warning messages that would be generated by Vim by default, when there is no
520 listener for this event. If you don't like this feature for any reason, you can
521 disable it by setting this option to 0. >
523 :let p4EnableFileChangedShell = 0
525 Note that the plugin no longer refreshes the ruler whenever vim detects that the
526 file has been modified externally requiring a reload of the buffer (and this
527 anyway happens only if the buffer is currently visible in a window, or if the
528 'hidden' option is set). To manually refresh the ruler see
529 |perforce-refresh-file-status|.
532 This setting is useful if you do not normally set the 'hidden' option. The
533 plugin normally sets the 'bufhidden' option for the perforce plugins to the
534 value "wipe" such that they are automatically wiped out when they are unloaded.
535 This keeps your buffer list clean and also conserves the vim resources as you
536 can potentially end up creating a lot of buffers, one for each perforce command
537 that you execute from with in Vim. But this would prevent you from switching
538 back and forth between the perforce result buffers and other regular buffers.
539 If you often find yourself working with perforce windows for a long time, you
540 should consider setting this option to the value "hide" instead, avoiding unload
541 of the buffers when they are hidden. When you set this value, an interesting and
542 useful side effect is that you can use <C-O> and <Tab> to navigate the preview
543 window, which can be very useful while viewing the description of list items,
544 see |perforce-list-commands|. >
546 :let g:p4BufHidden = 'hide'
548 Note: You have three other alternatives to essentially get the same
549 functionality at different levels, avoiding the unload of the buffers:
550 - Set the 'hidden' global option to avoid unloading all buffers. This
551 essentially avoids unloading every buffer that is loaded/created in
552 Vim, not just perforce windows.
553 - Manually set 'bufhidden' local option to "hide" for any particular
554 perforce window that you are interested in keeping around. Once set,
555 this prevents the buffer from getting wipedout, until explicitly
556 requested to do so. >
558 :setlocal bufhidden=hide
560 - Use the |:hide| command instead of quitting the buffer by other means,
561 such as the |:quit| command everytime. This again prevents the buffer
562 from getting unloaded even after it is hidden, but conveniently so
563 only when you use :hide command. If the buffer is later shown back
564 in another window and then hidden without having one of the other
565 settings appropriately set, then it will get unloaded and will get
568 See |PFWipeoutBufs| command for a way to cleanup all the hidden perforce buffers
569 that get accumulated, when you use one of the above techniques.
571 Note: There are other values that the 'bufhidden' can take, and so does the
572 g:p4BufHidden option, but they are not useful. They leave the perforce result
573 buffers lying around, without any useful side effect.
576 The plugin at any time can operate only on one preset depot, which by default is
577 "depot". If your perforce server has multiple depots or if your depot name is
578 not "depot", then you can use this setting:
580 :let g:p4Depot = 'proj'
582 to switch to a different depot than "depot". You can also do this at any time by
583 using the |PFSettings| command interactively.
586 By default, the plugin automatically reloads the file that get externally
587 modified as a side effect of some perforce commands (such as get and edit), if
588 the buffer inside vim is not yet modified. But you can disable this feature by
589 using this setting: >
591 :let g:p4Autoread = -1
593 A value of -1 means, use the 'autoread' vim setting and a value of 0 means don't
594 autoread and a value of 1 means autoread (the default).
597 The below are some additional settings that are related to configuring the
601 You can enable this setting to see additional information in the Vim ruler about
602 the current file's status. If the status for the current file doesn't exist yet,
603 nothing is shown. To make the status automatically available when you open a
604 file, you can enable the active status option, see |p4EnableActiveStatus|. You
605 can also manually obtain the status by executing the |PFRefreshFileStatus|
606 command any time. See |p4RulerWidth| on how to adjust the width of the ruler. By
607 default this setting is enabled, to disable it use, >
609 :let g:p4EnableRuler = 0
611 The plugin modifies the 'rulerformat' for this to work, so if you are also
612 modifying this, make sure you do it before the plugin gets loaded (doing it in
613 the vim startup file will ensure this.)
615 Note that enabling this option alone is not sufficient, you should also have the
616 |p4EnableActiveStatus| setting enabled or use the |PFRefreshFileStatus| command.
617 Also see |p4OptimizeActiveStatus| setting.
619 *perforce-ruler-width*
621 By default the plugin uses an additional 25 columns to show the perforce file
622 status. You might want to increase this value if you have long client names in
625 :let g:p4RulerWidth = 50
627 *perforce-active-status*
628 *p4EnableActiveStatus*
629 Enabling this option along with |p4EnableRuler| will provide you a quick look
630 at the current file's status in the perforce depot, as soon as it is opened.
631 By default this setting is enabled, but you can disable it if it introduces
632 significant delay for every file you open (as it involves running an external
633 command which in turn has to talk to a server). >
635 :let g:p4EnableActiveStatus = 0
637 If the response is slow and you would still like to have this feature, you can
638 disable this option and and use the |PFRefreshFileStatus| command, for whichever
639 file and whenever you want to see/update the ruler.
641 Besides using the status for showing the ruler, if available, it is also used to
642 make better decisions during some perforce operations.
644 Note, you need to still have the |p4EnableRuler| setting enabled to actually see
645 the status in the ruler. Also the default |p4OptimizeActiveStatus| setting
646 optimises it such that the "fstat" is done only the first time the file is
649 *perforce-active-status-ignore-patterns*
650 *p4ASIgnoreDefPattern*
651 *p4ASIgnoreUsrPattern*
652 These are regular expression patterns matching the filenames for which the
653 active status should be ignored. If the current filename matches the default
654 ignore pattern or the user defined ignore pattern, then it is assumed that the
655 file doesn't exist in the depot and no fstat is done on it. By default the
656 user pattern is empty and the default pattern is set to all files under tmp
657 and temp sub-directories and any file with log, dif, diff, out, buf and bak as
658 extension (case insensitive), which is expressed by the following pattern: >
660 '\c\%(\<t\%(e\)\?mp\/.*\|^.*\.tmp$\|^.*\.log$\|^.*\.diff\?$\|^.*\.out$\|' .
661 \ '^.*\.buf$\|^.*\.bak$\)\C'
663 To add additional patterns, the "p4ASIgnoreUsrPattern" should be used. The
664 "p4ASIgnoreDefPattern" can however be set to an empty value such that the
665 default pattern is completely ignored. Setting the default pattern to empty
666 string without defining the user pattern will completely disabled this feature,
667 resulting in a 'p4 fstat' call to every file that is opened (the file still
668 needs to be under the client root).
670 *perforce-optimize-filestatus*
671 *p4OptimizeActiveStatus*
672 Enabling this option along with |p4EnableActiveStatus| and |p4EnableRuler| will
673 allow the plugin to determine a brief status of the file in perforce and show it
674 as part of the ruler, without loosing much of the responsiveness. When you
675 enable this option, the plugin determines the status only the first time you
676 open the file and any other time there is a possibility for change in the status
677 (after executing the |PEdit|, |PRevert| etc.) and when you manually ask the
678 plugin to update the status using the |PFRefreshFileStatus| command. By default,
679 this option is enabled, to disable it use, >
681 :let g:p4OptimizeActiveStatus = 0
683 When this option is set, the current file status shown in the ruler may not be
684 the most up to date status, so when it is important (see
685 |perforce-negative-revisions|) make sure you update it manually.
687 *perforce-file-launcher*
689 This setting is used to choose the launcher application for executing the
690 |PFileLaunch| command in a filelist window. For non-windows platforms, this
691 needs to be explicitly set before you can use the |PFileLaunch| command, but on
692 windows, this by default is set to the following command: >
694 start rundll32 url.dll,FileProtocolHandler
696 This works almost the same as double clicking the file under explorer, so proper
697 file associations are assumed. You can however change the command to whatever
700 *perforce-dynamic-client*
701 For those users who have a need to dynamically switch between different perforce
702 clients, the plugin provides ability to set expressions that can be used to
703 provide call back hooks and determine the appropriate client. This is especially
704 useful when you have multiple clients mapped on to the same root and there is a
705 way to deduce the client based on the usage patterns and or current file.
709 These by default are set to an empty string, but can be assigned any Vim
710 expression that is valid on the RHS of a variable assignment. The expression is
711 evaluated and the result is used as the corresponding setting.
713 The "p4CurPresetExpr" setting is used only when using |P4CONFIG| setting. The
714 "p4CurDirExpr" at any time can also be used to determine the working directory
715 of the p4 operation, which in turn could impact which |P4CONFIG| file is picked
718 For the more demanding users, these expressions provide the call-back hooks
719 required to determine the client based on your environment.
721 Note that when you specify an expression which returns a different current
722 directory than the current Vim working directory (as returned by |getcwd()|),
723 the plugin doesn't attempt to modify any relative filenames that you specify on
724 the command-line to be relative to the new directory, so you need to make sure
725 you specify a valid filename in this case (or specify full paths all the time).
726 This could get tricky especially if you can't predict which directory your
727 expression would return. If your logic to find the current directory is really
728 that complex, then you could use the experimental API (see |perforce-API| that
729 the plugin provides to manipulate the filename arguments yourself from with in
730 the "p4CurDirExpr" before returning the directory name. However, while adding
731 new filenames to arguments (such as the default filename for certain commands)
732 the plugin automatically uses full filenames, when you specify a "-d" option on
733 the command-line or through the return value of "p4CurDirExpr".
735 It is recommended to return an empty string from "p4CurDirExpr", when the
736 directory is same as Vim's current working directory.
738 See also |perforce-switch-client|.
740 See |perforce-tips| for an interesting and useful idea for using "p4CurDirExpr"
744 This is an experimental feature, so defaults to 0.
746 Use this setting to make the plugin look into your client View: mappings while
747 translating depot paths to local paths and vice versa. The plugin translates the
748 paths without needing to run "p4 where" command, by extracting the View: data
749 from the client specification and building an internal representations for that.
750 This is done the first time the translation is required and it is cached to
751 avoid executing the "p4 client" command everytime. When the views in your client
752 specification change, you need to manually update this mapping by running the
753 |PFUpdateViews| command.
755 Make sure you don't have any syntactic errors in your views (such as unmatched
756 wildcards), as the plugin is not as forgiving as perforce itself in handling
757 them (this is done for simplicity).
758 ==============================================================================
761 The perforce plugin comes with a Vim syntax plugin for perforce filetype, and
762 works even when the |perforce-filetype| plugin is not setup. Most of the
763 output windows generated for perforce commands are set to the "perforce"
764 filetype and results in automatically sourcing this syntax file. Like any syntax
765 plugin, you can do further customizations and overrides from your vimrc or from
766 an "after" plugin (as the case may be). To customize syntax colors, here is a
767 complete list of all the syntax groups that the plugin defines (replace the tag
768 on the right hand side with your own preferred highlight group such as Comment,
771 hi link perforceSpecKey <your_preferred_highlighting_group>
772 hi link perforceComment <your_preferred_highlighting_group>
773 hi link perforceDate <your_preferred_highlighting_group>
774 hi link perforceCommands <your_preferred_highlighting_group>
775 hi link perforceHelpKeys <your_preferred_highlighting_group>
776 hi link perforceClientRoot <your_preferred_highlighting_group>
777 hi link perforceKeyName <your_preferred_highlighting_group>
778 hi link perforceDepotFile <your_preferred_highlighting_group>
779 hi link perforceLocalFile <your_preferred_highlighting_group>
780 hi link perforceVerSep <your_preferred_highlighting_group>
781 hi link perforceVersion <your_preferred_highlighting_group>
782 hi link perforceSubmitType <your_preferred_highlighting_group>
783 hi link perforceDefaultSubmitType <your_preferred_highlighting_group>
784 hi link perforceViewExclude <your_preferred_highlighting_group>
785 hi link perforceDepotView <your_preferred_highlighting_group>
786 hi link perforceClientView <your_preferred_highlighting_group>
788 ==============================================================================
791 The plugin comes with a help browser to browse the perforce help from within
792 vim window and move back and forth between different help pages. To start the
793 help just type |PH| or "PF help" command or alternatively choose the appropriate
794 menu entry. The plugin opens a new window that is positioned the way the vim
795 built-in help does. Once you close the help window, all the other window sizes
796 are restored, again the way the vim built-in help does.
798 Once you are in the help window, you can see that the perforce help keywords
799 are highlighted with a different color. To get additional perforce help on the
800 keyword, you can just move on to the keyword and press |Enter| or |K|. You can
801 also press double-click with your left mouse button.
803 The |PH|, |PHelp| or "PF help" command takes a set of arguments that are passed
804 to the perforce help command, which makes it easier to get to the help page if
805 you know the keywords. The |PH| and |PHelp| commands also support command
806 completion for help topics.
808 You can use <BS> and <Tab> to navigate the help history. This makes it easy
809 to view the perforce help and makes it feel like a hyper-text browser. Use "q"
810 or any other vim command to quit the help window.
811 ==============================================================================
815 *perforce-global-options*
816 *perforce-command-options*
819 The plugin defines a set of new commands to interact with perforce. The most
820 basic command is the "PF" command that is equivalent to the "p4" command on
821 the shell. This command takes arguments that are processed and passed to the
822 external p4 command and the output is collected back. Depending on the type of
823 command and various user settings, the output is either displayed in a new
824 window, a preview window or in a dialog box.
826 The command syntax resembles that of p4 command. There are five different types
827 of arguments that can be passed to PF command:
829 :[range]PF [<p4 global options>] <p4 command>
830 [<p4 command options>] [<arguments>]
832 All the argument sections are optional except for the command name itself. It
833 provides the flexibility to issue complex commands (essentially anything that is
834 possible at the shell prompt) such as the below:
836 :PF -c client -u user integrate -b branch -s source target1 target2
838 where, the "-c client -u user" are global options, "integrate" is the p4
839 command, "-b branch -s source" are the command options and the "target1
840 target2" are the arguments to the corresponding perforce command.
842 Note: See |perforce-common-options| for informaton on providing global options
845 All commands executed through "PF" go through a common internal function that
846 does argument validations/modifications/customizations etc. in addition to any
847 command specific operations. This results in a very consistent argument handling
848 throughout all the perforce commands.
851 " Run p4 diff on the current file and display the diff in a new window.
854 " Show all the opened files under the src directory (assuming you we are
855 " currnetly above this directory) in a new window.
858 " Open the client specification for editing.
861 Most commands take variable number of arguments. Some commands that require a
862 filename default to current file or ask you for an argument, if you didn't pass
865 You can additionally pipe the output of p4 through external commands (filters)
866 before the plugin sees the output. Anything after an unprotected bar ("|") is
867 considered as the external filters and so is specially treated by the plugin,
868 and the processing on such arguments is reduced to a minimum, which means that
869 you need to take care of the shell specific issues (such as enclosing the
870 arguments in quotes etc.) yourself. If you need to specify the bar symbol as
871 part of the perforce arguments (not really as the shell pipe symbol), then you
872 need to protect it with a back-slash, as discussed in the
873 |perforce-special-chars| section.
875 Example (useful for older versions of p4 client that didn't support -u
877 PChanges -s pending | grep hari
879 If you find yourself using a combination frequently, you can create a new
880 command for it to make it easier to type. For the above combination, the
881 following can be placed in .vimrc:
883 command! MyPChanges PChanges -m -1 -s pending | grep hari
885 Note, If you want to by-pass additional command specific processing, then you
886 can use the |PFRaw| command instead of the "PF" command.
888 The :PF command also supports custom command completion, to complete partial
889 perforce command names as well as filenames. Most filename expansions
890 automatically happen (like, %, <cfile> etc.), and # followed by a revision
891 specifier is treated specially when occurred at the end of the argument, and is
892 prevented from getting expanding as a Vim buffer name.
894 *perforce-special-chars*
895 Some of the characters in the arguments are treated specially by the plugin,
896 unless they are protected by prefixing them with a back-slash. The characters
897 that are treated specially are:
899 character special meaning ~
900 <space> argument separator.
901 & codeline modifier. See
902 |perforce-alternative-codeline-modifier|
904 \ protects other special characters, unless protected by
907 *perforce-command-mode-specifier*
908 *perforce-filter* *perforce-pipe*
909 You can also specify the run mode of the perforce command as one of the "run"
910 (default), "filter" or "pipe" by specifying one of the '++r', '++f' or '++p'
911 option respectively to the PF command in the <p4 global options> section as
912 described in the |perforce-commands| section. These options are just used as
913 directives to the command-processor and are not passed to the external p4
914 command. The "filter" and "pipe" modes are most useful with the "-x -"
915 perforce global option (see ":PH usage" for details) and "display" mode is used
916 mainly for internal purposes.
919 ++p Write (pipe) the lines specified by the given [range] to the p4
920 command on standard input. This works like the |:write_c| command.
921 This only pipes contents to p4, and doesn't read the output back, so
922 the contents are not effected.
923 ++f Filter the lines specified by the given [range] through the p4
924 command. This works like the |filter| command. You can create a new
925 buffer or modify buffer containing the output of another perforce
926 command, and pass the contents as arguments to a perforce command
927 and get back the results. In fact the '++c' option of diff does
928 exactly this. It first obtains the list of opened files in the given
929 change list and passes them as arguments to the diff command. See
930 |perforce-extensions|. The |PW| command is just an alias for this
931 feature so that you can skip the bang for convenience (you can't
932 specify -x option with this command, however).
934 The default [range] for the ":PF" command is the whole buffer (1,$). There is no
935 direct equivalent of Vim's |:read!| syntax here, but it can easily be done using
936 the "filter" mode on an empty line created at the location where you want to
937 read the output of p4 command.
939 *:PEdit* *:PRevert* *:PAdd*
940 *:PDiff* *:PDiff2* *:PPrint*
944 *:PSubmit* *:PUnlock*
945 *:PClient* *:PClients* *:PUser*
947 *:PBranches* *:PLabel*
948 *:PLabels* *:PJob* *:PJobs*
949 *:PJobspec* *:PResolve*
950 *:PChange* *:PChanges*
951 *:PDepot* *:PDepots* *:PHave*
952 *:PDescribe* *:PFiles* *:PFstat*
954 *:PLabelsync* *:PIntegrate*
957 While the perforce commands can be executed using the "PF xxx" syntax, some
958 of them have an equivalent PXxx command. So the following two: >
966 are identical. However, if you intend to pass some global arguments to p4,
967 then you are forced to use the first syntax. E.g., if you want to change the
968 user specification of another user, instead of changing the P4USER env.
969 variable, or using the |PFSwitch| command, you can use the following approach:
971 :PF -u other_user user
974 The describe command by default adds the "-s" option to avoid generating the
975 diff, unless a diff option is explicitly specified (implying that you would like
976 to see the diff too).
978 Note that the commands that normally prompt a confirmation message (such as
979 revert) accept a "++y" argument to avoid the prompt.
981 :PF ++y revert -c 12345
983 *:PE* *:PR* *:PA* *:PD* *:PD2* *:PP*
985 Some of the more frequently used commands have a shortcut to make it faster to
986 type. Following table gives the mapping:
994 PH help |perforce-help|
999 You can also define your own shortcuts easily, e.g., >
1001 :command! -nargs=* PB :PF branch <args>
1003 Place this command in your .vimrc so that it gets executed every time you
1007 PFRaw command is like |PF| command except that it bypasses all the processing
1008 that the |PF| command does. You should be able to pass most of the perforce
1009 arguments as they are to this command. The raw output from the p4 command is
1010 collected and placed in a new window
1012 Note that you can't use PFRaw to execute any p4 command that requires user
1013 interaction (such as "PFRaw client") unless you can pass in a "-o" options to
1014 it. In fact the |PF| command and the corresponding specialized commands (such
1015 as PClient) pass the "-o" argument internally to generate forms.
1017 *perforce-initialize*
1018 *perforce-reinitialize*
1020 Changing some settings may have impact on other plugin or Vim settings, so to
1021 propagate these changes, you should execute the :PFInitialize command.
1022 When you want to change a setting while within Vim, you can directly set the
1023 value of the corresponding global variable, but you should also call the
1024 :PFInitialize command. It is recommended to use the |:PFsettings| command, which
1025 not only makes it easier to find and enter values for these settings, it will
1026 also execute :PFInitialize for you.
1029 You can remove the Perforce sub-menu from the main menu by using
1030 the following commands: >
1032 :let g:p4EnableMenu = 0
1035 You can re-enable the menu, may be the full-featured one by setting: >
1037 :let g:p4EnableMenu = 1
1038 :let g:p4UseExpandedMenu = 1
1042 To make the above process easier, the PFSettings command prompts you with a
1043 list of settings to select from (without the common p4 prefix) and let you
1044 modify them. You can optionally pass in the setting name and value on the
1045 command line too. If passing the setting name, you can use Vim's completion
1046 mechanism to complete partially typed in name.
1048 :PFSettings [setting name] [new value]
1050 The command reinitializes the plugin after making the modifications. A typical
1051 dialog to turn on perforce menu for a gvim window could look like this:
1054 0 User 1 Client 2 Password
1055 3 Port 4 Presets 5 ClientRoot
1061 Select the setting: 9<Enter>
1062 Current value for EnableMenu is: 0
1063 Enter new value: 1<Enter>
1065 You should see the menu turned on at the end of this process. You can quit the
1066 dialog at any time by just pressing <Enter> without typing anything.
1068 If you know the name of the setting (or use command-completion), you can specify
1069 the setting and its new value directly on the command-line, to avoid the
1070 dialogs. E.g., to change the default diff options: >
1072 :PFSettings DefaultDiffOptions -dwbu
1073 Current value for DefaultDiffOptions: "-du" New value: "-dwbu"
1075 Note, there is also an abbreviation defined for this command as "PFS".
1077 *perforce-switch-client*
1078 *:PFSwitchPortClientUser*
1080 If you are connecting to multiple perforce installations, the PFSwitch command
1081 can be used to quickly switch between them. For an explanation of how to
1082 store these configurations to avoid typing, or use the Settings menu, see
1085 When you want to switch to a different perforce server, or just switch to a
1086 different client or user, without leaving Vim or needing to change any
1087 environment variables, use the PFSwitch command in one of the following ways:
1089 1. Prompt for the setting to choose from. Enter the index in the list of
1094 2. If you know the index, pass it as an argument. >
1096 :PFSwitch <index into p4Presets starting with 0>
1098 3. To switch to an arbitrary setting, pass in the arguments as below: >
1100 :PFSwitch <port> [<client>] [<user>]
1102 As a special case, you can pass in P4CONFIG as the only argument to
1103 switch to using the P4CONFIG feature of the external p4 command (see
1104 also |perforce-dynamic-client| and |perforce-P4CONFIG|. You can use Vim
1105 command completion mechanism to complete from the |p4Presets|.
1106 4. You can also use PFSwitchPortClientUser which prompts you for the
1107 individual values. >
1109 :PFSwitchPortClientUser
1111 See also |p4Presets|.
1113 Note, this command resets the cached file statuses of all the buffers such that
1114 their statuses are determined again based on the new client.
1117 This command can be used periodically to cleanup all the hidden perforce buffers
1118 that are not already wipedout because they are not yet unloaded (see
1119 |p4HideOnBufHidden| for ways to do this). By default, this command only prints
1120 the list of buffers that will be wipedout, so to actually wipeout the buffers,
1121 run the command with "++y" option. >
1125 *perforce-update-views*
1127 Use this command to update the internal structures corresponding to the client
1128 view mapping. When run, it discards the local cache and reconstructs it by
1129 running "p4 client" command.
1130 ==============================================================================
1132 *perforce-revisions*
1133 For convenience most commands (such as sync and print) take in a revision (as
1134 specified by "help revisions") as the last argument and apply it to the
1135 current file. You need to however protect the '#'s with a backslash such that
1136 it is not substituted by vim with the current alternative-file |#|.
1139 :PP \#1 - To see the revision 1 of the current file.
1140 :PP @2002/01/01 - To see the current file as of a date.
1141 :PP @65000 - To see the current file as of change 65000.
1143 *perforce-negative-revisions*
1144 In addition, you can also pass in a negative or positive number as a revision
1145 to specify an offset from the have revision. If you have the
1146 |perforce-active-status| feature enabled, the have revision value is available
1147 automatically, otherwise the plugin executes the file status such that it can
1148 generate the new revision after the offset. >
1150 :PP \#-2 " To see the (#head - 2)'th revision.
1151 :PD2 \#-1 \#-0 " Diff between the have and the previous revisions.
1152 :PD2 #\#have #\#head " Diff between the have and the head revisions for
1153 " the alternate file..
1155 Note: Observe the "-0" given as the revision number to mean the head revision.
1157 Note: PD2 (which is a shortcut for "PDiff2" or "PF diff2") also supports an
1158 interactive mode in which you can just type in PD2 by its own with no
1159 arguments, and the plugin will prompt you to specify the two revisions. You
1160 can specify any revision specifier that is normally supported on the
1161 command-line, in addition numbers are always treated as revisions so you don't
1162 have to prefix them with a \#. >
1166 Version 2? 2002/12/15
1168 Note: To be able to specify revision offsets, you need to have all the resultant
1169 files already open in the current vim session.
1171 *perforce-alternative-codeline-modifier*
1172 Another convenient feature supported by plugin is to allow specifying an
1173 alternative codeline in addition to the revision specifiers by using the '&'
1174 modifier. Suppose you want to diff between the revision 2 of the currently
1175 opened file with the head revision of the same file but from another codeline
1176 called 'other', then the following syntax makes it easy >
1178 :PD2 \#head&other \#2 " Same as 'PD2 \#1 \#2' if 'other' is the parent
1179 " codeline and if they are in sync.
1181 You can pass multiple such modifiers too, though the main use is with the
1182 depot-modifier as described below.
1184 *perforce-depot-modifier*
1185 The '&depot' modifier is treated specially. Instead of treating 'depot' (or the
1186 name of the current depot) as an alternative codeline, the filename is converted
1187 to its corresponding depot name. This is useful if the local file is not part of
1188 your client spec or is deleted from the depot. See also
1189 |perforce-edit-alternative-file| >
1190 :PF filelog a-deleted-file&other&depot
1193 *perforce-local-modifier*
1194 The '&local' modifier is treated specially. Instead of treating 'local' as an
1195 alternative codeline, the filename is converted to its corresponding local name.
1197 ==============================================================================
1200 *perforce-specifications*
1201 *perforce-interactive-commands*
1202 Most of the perforce forms can be edited right from with in vim. The perforce
1203 command line normally invokes the external editor to edit the forms and when
1204 you save and quit the editor, the form is read back and the corresponding
1205 settings are updated. E.g., the following steps describe how you modify client
1206 specification using the p4 command:
1210 # A Perforce Client Specification.
1212 # Client: <so and so>.
1217 Client <so and so> saved.
1219 The aim of the plugin is to be able to do most of such actions without
1220 needing to leave Vim. So when you execute a command that requires editing a
1221 form, the plugin automatically generates the form in a new window for you to
1222 edit. You can then modify it as you would normally in the external editor
1223 invoked by the p4 command, and to finally save it, use the normal |:write| or
1224 the special "W" (|perforce-W|) command. The plugin then tries to send the
1225 changes back to the server and generates the result also on the same window. The
1226 entire process would appear the same as above, except for
1228 1. you would use "PF client" or |PClient| in Vim, instead of the
1229 "p4 client" in the shell.
1230 2. Edit the specification as you would otherwise.
1231 3. The specification will be automatically written back to perforce when
1232 you save it like any other file (using :w or :W).
1234 Note that you can also use :wq to save and quit the window at the same time, but
1235 because of a known issue in Vim as of the release version of 6.1, your changes
1236 could be lost if the specification has an error. There is a patch available for
1237 this that fixes the problem, so apply the patch or use the safer :WQ command.
1239 What is the advantage?
1241 - You don't have to leave your Vim window or look for a command prompt.
1242 - If you change your mind, it is easy to quit/leave or even postpone
1243 (especially for submits, where you can convert it to a new
1244 change list) the spec window.
1245 - On errors you can just undo (by pressing 'u') and retry, as many
1246 times as you need to.
1247 - You have the option of opening the specification while viewing its
1248 corresponding list. E.g., you can execute "PF changes -s pending"
1249 and press "O" command on any change to open its change specification
1250 and easily modify it.
1251 - You can also view multiple specifications at the same time. You can
1252 for example easily move files from one change list into another.
1253 - You have additional commands defined local to the spec window, that
1254 are specific to the type of spec being edited.
1255 - Based on your working habits, you have other advantages that are
1256 inherent in using the same Vim session for multiple things.
1257 - It is much easier to use the Vim editing techniques to filter the
1258 filelist or edit the description instead of using the GUI in p4Win.
1259 - To me, it is also more fun to do it this way :)
1261 Unlike in earlier versions of the plugin, the specification buffers are now
1262 regular buffers, so they get marked as 'modified' when you start editing them.
1263 This prevents you from accidentally quitting the buffers, without writing them
1264 back to perforce. Also, Vim creates 'swapfile's for these buffers, so in case
1265 your session crashes, you can retrieve your changes (such as the description or
1266 your filelist) from the swapfile (see |crash-recover|). The swapfile will
1267 usually be created in the current directory or in a fixed directory specified by
1268 'directory' setting. When working with perforce specifications, the swapfiles
1269 could also be created in the temp directory, as the buffer names are often
1270 invalid on the file system (in which case the swap filename may not be that
1275 The W command accepts arguments that are in turn passed to the corresponding
1276 p4 command, so you can pass additional arguments such as "-r" while using
1279 There is also a WQ command which is same as the W command except that it also
1280 close the form window when there are no errors.
1282 The equivalent menu entries are "Save Current Spec" and "Save and Quit Current
1285 *perforce-changelist*
1286 The change command accepts a set of perforce filename patterns that are
1287 passed directly to "opened" to filter the files that should be included in the
1288 changelist. Without specifying the patterns, the command would work exactly the
1289 way the native "p4" command works, which means the changelist will start with
1290 all the opened files that are in the "default" changelist.
1292 ==============================================================================
1295 The submit command is handled slightly differently than other interactive
1296 commands, as the "PF submit" or |PSubmit| internally runs the "PF change"
1297 command to generate a submission template. There are a few additional features
1298 implemented which are discussed below.
1300 PSubmit command accepts additional arguments which are passed in as they are
1301 to "opened" command to generate the list of files to submit, so it is possible
1302 to create the template with a set of files to submit such as, "PSubmit % #" to
1303 submit the current and alternate files only (which is more flexible than the
1304 native command). Of course you can always run with out arguments to generate a
1305 full list of files and then remove the ones that you don't want. You can also
1306 pass in the -c changelist# to submit the given changelist non-interactively (or
1307 submit it from "changes" list). You can convert a submission template into a
1308 changelist by simply using the PSubmitPostpone instead of the W or WQ command.
1309 Similarly, when you are in the change specification, you can use the
1310 PChangeSubmit to submit the current change instead of first saving it using W or
1311 WQ command and then submitting the change list using the "PSubmit -c
1314 On partial errors during the submissions (such as those that require a resolve
1315 before submission), perforce sometimes automatically creates a changelist for
1316 the files in the submission template, in which case the changelist number is no
1317 longer "new" and the status is no longer "pending", so the plugin automatically
1318 detects this scenario and adjusts the template for these values. All you have to
1319 do in such cases is to 'undo' as you normally would, and fix the error before
1320 trying to submit again.
1322 Note, arguments such as '-r' are remembered when the PSubmit is first invoked
1323 and are used during the :W or :WQ command.
1325 ==============================================================================
1327 *perforce-list-commands*
1328 *perforce-list-view*
1329 *perforce-item-list*
1330 When executing a perforce command that generates a list of {something} such as
1331 changes, you have special commands defined that are local to the buffer and
1332 are specific to the list you are viewing. This allows you to visually perform
1333 some operations on the individual item without needing to type a separate
1334 command on the item.
1336 There are commands defined for both the commandline as well as key mappings
1337 and menu items for these operations. Note however that the same mapping can
1338 behave differently on different list views, depending on what is the list that
1339 you are viewing. E.g., pressing D normally means delete the specific item, but
1340 on a filelog window when you select two history entries (select all the lines
1341 between the two versions, inclusive) and press D, you get a diff between the two
1344 There are some generic list commands that work in most of the list views with
1345 somewhat consistent behavior:
1347 Note that for commands that generate a list of files (such as opened), there
1348 is a different set of commands defined, see |perforce-filelist|.
1350 *perforce-common-list-commands*
1351 These commands are available in all the listing windows.
1353 *:PItemDescribe* *:PItemOpen*
1355 Command Key Meaning ~
1356 PItemDescribe <Enter> Describe the current item. This shows a
1357 summary of the current item in a
1359 PItemOpen O Open the current item for editing.
1360 PItemDelete D Delete the current item. You will have be
1361 prompted to confirm the deletion.
1363 *perforce-client-list*
1364 You can use all the commands described in |perforce-common-list-commands|, as
1368 Command Key Meaning ~
1369 PClientsTemplate P Using the current client as a template,
1370 start creating a new client spec. You will
1371 prompted for the name of the new client.
1373 *perforce-labels-list*
1374 You can use all the commands described in |perforce-common-list-commands|, as
1377 *:PLabelsSyncClient*
1378 *:PLabelsSyncLabel* *:PLabelsFiles*
1380 Command Key Meaning ~
1381 PLabelsSyncClient S Sync the client to the current label.
1382 PLabelsSyncLabel C Sync the the label to the current client.
1383 PLabelsFiles I List the files associated with this label.
1384 PLabelsTemplate T Using the current label as a template, start
1385 editing a new label spec. You will be
1386 prompted to enter the name of the new label.
1388 *perforce-changes-list*
1389 You can use all the commands described in |perforce-common-list-commands| as
1392 *:PChangesSubmit* *:PChangesOpened*
1394 Command Key Meaning ~
1395 PChangesSubmit S Submit the current change list. You will
1396 be prompted to confirm.
1397 PChangesOpened o List files associated with this
1399 PChangesDiff d Show diff for the current pending or
1400 submitted changelist.
1402 *perforce-filelog-list*
1403 You can only use the describe command described in
1404 |perforce-common-list-commands| however there are other convenience commands
1405 defined for this view:
1407 *:PFilelogDiff* *:PFilelogDSync*
1408 *:PFilelogDescribe* *:PFilelogPrint*
1409 Command Key Meaning ~
1410 PFilelogDiff D Show diff between two selected versions
1411 (works only in the visual mode).
1412 PFilelogDSync S Sync to the current version.
1413 PFilelogDescribe C Describe the changelist for the current
1415 PFilelogPrint p Run print on the current version.
1417 You can generate the diff between two version while viewing the history. For
1418 this, you need to select all the lines between the two version, inclusive, and
1419 press the 'D' key. You can also use the PFilelogDiff with a range of lines as
1420 a prefix, without needing to select the lines.
1423 You can mark the first version as 'a' using the 'ma' command and mart
1424 the second line as 'b' using the 'mb' command and execute: >
1430 When you execute the commands |POpened|, |PHave|, |PFiles| and |PDescribe| that
1431 generate a list of files, you can use the file list window to do further
1432 operations on the files.
1434 *:PFileDiff* *:PFileProps* *:PFileEdit*
1435 *:PFileRevert* *:PFilePrint* *:PFileSync*
1436 *:PFileChange* *:PFileLaunch* *:PFileLog*
1437 Command Key Meaning ~
1438 PFileDiff D Run "p4 diff" on the current file.
1439 PFileProps P Print the properties (fstat) of the
1441 PFileEdit I Edit (checkout) the current file.
1442 PFileRevert R Revert the current file.
1443 PFilePrint P Print the current file in the preview
1444 window. This is mostly same as
1445 PItemDescribe, but handles the deleted and
1446 binary files correctly.
1447 PFileGet Sync the current file to the revision
1448 specified in the filelist.
1449 PFileSync S Sync the current file to the head
1451 PFileChange C Open change list for the current file.
1452 PFileLaunch A Launch the current file. On windows, it
1453 works almost the same way as double clicking
1454 the file in explorer. On non-windows
1455 platforms, you need to explicitly configure
1456 a launcher command by using the
1457 |p4FileLauncher| setting. You need to have
1458 (correct revision of) the file already on
1459 the filesystem, if not first do a sync as
1461 PFileLog Run "filelog" on current file.
1463 In addition, the plugin sets up 'includeexpr' such that you can use |gf| and
1464 |<cfile>| on the depot files. Since |gf| would result in the current buffer
1465 getting hidden, the current perforce buffer showing the filelist could get
1466 wipedout (unless this is prevented using the techniques described in
1467 |p4BufHidden|). If you have any mappings using |<cfile>| they should work well.
1469 Note: There is no quick help available to see which commands are available and
1470 what the mappings are for any given perforce result buffer. However, the output
1471 of nmap command is pretty useful and sufficient for this purpose. Type the
1472 following command as it is to see the perforce commands with their mappings
1476 ==============================================================================
1478 *perforce-extensions*
1479 There are some useful extensions provided over the perforce commands to make
1482 |perforce-pending-change-diff| Restricting diff to an open changelist.
1483 |perforce-vim-diff| Diffing using vim's built-in diff feature.
1484 |perforce-external-diff| Diffing using external diff tool.
1486 *perforce-pending-change-diff*
1487 This provides an useful "++c" option to the PDiff command to specify a change
1488 number that is open on this client. The plugin internally queries the open files
1489 under this change list and restricts the diff to only these files. >
1491 PF diff ++c 1111 //depot/branch/src/...
1493 The above restricts changes to only the changelist '1111' and under the src
1496 *perforce-builtin-commands*
1498 The plugin provides two built-in commands vdiff and vdiff2 to view diff using
1499 the Vim's built-in diff features instead of using the perforce diff and diff2
1500 commands respectively. If you need to customize the view, then read help on
1501 |diff-options|. These commands do not accept any options and will ignore them if
1502 any are provided. Make sure you don't have any windows that have diff mode set
1503 before running these commands as otherwise they will participate in the diff
1510 These commands are an alternative to the perforce diff and diff2 commands that
1511 use the Vim's built-in |vdiff| feature to generate the diff. Both command work
1512 exactly same as both accept upto two arbitrary local or depot files as
1513 arguments, but while "vdiff" command works with the files as they are specified
1514 (local or depot paths), the "vdiff2" command tries to convert them to depot
1515 paths as much as possible. There is also difference in how they choose default
1516 arguments when the number of arguments is less than 2. The "vdiff" commands are
1517 also a lot more flexible than the "diff" commands in that you can mix any two
1518 filenames as arguments, including those from different codelines, local and
1519 depot files and even those that are not even related.
1521 With only one file (or the current file when no arguments) specified as
1522 argument, the "vdiff" command like the "diff" command, diffs the file against
1523 that of depot, where as the "vdiff2" command, like the "diff2" command prompts
1524 you to enter the two depot version that you would like to diff for the specified
1527 :PF vdiff " Diff the current file against depot.
1528 :PVDiff % &altBranch " Diff the current file against the same from a
1530 :PVDiff2 \#1 \#2 " Diff the revisions 1 and 2 for the current file.
1533 These commands always open new windows split vertically side-by-side to start
1534 diff settings (diff settings are local to windows), so that your existing
1535 windows are not disturbed. When you are done viewing the diff, you can just
1536 close the diff windows and be done. But in case you need to reset the diff
1537 settings, there is a command called "PFDiffOff" provided for convenience. The
1538 command is very flexible in the sense that, it can identify the diff windows
1539 that belong to one diff operation and when run from one of them, can turn off
1540 the diff settings on all the related windows. This is useful to incrementally
1541 add/remove diff windows using PVDiff and PVDiff2 commands. If run outside of any
1542 perforce diff windows, it turns off diff for all perforce windows.
1544 *perforce-default-diff-format*
1545 Pass the dummy option "-d" (with no diff flags) to perforce commands that
1546 produce diff output to force the format to be in the default diff format. This
1547 is useful in case the |p4DefaultDiffOptions| is used and you temporarily want
1548 the diff output to be of default type. This option is not really recognized by
1549 the p4 command, and so will be removed from the command string before seen by
1550 the p4 command (and so is merely used to avoid adding the default diff options).
1554 *perforce-external-diff*
1556 The "diff" command now supports running external GNU diff to generate the diff
1557 output. To use this feature, make sure you have GNU diff installed in the path
1558 and pass one or more of the valid GNU diff command options using the following
1561 +<short or long option>[=<optional argument>]
1563 E.g., to generate diff output for the current file in unified format with the
1564 whole file in context (like the diff output in p4Win), you could use the
1569 Just make sure that the number is large enough to include the whole file.
1572 :PDiff +strip-trailing-cr +context=10 +W=120 +w
1574 *perforce-execute-direct*
1576 This is a built-in command that executes arbitrary vim commands after
1577 processing the command-line the same way as it would if you executed any regular
1578 perforce command. This is useful to execute external perforce commands (though
1579 not limited to them) directly, when you find that you can't do some task using
1580 the features provided by the plugin alone. You typically want to execute
1581 perforce commands using Vim's |:!| feature, e.g.: >
1585 But if you want to take advantage of the various command-line shortcuts provided
1586 by the plugin, then you would just pass the command as it is to :PExec: >
1588 :PExec !p4 sync %&altbranch#3
1590 The above would sync the current file in a parallel branch called
1591 "altbranch" to the version 3. Using the command also has the other inherent
1592 advantages such as, you don't have to protect the filenanme special character
1593 such as "#". The plugin also performs the same escaping mechanism on the
1594 external command that it does on the regular plugin commands, however any
1595 filters specified are not currently escaped.
1597 Note, the above two commands are just examples that can easily be achieved using
1598 the following plugin commands: >
1601 :PF sync &altbranch#3
1603 ==============================================================================
1605 *perforce-misc-commands*
1606 These are some misc. commands that are provided by the plugin in addition to the
1607 commands that are already described.
1608 |PFRefreshActivePane|, |PFRefreshFileStatus|,
1609 |perforce-edit-alternative-file|, |PFSwitch|, |PW|, |PFToggleCkOut|,
1610 |PFLastMessage|, |PDiffLink|, |PDiffPLink|
1612 *perforce-refresh-active-pane*
1613 *:PFRefreshActivePane*
1614 This command allows you to refresh the active perforce window (the window where
1615 the cursor currently is). The window should have been a result of a perforce
1616 command, to be able to refresh it. There is also a menu entry and a normal-mode
1617 mapping <Leader>prap to do the same.
1619 *perforce-refresh-file-status*
1620 *:PFRefreshFileStatus*
1621 Use this command to manually refresh the |perforce-ruler|. Useful when you
1622 have the automatic refresh disabled by setting the |p4EnableActiveStatus|
1623 to 0. You can also use the normal-mode mapping <Leader>prfs to do the same.
1625 *perforce-edit-alternative-file*
1628 These commands allow you to open the current file from an alternative codeline.
1629 The syntax of the command is: >
1631 E [codeline] [files: default %]
1632 ES [codeline] [files: default %]
1634 The difference between the two is that ES opens the file by splitting the
1635 current window, where as E opens the file in the current window. You can specify
1636 more than one file in which case the first one is still opened, but the
1637 remaining files are just added to the buffer list so you can open them later
1638 using a buffer explorer, or using :e #<buf>. If no arguments are passed, (just
1639 type E or ES on its own), you will be prompted to enter the codeline.
1641 *perforce-write-file-contents*
1643 The |PW| command is a special command that you can use to filter the current
1644 file contents through p4. You can specify the range of lines that need to be
1645 written to the command and the default range is the entire file (1,$). The "W"
1646 (|perforce-W|) or "WQ" (|perforce-WQ|) command described in |perforce-forms|
1647 internally uses this command to write the form back to the perforce command and
1648 read the result back. The command itself uses the |perforce-filter| feature to
1651 The following command can be used to revert the contents of the current file
1652 without using the perforce "revert" command. You can save the file, but you can
1653 always do |:undo| to get back to your original contents (provided you haven't
1654 lost your undo history). So this can be used to temporarily revert contents to
1655 the depot version and then get back to your original version.
1661 Also see |perforce-command-mode-specifier| for alternatives to using this
1664 *perforce-toggle-checkout-prompt*
1666 This command can be used to disable/enable the automatic checkout prompt while
1667 editing the readonly files. This is useful while you are in a read-only vim
1668 (started with -R option), so even the files that are already checked out also
1669 appear as read-only files, in which case, you don't want to see the checkout
1670 prompt when you accidentally start modifying a file (or for that matter even
1671 when you deliberately modify a file).
1673 *perforce-last-message*
1675 Prints the last given message again.
1677 ==============================================================================
1679 *perforce-special-commands*
1682 You can use the special tag <pfitem> on the command-line to mean the current
1683 list item. This works very close to how |:<cword>| etc. work. The command-line
1684 parser would replace this with the value of the current item (which is dependent
1685 on the type of list view) at runtime. This is useful to create your own
1686 mappings/commands over what the plugin provides.
1688 *perforce-special-mappings*
1689 There are some special mapping created for the command-line usage.
1691 While you are in a list view (such as list of labels), you can get the name of
1692 the current label on to the command-line by just typing <Ctrl-X><Ctrl-I>. This
1693 is useful to quickly and accurately execute commands on the items that have
1696 On the same lines as the E command (|perforce-edit-alternative-file|), there
1697 is another command-line mapping created for inserting the name of an
1698 alternate file right at the command-line. You can do this by typing
1699 <Ctrl-X><Ctrl-P>. You will be prompted to enter the name of the alternative
1701 ==============================================================================
1704 These are available only when you install the perforce/perforceutils.vim plugin
1705 as described in the |perforce-installation| section.
1707 *perforce-diff-mode*
1708 *perforce-diff-hyperlink*
1709 *:PDiffLink* *:PDiffPLink*
1710 Executing various commands such as |PDiff| and |PDescribe| produce output in the
1711 form of perforce diff (very similar to GNU diff output). The plugin provides two
1712 commands to make it easier to navigate from the diff output to the original
1713 source file like a hyperlink. The location of the original source file and the
1714 line number are extracted from the diff output (supports the default, context
1715 and unified formats). To open the source file and take the cursor to correct
1716 location, use :PDiffLink command or press "O". To open the source file and
1717 position the correct location in the preview window, use :PDiffPLink or press
1718 <CR>. These commands are defined for only those windows that contain perforce
1721 Note that the commands can be executed on both the old and new source lines, and
1722 the plugin either opens the appropriate file on the local filesystem or
1723 "print"s the correct version from Perforce to position the cursor. When diff
1724 refers to a depot file and the corresponding local file is already open in Vim
1725 and has the same revision as of the depot file that the diff refers to, the
1726 plugin opens the local file instead.
1728 Note these commands are capable of handling regular GNU diff output formats too,
1729 so you can use it on diff outputs generated using the "diff" command alone.
1733 These commands provide the same functionality that |PDiffLink| and |PDiffPLink|
1734 provide in a diff windows, except that you can run them in any buffer that has
1735 diff style output. Mostly useful if you are viewing diff obtained in a patch.
1737 *perforce-show-conflicts*
1739 This command is useful while resolving conflicts using an interactive
1740 "p4 resolve" command. When you choose the "e" option to edit files, perforce
1741 generates a single file containing changes from ORIGINAL, THEIRS and YOURS. It
1742 is usually hard (especially when the conflicting region is large) to figure out
1743 what others have changed and how to resolve them. Using a visual merge tool
1744 usually helps, but this commands provides an alternative by allowing you to use
1745 the |diff-mode| features in Vim. Once p4 invokes Vim as the EDITOR using a
1746 tempfile as the argument, you can run this command to generate three vertical
1747 windows each containing changes from ORIGINAL, THEIRS or YOURS only, and invokes
1748 the |diff-options| on them. Edit the YOURS file as usual and use the |:diffget|
1749 command from within YOURS or the |:diffput| command from the other two windows
1750 to move diff regions into the YOURS file, and finally write the changes back to
1751 the original temp file using the |:write| command.
1753 *perforce-selectbuf-ftplugin*
1754 *perforce-selectbuf-integration*
1755 The perforce plugin now comes with ftplugin that adds some perforce commands to
1756 the SelectBuf buffer browser. If you have the SelectBuf plugin installed, you
1757 don't need to do anything special to take advantage of this. When you are
1758 viewing the buffer list, you can execute the following commands directly on the
1759 current buffer in the list, or the current selection of buffers:
1773 I also recommend also installing multiselect.vim plugin that you can download
1774 from www.vim.org that allows you to select multiple buffers that are
1775 non-adjacent to do operations on them. This allows you to e.g., submit a few
1776 files together that are spread out far from each other in the buffer list.
1777 ==============================================================================
1780 The plugin comes with an experimental API that you can use to extend the
1781 functionality and provide some integration. Please send in your feedback to
1782 improve the API. You should also look at the perforce/perforcemenu.vim and
1783 perforce/perforcebugrep.vim for examples.
1785 " Return the value of the variable in the script context (so add
1786 " appropriate prefix).
1788 " let curClient = perforce#PFGet('s:p4Client')
1789 String perforce#PFGet(String var)
1791 " Set the value of the specified variable in the script context, to the
1794 " call perforce#PFSet('s:p4Client', 'xxx')
1795 void perforce#PFSet(String var, String val)
1797 " Call the specified function in the script context with the arguments
1798 " passed and return the result. Pass appropriate number of arguments
1799 " based on the function that you are calling.
1801 " echo perforce#PFCall('s:PFIF', '0', '4', 'info')
1802 " let client = perforce#PFCall('s:GetSettingValue', 'Client')
1803 String perforce#PFCall(String func, ...)
1805 " Evaluate the given expression in the script context and return the
1806 " result. The expression can be any Vim expression that is valid on
1807 " RHS of a variable assignment.
1809 " let client = perforce#PFEval('s:p4Client')
1810 " let client = perforce#PFEval('s:GetSettingValue("Client")')
1811 String perforce#PFEval(String expr)
1813 ==============================================================================
1816 - If you are new to Perforce, try the help browser using the |PH| command. You
1817 can easily move back and forth in the help history using <BS> and <Tab> keys.
1819 - The :W and :WQ commands also accept arguments that are passed as they are to
1820 the external p4 command. If you forgot to specify '-r' option to PSubmit,
1821 you can still specify it to the :W or :WQ command.
1823 - How to quickly open the current file from a different codeline?
1827 - How to quickly and easily find and open a file, say x.y, which you know is
1828 somewhere under the current directory?
1830 :PF files .../x.y - List the files that match x.y in the codeline. This
1831 opens a new window with all the files that match x.y.
1832 You can move cursor to the file-line that you want to
1834 O - Open the file that is displayed under the cursor.
1835 ^Wo - Close all other windows (see |CTRL-W_o|).
1837 This technique can also be used with other wildcards that perforce supports.
1838 E.g, you can find all the shell scripts that are checked in to a branch by the
1839 following command (assuming they all have .sh extension):
1842 :PF files //depot/branch/.../*.sh
1844 - How to quickly and easily find and launch a file in its associated
1845 application (needs configuration on non-windows platforms)?
1847 :PF files .../x.y - List the files that match x.y in the codeline. This
1848 opens a new window with all the files that match x.y.
1849 You can move cursor to the file-line that you want to
1851 A - LAunch the file.
1853 - How to easily reach to a file that you know is currently checked out?
1855 :PO - This will create a new window with all the opened
1856 files. You can move cursor to the file-line that you
1858 O - Open the file that is displayed under the cursor.
1859 ^Wo - Close all other windows.
1861 - You can temporarily disable the p4DefaultListSize (by default set to 100)
1862 while running some list commands by using the -m -1 arguments, to see all
1865 :PChanges -s pending -m -1
1867 - The plugin defines some long normal mode mappings, which could be hard to type
1868 without making errors or pausing for a brief moment. To type in such long
1869 mappings comfortably, you can download and install the execmap.vim plugin from
1871 - You can create aliases for most used command combinations using the Vim
1872 |:command| feature (from your vimrc). E.g. the following gives my pending
1875 :command! PendingChanges :PF changes -s pending -u hkrishna -m -1 <args>
1877 - To quickly go to the lines that you have modified in the current file, open
1878 the diff window against the depot, scroll/find the line that you are
1879 interested in and use |perforce-diff-mode| features.
1885 - To quickly start over with the depot version, without needing to execute
1886 "revert" followed by an "edit", use the |PW| command.
1890 - To insert the output of any perforce command at the current location, first
1891 open a blank line and run the command using |PW.
1894 :.PW describe -s 100
1896 - Set "p4CurDirExpr" to the following:
1898 let g:p4CurDirExpr = "(isdirectory(expand('%')) ? substitute(expand('%:p'),
1899 \ '\\\\$', '', '') : '')"
1901 to have the commands run from the directory that you are currently viewing,
1902 instead of the current directory of Vim.
1904 - If your colleague sends you diff for review, you can make use of :PFDiffLink
1905 and :PFDiffPLink commands to make it easier to reach the "before" file. In
1906 addition, if your colleague's dev folder is accessible by you in the same m/c
1907 (typically for a UNIX server), you should be able to look at the "after"
1908 changes in context. Even if the dev folder is accessible only over the
1909 network, you can convert the local paths in the diff to the network paths
1910 (E.g., you could convert "c:\dev" to "\\tom\dev"), and browse the changes
1913 - Do you know that :PFDiffLink and :PFDiffPLink commands can be used on regular
1914 "diff" command output too?
1916 - To quickly search for change descriptions, you can print the list of changes
1917 matching a given restriction, with their descriptions and use Vim to search
1918 for the pattern. You can then describe the change for more information. Ex: >
1920 :PChanges -l //depot/branch/src/server/...
1923 - Use VDiff if you want to revert only parts of your changes.
1924 *perforce-explore-changed-lines*
1925 - Here is a technique I often use to track who and when someone made a
1926 particular change. The technique assumes you have a branch which includes all
1927 the releases (typically called "release" or "main"). You would first get the
1928 annotations as below: >
1930 :PF annotate -a &main&depot
1932 Locate the line that has been changed (you might find multiple lines due to
1933 reformatting) and identify the version. Run the below command to identify the
1934 change (can be executed from the annotate window): >
1938 This gives you the change number and integration history for that version.
1939 Sometimes this is not enough to find the origin branch, so you can continue to
1940 execute "annotate" and "filelog" commands until you find the original branch
1943 ==============================================================================
1945 *perforce-limitations*
1946 - Interactive resolves can't be done using the plugin. You can however use
1947 auto resolves by passing options such as -as to the 'resolve' command. See
1948 "PH resolve" for help on auto-resolves. Also take a look at the
1949 |PFShowConflicts| command.
1950 - The plugin can work with only one depot at any time, but you can easily
1951 switch between different depots by changing the |p4Depot| setting through
1952 the |PFSettings| command.
1953 - When executing commands that take a lot of time, such as syncing on the
1954 entire branch, Vim waits for the command to complete and exit before
1955 the plugin can display the result. So until Vim becomes more capable in
1956 executing external commands in this regard, I recommend not to run such
1957 commands using the plugin.
1958 - Since 'q' is mapped to quit the perforce windows, it is hard to record
1959 macros that involve dealing with perforce windows. A workaround is to
1960 create a new mapping to the "q" command and use that to start and stop
1961 recording instead, something like this:
1965 *perforce-troubleshooting*
1966 - If none of the perforce operations work for you, then make sure you set
1967 your |p4CmdPath| setting correctly. You can run PFS command and select
1968 CmdPath setting to see what the current value is. On windows, if you have
1969 back-slashes in the path, then make sure your 'shell' setting can honor
1970 them. The 'shellslash' setting is also important if you use a UNIX-like
1971 shells on windows. IF all seems to be well, then please report the problem
1972 to me with your 'shell' setting and OS details.
1973 - If you get E485 errors occassionally or most of the time, and your shell
1974 related settings seem to be fine, then point your $TMP and $TEMP
1975 environmental variables to some path that is shorter ("/tmp" instead of
1976 "C:/DOCUME~1/HARI/LOCALS~1/Temp").
1977 - If the online perforce help is not working (ie., you are reading this by
1978 directly opening the file, instead of by typing :h
1979 perforce-troubleshooting :), then make sure you ran |:helpt| command.
1980 - If you are not getting automatic checkout prompt when you modify a
1981 read-only file for the first time (and everything else seems to work
1982 fine), then make sure you set your |p4ClientRoot| property correctly. The
1983 plugin ignores any files that are not under your root from giving this
1985 - If vdiff and vdiff2 commands don't work for you, make sure the vimdiff
1986 itself works for you. Try running the following command on any two files:
1990 If the above command doesn't produce any diff though they are different,
1991 or gives any error messages, then first go through the help on |vimdiff|
1992 to get the standalone diff working.
1993 - While editing perforce specifications from commandline, if you don't see
1994 the perforce syntax or cursor is not positioned at a convenient position,
1995 then make sure you added perforce filetype as described in
1996 |perforce-filetype|.
1997 - If |perforce-ruler| doesn't work for you, make sure you have 'ruler'
1998 option set. Also make sure you didn't disable |p4EnableRuler| setting. It
1999 is also possible that another plugin is overwriting the 'rulerformat'
2000 setting (instead of appending to it, as done by the perforce plugin) after
2001 the perforce plugin configures it. Also, if you are in the 'paste' mode,
2002 Vim automatically disables ruler, so make sure you don't currently have
2004 - If you observe a noticiable delay in Vim startup time after you installed
2005 perforce plugin, it may be because, the plugin is trying to obtain the
2006 value of |p4ClientRoot| setting by executing the "PF info" command. You
2007 can avoid this by setting this property yourself in your vimrc.
2008 - If piping a spec manually to a perforce command such as 'change' or
2009 'submit' using ++p option is not working, make sure the command accepts a
2010 '-i' option to read the spec from stdin and that you are passing in this
2012 - If you get a weird invalid option error, or if the command behaves
2013 weirdly, make sure you don't have a typo in the command-name. The
2014 command-line parser recognizes only the known perforce commands, which
2015 makes an incorrect command name a global option, making it an invalid
2016 syntax. E.g., if you mistype "opened" as "open", you get an error that
2017 "-u" is an invalid option.
2019 *perforce-version-changes*
2020 These are just a summary of the changes done in the current and previous
2021 versions. Though I have done a good attempt to list all, I could have very well
2022 missed some changes.
2024 *perforce-changes-4.1*
2025 - Fixed broken handling of <SHOW DIFF> in describe windows. But it is better
2026 than before, as you can now describe multiple changelists and show diffs
2028 - For newer perforce servers, <Enter> on a pending change (in changelist)
2029 showed the file list twice. Removed special handling for this, which means
2030 for older perforce servers, you will see no file list.
2031 - Force a file status update on auto checkout.
2032 - File status handling has in general been improved.
2033 - Now executing command on multiple files that result in changing the
2034 file statuses (such as add, edit, revert etc.) will correctly result
2035 in their file statuses getting reset.
2036 - While create a new changelist or submitting a change, the Files:
2037 section is examined and the file statuses for all of them will be
2038 reset. This also works for most of the cases of modifying a changelist
2039 to remove/add files.
2040 - This will also solve a long standing issue that reload during submit
2041 doesn't update its file status.
2042 - All windows are getting navigatation commands mapped (like in help window)
2043 - Workaround for one of the E788 errors (originating from the plugin) during
2044 the auto-checkout. This part of the code has been cleaned up and
2045 simplified. During the auto-checkout, if there are other users editing the
2046 same file, it now results in the plugin echoing the output as a
2047 |WarningMsg|. If you missed to read the output (because you pressed
2048 <Enter> in advance), you can see it again using the |PFLastMessage|
2049 command. The other E788 originating from Vim code can't be
2050 fixed/workedaround, it has to be fixed by Bram.
2051 - Fixed broken submit from changelist.
2052 - When you create changelists, you can now safely undo to make any further
2053 changes, and save them. This also works for submissions (to edit
2054 description only), though you may have to remove the Files section before
2055 saving the change description.
2057 *perforce-changes-4.0*
2058 - Using Vim7 features, so it is no longer backwards compatible with older
2059 Vim releases. All the logic using multvals has been changed to take
2060 advantage of the Vim7 Lists, so it should be a lot more cleaner and
2062 - No longer depends on multvals plugin.
2063 - It is now autoloaded on demand, which means it will help your vim session
2064 load faster. Read the impact on the installation due to this change,
2065 |perforce-installation|.
2066 - A new Cancel option for checkout prompt, see
2067 |perforce-automatic-checkout|. The default for checkout prompt is now
2069 - The perforce/perforcemenu.vim needs to be loaded from your vimrc if you
2070 want menu to be enabled. See |perforce-installation|.
2071 - The plugin no longer removes the global user setting variables but you
2072 still need to call |:PFInitialize| for effect of some settings to
2073 propogate further. This should have no user visible impact (except in rare
2074 cases). This will only make it easier to deal with settings. You can
2075 still use |:PFSettings| command conveniently for its prompting or
2076 completion features.
2077 - Setting a preset to the g:p4DefaultPreset directly now works fine.
2078 - Most settings can now be overridden at the buffer/window/tab level.
2079 - PFRefreshActivePane doesn't work well on the diff windows (especially when
2080 the ++c option is used).
2082 *perforce-changes-3.2*
2083 - Fixed PVDiff to work with two filenames. The problem was only with PVDiff
2084 command, as "PF vdiff" worked fine.
2085 - PFDiffOff command is a lot more flexible now, see |PFDiffOff|.
2086 - New command PPasswd for changing passwords.
2087 - Don't confirm revert if -a or -n option is passed.
2088 - Avoid accidentally loosing existing buffers while opening new ones from
2089 diff and other windows.
2090 - Recognize additional p4 commands as valid.
2091 - You can now pass multiple codeline modifiers, see
2092 |perforce-alternative-codeline-modifier|.
2093 - Misc. tuneups for peforce diff hyperlinking feature.
2094 - Misc. bugfixes in the menu.
2096 *perforce-changes-3.1*
2098 - This version introduces the concept of overriding settints at the
2099 buffer/window level (an extension of the existing support for
2100 b:p4Options). Makes it easier to work with multiple clients from a single
2101 vim instance. Currently only the p4Client/p4Port/p4User/clientRoot can be
2102 set at buffer/window level.
2103 - Now view mappings are maintained separately for each client. This allows
2104 us to easily work with multiple clients at once. Also see
2105 |perforce-buffer-local-options|.
2106 - For diff hyperlinking, avoid refreshing the depot file if it already
2108 - Now supports <pfitem> tag to mean the current list item. See |:<pfite>|
2109 - New :PExec command to make it easier to execute exeternal perforce
2110 commands directly, when plugin can't do what you want. See |PExec|.
2111 - PFDiffLink and PFDiffVLink commands couldn't handle "diff -r" output.
2112 - If the current directory is not same as the directory of file being
2113 resolved PFShowConflicts didn't work.
2114 - PItemOpen in describe window now opens the local file, as PItemDescribe
2115 can be used to open the depot file.
2117 - Negative revisions are not working any more. E.g., PP #-1
2118 - PW is not using the custom completion, so revision specifier (#1)
2119 still needs to be escaped.
2120 - While rerunning a command that opens up a new buffer (such as PD),
2121 unexpected warning messages about matching an existing buffer.
2122 Instead, it should silently refresh the output.
2123 - Diff hyperlinking, prints the depot file everytime, this causes
2125 - PFRefreshActivePane would fail if there are filename special
2126 characters in the command.
2127 - PF command now implements a special completion mode to complete both the
2128 perforce command as well as files. Now you no longer need to protect the
2129 revision specifier (#<revision) as long as it appears at the end of the
2132 *perforce-changes-3.0*
2133 - Discard the diff output if P4DIFF env. var. is set (Denis Perelyubskiy).
2134 - There is an experimental API to allow some modularization of the plugin.
2135 See |perforce-API|. There are plugin modules available under perforce
2136 directory that take advantage of this.
2137 - New PFBugReport command to generate "perforcebugrep.txt" file. This is
2138 implemented as a new module perforcebugrep.vim using the above API.
2139 - The menu creation is now separated as a new module that is executed on
2140 demand. Other than giving some modularity, this effectively reduces the
2141 resources consumed by the plugin, especially when the menus are disabled.
2142 - New settings and features that allow dynamic switching of perforce client
2143 settings (Mark Brophy). See |perforce-dynamic-client|.
2144 - The default options don't get saved with the perforce windows (Mark
2146 - IsFileUnderDepot() should ignore case for windows (Mark Brophy).
2147 - Some enhancements to the "diff-hyperlink" feature, see |PFDiffLink|.
2148 - The plugin now translates the depot paths to local paths and vice versa
2149 accurately by reading the client specification. This is an experimental
2150 feature and so will very likely have bugs in it. While reporting bugs,
2151 please include the "View" section in your client specification and the
2152 path. See |p4UseClientViewMap| and |PFUpdateViews|.
2153 - For consistency and to avoid potential conflict with the actual perforce
2154 commands, most of the plugin commands that are not associated with any
2155 external perforce command are prefixed with "PF". This involves renaming
2156 of the following commands. If you would like to continue to use the old
2157 command, you can add your own commands with the old names that in turn
2158 call the new commands.
2159 PWipeoutBufs -> PFWipeoutBufs
2160 PDiffOff -> PFDiffOff
2161 PToggleCkOut -> PFToggleCkOut
2162 PRefreshFileStatus -> PFRefreshFileStatus
2163 PRefreshActivePane -> PFRefreshActivePane
2165 PSwitchPortClientUser -> PFSwitchPortClientUser
2166 PLastMessage -> PFLastMessage
2167 PBugReport -> PFBugReport
2168 - :PFSettings command now optionally takes the name of the setting (as
2169 displayed in the interactive session) and the value. The command also
2170 supports completion, so you can type in a partial setting name and let Vim
2171 complete it for you.
2172 - I have changed the way the perforce client related settings are done.
2173 Instead of using three different settings, "p4Port", "p4Client" and
2174 "p4User", I have introduced a single setting for all the three called
2175 |p4DefaultPreset|. The old settings are no longer recognized and these
2176 will not appear when |PFSettings| is run. However, you can use |PSwitch|
2177 and |PSwitchPortClientUser| commands to change to an arbitrary client at
2178 runtime. Other than |p4DefaultPreset|, there are two new settings,
2179 |p4CurPresetExpr| and |p4CurDirExpr|. Also, to be consistent, the
2180 p4Password setting is no longer supported. Use "P4PASSWORD" environmental
2181 variable for the same effect, or just let the plugin prompt you for one
2183 - New command |PFileEdit| in filelist view.
2184 - New plugin perforce/perforceutils.vim. Adds a useful |PFShowConflicts|
2185 command. See |perforce-utils|. The |perforce-diff-hyperlink| feature is
2186 also moved into this module with some enhancements.
2187 - For consistency, some built-in options have been changed. Now all the
2188 built-in options should be prefixed with "++". The options prefixed with a
2189 single "+" are reserved for passing options to the external commands. The
2190 following options have been modified to accommodate this:
2191 Old option New option Scope ~
2192 +y ++y PF, PWipeoutBufs
2194 - New diff mode to execute external GNU diff command to generate the diff
2195 output. See |perforce-external-diff|.
2196 - New commands on filelist view, PFileLaunch, PFileLog. PFilePrint has been
2197 enhanced to print previous version if the head action is "delete" and
2198 avoid printing binary files.
2199 - Many misc. bug fixes and enhancements and general toning down of the code.
2200 - A new integration with SelectBuf plugin. If you install SelectBuf, you can
2201 execute a bunch of commands right from the buffer list. See
2202 |perforce-selectbuf-integration|.
2203 - The default value for 'bufhidden' setting in the perforce result buffers
2204 is now set to "wipe". This works much better than the earlier approach to
2205 wiping out buffers as they get unloaded, and gives better control to
2206 users. Consequently, the g:p4HideOnBufHidden option is now replaced with
2207 the g:p4BufHidden option.
2208 - The plugin no longer handles all the FileChangedShell events, instead only
2209 the events generated during the execution of the perforce commands are
2210 captured to refresh file-status. This is so that the default Vim mechanism
2211 is least impacted. To manually refresh the ruler see
2212 |perforce-refresh-file-status|.
2213 - New :PChangesDiff command in changes window.
2214 - Fixed the argument parser to recognize context size in the diff flags
2215 (such as "-du10"), didn't actually know that you could pass context to the
2216 diff flags. Also, the |perforce-default-diff-format| option has been
2217 changed from "-dd" to simply "-d".
2218 - All the perforce commands now implement a custom completion that completes
2219 arguments in a context sensive manner. They can also complete depot paths
2220 by running the "dirs" and "files" commands. In addition, |PHelp| supports
2221 help topic completion, |PFSettings| supports setting name completion and
2222 |PFSwitch| commands supports preset completion.
2224 *perforce-changes-2.0*
2225 - Renamed g:p4CodelineRoot to g:p4ClientRoot.
2226 - Fixed a problem with choosing a default username on cygwin.
2227 - Added support for showing ruler with the file status from "Tom Slee",
2228 Perforce plugin with some enhancements.
2229 - Added support to obtain the clientRoot from the perforce server, if it
2230 is not already defined.
2231 - More robust error handling. Now there is very less chance (or none) of
2232 messing up the current window.
2233 - Fixed to use setlocal instead of set command for changing some settings.
2234 - Filelog also honors the defaultListSize option.
2235 - Better formatting options for the form windows.
2236 - The default option for checkout file dialog is changed from "Yes" to
2237 "No". Use the |p4CheckOutDefault| option to get the old behavior.
2238 - On Windows, allow execution of commands containing filename special
2239 characters by replacing them with a [x] sequence. They are mapped as,
2249 - Now you can use -ve revisions to indicate previous revisions from the
2250 head. You can also use branch specifiers to mean the same file from a
2251 different branch. Also these enhanced revision specifiers are now
2252 acceptable anywhere.
2253 - Extended diff to take "++c" argument to specify change number. See
2254 |perforce-pending-change-diff|.
2255 - Added vdiff and vdiff2 commands. Added p4UseVimDiff
2256 option. See |perforce-vim-diff|.
2257 - Added PFileChange command for the filelist window.
2258 - You can now pass "++y" option to revert to skip the prompt.
2259 - New command |PFSettings| to interactively change the settings of a
2261 - The script now has a more robust and compact architecture, which actually
2262 helped reducing the size of the plugin even after adding many more
2263 features. I have also consolidated all the logic into one method described
2264 by a set of metadata variables. Adding new features in the future should
2266 - The opened list is now better than ever. You can use it to quickly reach
2267 to a file that you have already checked out of perforce. See
2269 - You now have a way to preserve the perforce windows from getting wipedout
2270 as soon as they are hidden. This feature can be used if you are intending
2271 to keep them opened for a long time (such as "opened" list windows).
2272 - You can now change the name of the depot from the default "depot". This is
2273 useful if you have multiple depots in your system.
2274 - I have extended the command syntax with the
2275 |perforce-command-mode-specifier| for the more demanding users.
2276 - The "change" command now takes perforce filename patterns to filter out
2277 the initial list of files that should be included in the change. The
2278 "submit" command already does this. See |perforce-changelist|.
2279 - You can now press "q" to quit in read-only perforce windows (David
2281 - Improved the handling of back-slashes and spaces in filenames.
2282 - The vim built-in :w and :wq commands work exactly like the :W and :WQ
2283 commands respectively. For "submit", they now prompt for confirmation,
2284 which can be suppressed by passing a "-y" option.
2285 - Now the specification windows are regular buffers. For reasons on why this
2286 is much better than the earlier approach, read towards the end of
2288 - The plugin now uses try/finally blocks to avoid leaking any changes done
2289 to global settings in case of unexpected errors.
2290 - The submit command now detects partial errors that results in an
2291 automatic changelist creation, and modify the template appropriately. This
2292 also works while creating a new changelist, so that after saving the
2293 changelist, you can just undo and continue making further changes.
2294 See |perforce-submit|.
2295 - Hyperlink the diff window to the source. Pressing O or <CR> on a line
2296 takes you to the source line. See |perforce-diff-mode|.
2297 - Fixed some bugs with passing special characters and whitespace to shell.
2298 - A dummy option "-dd" to mean the default diff format. See
2299 |perforce-default-diff-format|
2300 - A new ftplugin for perforce forms which can be made to work even while
2301 starting forms from p4 directly. See |perforce-ftplugin|
2302 - This help file itself is new.
2305 *perforce-known-issues*
2306 Not in any particular order:
2307 - PChangesDescribeCurrentItem doesn't work for pending changelists from
2309 - A deleted file is showing up as unopened.
2310 - Consider #none also as revision in the syntax highlighting.
2311 - I don't think the p4Depot setting is being handled correctly. We need to
2312 investigate how depots created using "p4 depot" are used.
2313 - There is a Syntax highlighting for: "<file>#1 - added as <file>". How is
2314 this message generated?
2315 - When you open a spec window with perforce wildcard patterns as arguments
2316 (such as "P4 submit .../*") saving works as long as you don't change the
2317 current working directory of Vim after creating the spec window, otherwise
2318 because of some weird behavior in Vim, you get an E212.
2319 - You can't login using the plugin.
2320 - <pfitem> should be handled at a higher level for it to be more useful.
2321 - During the auto-checkout, Vim will give error E788 if the ftplugin uses
2322 :compiler command. This is a known issue with Vim7.0 release, and might
2323 get fixed in a future patch.
2324 - When PFSwitch fails because the perforce server is not up, you are forced
2325 to switch to another setting and come back to it to select it again.
2326 - When reverting files from files view, if you select No for the prompt, it
2327 still refreshes the window.
2330 Here is a list of changes that I think will be useful to do, in no particular
2332 - PChangeSubmit etc. should have menu entries in change menu.
2333 - Sort change lists and show those that are by the current client and
2335 - The "nmap <buffer>" output can probably be used to generate a simple help.
2336 - A command to rename files (Raj). Invoke integrate and delete internally,
2338 - It will be nice if the change number is automatically remembered.
2339 Also, we should be able to set a change number which should be
2340 automatically applied to all the edits, deletes etc.
2341 - How can we support interactive resolves? Will it be worth doing it?
2342 - In filelist view, allow visual select on the files to be operated upon
2344 - I should be able to parse the output of p4 resolve using this command:
2345 sh -c "while true; do echo s ;done" | p4 resolve
2346 - How can we avoid prompting for checkout when the current vim session is
2347 in view mode (-R option)? For now just use PFToggleCkOut command in such
2349 - The script now has knowledge of client-view settings. There may still be
2350 places that assume that the branch name and local directory name are same.
2351 - The menus can be further improved.
2352 - The list specific menus should be disabled unless you are in that
2354 - Backup/Restore commands for opened files will be useful. For now, just use
2355 the included shell scripts.
2356 - A simple p4win style explorer will be helpful for quickly browsing the
2358 - Negative revisions for dates also? Is it possible using vim functions?
2359 - Check for unsaved buffers during submit. Requires us to look into the
2361 - There should be an option to show/hide deleted files in the filelists
2363 - The PPasswd can't be used when either the old or new password is empty.
2364 - There should be an option to have a single perforce-log window where all
2365 the output gets appended, instead of opening new windows for each command.
2366 - We should be able to pass file patterns to be used as the View while
2367 creating a new label command.
2368 - We should have a feature to diff2 in labels and changes views when started
2369 with a filename as an argument. Also diff from changes view.
2370 - A command to refresh only the files that are in a label. Works well for
2371 lables containing only a partial list of files.
2372 - Supporting backquotes could be useful when the shell is unixy.
2373 - In list views (and filelog view), we should be able to map the mouse
2374 presses such a way that single mouse click results in selecting the entire
2375 line and mouse drag automatically selects the entire line. We will then
2376 need to make sure all the list view local commands will work with visual
2378 - If the current buffer is a directory (i.e. opened with the vim
2379 filebrowser), it would be nice if the plugin could simply append '...'
2380 to the relative path, so something like PSync would make perforce sync
2381 all files under the current directory (Mark). In otherwords, it would make
2382 sense to append '...' to the directory name whenever a command that
2383 defaults to current buffer is executed on a directory buffer.
2384 - How about using v:dying to determine if the vim session is crashing and
2385 preserve the spec buffers?
2386 - Executing "admin" command shouldn't open up a new window.
2387 - Better support for "monitor" command.
2388 - There should be an option to position the current line in the diff (if
2389 exists) (like view current line in the diff).
2390 - While viewing a directory, it will be nice if the file completion
2391 happens relative to the directory that is being viewed, rather than the
2392 working directory of Vim. We probably should have an option to turn it
2394 - It is possible to have a command that starts p4win with options such as
2396 - vdiff should print the have version not head version, unless this
2397 information is for some reason not available.
2398 - While doing custom expansion for files (:PF command), the spaces in the
2399 filenames should be escaped.
2400 - For diff hyper linking, there should be a way to always open the depot
2401 file (even for the context lines).
2402 - In DiffLink, detect the column position also. Also add a way to jump the
2403 diff region containing the current line.
2404 - There should be a way to force deletion from the users list (-f option).
2405 - Need a "blame" built-in command to produce annotated output with change
2408 *perforce-bugreporting*
2409 Please read the entire plugin online help before you report any bugs, as it will
2410 help clear up scenarios which may not indeed be a bug. In addition,
2411 - Refer the p4 user manual and online help to be clear about the right
2413 - Check if it is already mentioned in the |perforce-limitations| or
2414 |perforce-known-issues| sections.
2415 - Run :PFBugReport command to generate "perforcebugrep.txt" file in the
2416 current directory and attach that with your email. Before sending this
2417 out, check to make sure it doesn't contain any confidential information!
2419 Please send your reports to hari_vim at yahoo dot com.
2421 *perforce-acknowledgements*
2422 - Tom Slee (tslee at ianywhere dot com) for his idea of creating a status
2423 bar with the p4 fstat information (see
2424 http://www.vim.org/script.php?script_id=167).
2425 - Leo L. Schwab (leo dot schwab at openwave dot com) for reporting problems and
2426 helping me with debugging them.
2427 - David Fishburn (fishburn at ianywhere dot com) for his idea with mapping the
2428 'q' key to quit non-editable perforce windows, and reporting various bugs.
2429 - Mark Brophy (mbrophy at esmertec dot com) for his ideas with using P4CONFIG
2430 and others that allow dynamic configuration.
2431 - Various others for sending bugs, patches, ideas and feedback. Some of them
2433 - Denis Perelyubskiy (denisp at CS dot UCLA dot EDU)
2434 - Kevin McCarthy (tunacat at yahoo dot com)
2435 - Paul Wright (paul at noctua dot org dot uk)
2436 - Reva Revadigar (reva dot revadigar at autodesk dot com)
2437 - Peter Hutkins (PHUTKINS at altera dot com)
2438 - Brett Humphreys (bretth at aiinet dot com)
2439 - Craig Emery (craig dot emery at ntlworld dot com)
2441 vim6:tw=80:ts=8:ft=help:ai:sw=4:et
git://git.iain.cx/iain / profile.git / blob