*perforce.txt*  A feature Rich Perforce SCM Integration for Vim.
                    Requires Vim 6.0
            Last Change: 01-Sep-2006 @ 16:54
          Since Version: 1.4
               Revision: 1.3.0
         Plugin Version: 4.1
                 Author: Hari Krishna Dara (hari_vim at yahoo dot com)

                                            *perforce-introduction*
                                            *perforce-plugin*
This is a fairly complete integration with the perforce version control system
for the most commonly used operations, including many administrative commands.
It includes a great menu that is modelled very close to the p4win (the perforce
GUI client) and is quite extensive.

==============================================================================
OVERVIEW                                    *perforce-overview*

|perforce-installation|     How to install the plugin.

|perforce-filetype|         Perforce filetype plugin and setting it up for p4.

|perforce-settings|         An explanation of how to configure the plugin, for
                            both the perforce related parameters and the plugin
                            customizations, such as enabling menu.

|perforce-ruler|            Setting up the ruler to show an active status of the
                            file.

|perforce-syntax|           Perforce syntax plugin.

|perforce-help|             Browse the p4 help conveniently from within vim.

|perforce-reinitialize|     Describes how to reinitialize the plugin to load the
                            latest settings from the environment without
                            restarting vim.

|perforce-commands|         A description of various commands that can be
                            issued on Vim command-line.

|perforce-revisions|        Specifying perforce revisions conveniently.

|perforce-interactive-commands|
                            How to execute interactive perforce commands.

|perforce-forms|            How to edit the perforce forms (specifications) from
                            within vim.

|perforce-submit|           Special handling of submit command.

|perforce-list-commands|    Commands that can be used in a list of items window.

|perforce-extensions|       Some useful extensions in the form of new options
                            and commands.

|perforce-misc-commands|    Some additional useful commands.

|perforce-special-commands| Some useful commands and mappings.

|perforce-utils|            Additional utilties (perforce/perforceutils.vim).

|perforce-API|              New API provided by the plugin (experimental).

|perforce-tips|             Some useful tips.

|perforce-limitations|      Current limitations of the plugin.

|perforce-troubleshooting|  Some notes how to trouble shoot problems.

|perforce-changes|          A change list for current version from previous
                            versions.

|perforce-known-issues|     A list of known bugs.

|perforce-wishlist|         Wishlist items that may be worth doing for a future
                            version.

|perforce-bugreporting|     Reporting bugs.

|perforce-acknowledgements| Acknowledgements.

==============================================================================

                                            *perforce-installation*

To install, place the perforce.vim script in one of the runtime plugin
directories along with the genutils.vim scripts that it depends on. This
typically is .vim/plugin or vimfiles/plugin directory under your home directory.
To get the latest versions of these plugins, goto the following webplages:
     perforce.vim: http://www.vim.org/script.php?script_id=240
     genutils.vim: http://www.vim.org/script.php?script_id=197

The distribution contains the following files:
    - plugin/perforce.vim
        - Thin interface to the plugin (autoload/perforce.vim).
    - autoload/perforce.vim
        - The perforce plugin itself loaded on demand.
    - ftplugin/perforce.vim
        - The perforce filetype plugin file. See below on how to configure the
          perforce filetype.
    - syntax/perforce.vim.
        - Syntax definition file for perforce forms.
    - doc/perforce.txt.
        - The online help file (this file).
    - perforce/perforcemenu.vim.
        - Additional module to install and configure a menu for the plugin.
          See |perforce-menu|.
    - perforce/perforcebugrep.vim.
        - An utility script that can be used to generate useful information
          while sending bugreports about the plugin. See
          |perforce-bugreporting|.
    - perforce/perforceutils.vim.
        - Thin interface to autoload/perforceutils.vim
    - autoload/perforceutils.vim
        - Additional misc. utilities loaded on demand.

If you obtained the plugin as a zip archive,
    - Just extract it in your runtime directory.
    - Start a new instance or go to an existing instance of vim.
    - Execute:
>
        :helpt <your runtime directory>/doc
<
      This should generate the help tags for the perforce plugin help.
    - Setup perforce filetype as described in |perforce-filetype| section.
    - Make sure p4 command is in your path or set |p4CmdPath| property.
    - Set the |p4ClientRoot| property and additionally any other
      |perforce-settings| that you like.
    - Optionally set 'cmdheight' property to at least 2 to avoid seeing the more
      prompt for most of the messages the plugin gives.
    - The plugin requires that you have Vim 7.0 version installed.
    - If you want to enable the perforceutils.vim plugin, add the following line
      to your vimrc:
>
        runtime perforce/perforceutils.vim
<
    - If you want to enable the menu, add the following line to your vimrc, at
      the end of perforce configuration lines:
>
        runtime perforce/perforcemenu.vim
<
    - The core of the plugin is autoloaded by Vim the first time a perforce
      command needs to be executed. This improves the startup time of Vim
      considerably in some situations. If you want the plugin to be loaded
      immediately, you can force an autoload by adding the following command to
      your vimrc:
>
        PFIntialize
<

Note: It is important to make sure your 'shellredir' properly set such that, vim
captures both the standard output and standard error messages from the external
perforce command. If this is not correctly set, the plugin will not be able to
show the error messages generated by p4 command to you.

Also note that on Windows, if you use a UNIX like shell for your 'shell'
setting, the plugin will not work correctly unless the 'shellslash' option is
set.

                                            *loaded_perforce*
Later, if you need to temporarily disable the plugin without needing to remove
the files, you can set the loaded_perforce variable in your vimrc. You can also
set the no_perforce_maps to disable just the mappings defined in this plugin or
no_plugin_maps to disable mappings in all the plugins (provided they all honor
this setting), in your vimrc.
==============================================================================

                                            *perforce-filetype*
                                            *perforce-ftplugin*
The package comes with a perforce ftplugin (|filetype-plugin|) which sets a
few text mode options suitable for editing the forms and a syntax plugin to
colorize the spec files. The ftplugin also positions the cursor at the
appropriate line based on the type of spec you are editing. When you open
perforce forms from within vim using |perforce-interactive-commands|, you
don't have to do anything special for this to work, but if you want the same
to work while editing forms using p4 command directly, then you need to add
the following lines in your scripts.vim:
>
        if getline(1) =~ '^# A Perforce '
          setfiletype perforce
        endif
<
If you do not have this file already, then you need to create it under
vimfiles or .vim directory (or anywhere in your 'rtp'). For details see help
on |new-filetype-scripts|. Note that you also need to enable filetype plugins
for this to work, see |filetype-plugin| for more information.

==============================================================================

                                            *perforce-settings*
                                            *perforce-customizing*
The plugin allows a lot of customization by reading some global variables. You
can define a set of global variables in your startup script (.vimrc/_vimrc) and
they are automatically read by the plugin during the Vim startup and are used
for customizing the behavior.

Note that all the setting names are case sensitive and the boolean settings can
be set to the value 0 to disable and any non-zero number (for the matter of
fact, any string will also do) to enable. All the settings can be changed at
runtime without restarting vim; see |perforce-reinitialize|.

The settings can also be changed at runtime, see |perforce-reinitialize|.

Here is a list of all the options:
    |p4CmdPath|, |p4DefaultPreset|, |p4DefaultOptions|, |p4ClientRoot|,
    |p4EnableRuler|, |p4RulerWidth|, |p4EnableActiveStatus|,
    |p4ASIgnoreDefPattern|, |p4ASIgnoreUsrPattern|, |p4OptimizeActiveStatus|,
    |p4UseGUIDialogs|, |p4PromptToCheckout|, |p4DefaultListSize|,
    |p4DefaultDiffOptions|, |p4EnableMenu|, |p4UseExpandedMenu|,
    |p4EnablePopupMenu|, |p4UseExpandedPopupMenu|, |p4Presets|,
    |p4MaxLinesInDialog|, |p4CheckOutDefault|, |p4SortSettings|, |p4TempDir|,
    |p4SplitCommand|, |p4UseVimDiff2|, |p4EnableFileChangedShell|,
    |p4HideOnBufHidden|, |p4Depot|, |p4Autoread|, |p4FileLauncher|,
    |p4CurPresetExpr|, |p4CurDirExpr|, |p4UseClientViewMap|

                                            *perforce-command-path*
                                            *p4CmdPath*
The plugin executes the external p4 command for all its operations. By default
the command is found in the PATH, but if it doesn't exist in the path you can
still specify the location by using the p4CmdPath variable.
>
        :let g:p4CmdPath = '<path_to_p4_command>'
<
    Example: >
        :let g:p4CmdPath = '~/bin/perforce/bin/p4'
<
                                            *perforce-presets*
                                            *p4Presets*
This is a useful setting when you work with multiple perforce installations at
the same time. This allows you to predefine a set of configurations that you
can switch between without needing to restart vim or manually enter the
details while using the |PFSwitch| command. Set this variable in your vimrc
with a comma separated list of settings. Each setting should be of
the form (separated with one or more spaces):
>
            <port> <client> <user>
<
You can include as many of these specifications as you want, just separate them
with commas.
>
            :let g:p4Presets = 'port1 client1 user1,port2 client2 user2'
<
Once set, you can use the |PFSwitch| command in one of three ways to choose the
setting.

        1. If you know the index of the setting to which you want to
           switch to (starting with 0), just pass that as an argument to the
           command as
>
            " Switch to the third setting.
            :PFSwitch 2
<
        2. If you don't know the index, just invoke the command without any
           arguments. You will be prompted to enter the index after displaying
           a list of available settings.

        3. If you have expanded menu enabled (see |p4UseExpandedMenu| or
           |p4UseExpandedPopupMenu|), then you can choose the desired setting
           to switch to using the "Settings" sub-menu under "Perforce" group.

                                            *perforce-P4CONFIG*
                                            *P4CONFIG*
As a special case, you can have one of the specifications as "P4CONFIG",
allowing you to switch to the P4CONFIG feature of external p4 command
interactively, see |perforce-dynamic-client|.
>
            :let g:p4Presets = 'p1 c1 u1,P4CONFIG,p2 c2 u2'
<
Setting port field to "P4CONFIG" also has the same effect. This results in
plugin not passing the options for port, client and user explicitly such that p4
can determine them based on the P4CONFIG file. However you can still override
them by explicitly specifying the corresponding option to PF command.

                                                    *p4DefaultPreset*
If you don't have the P4CLIENT, P4USER and P4PORT environment variables set, you
can use this setting to initialize the plugin with corresponding values. The
format for the value is exactly same as a single entry in |p4Presets| setting.
In fact, you can also set this to an index in the |p4Presets|.
>
        :let g:p4DefaultPreset = '<your_perforce_port> <your_perforce_client_name> <your_perforce_user_name>'
<
    Example: >
        :let g:p4DefaultPreset = 'localhost:1666 hari_client hari'
        :let g:p4DefaultPreset = 2 " Start with the second setting in p4Presets.
<
Note that the plugin automatically chooses some defaults for the above based on
your environment, if you don't explicitly set them in your startup script.

                                            *perforce-default-options*
                                            *perforce-common-options*
                                            *p4DefaultOptions*
If you need to pass in additional arguments every time the external p4 command
is run, you can use the following setting. The arguments are passed to p4
literally. For the set of options that you can specify here, see perforce help
for "usage" (use ":PH usage" command, see |perforce-help|)
>
        :let g:p4DefaultOptions = '<default_options_to_p4>'
<
    Example: >
        :let g:p4DefaultOptions = '-H hkrishna'
<
                                            *perforce-buffer-local-options*
In addition you can also use the buffer local variables "b:p4Options",
"b:p4Client", "b:p4User", "b:p4Port" and "b:clientRoot" to override the global
options (see ":PH usage" for option list) at a buffer level. The plugin
automatically sets these options whenever you create a new perforce result
window such that any future commands originating from the same window
automatically inherit them.  This is especially useful when you temporarily
switch to a different client/user by providing one at command-line, and later do
more operations on the results (provided the given client/user is valid on the
current m/c). >

        :PF -c hari_tmp opened
        :PFileDiff
>
The PFileDiff will automatically use the "hari_tmp" client as b:p4Client is set
to that value. You can also use b:p4Options to set any option that is accepted
in the global options section of PF command (see |perforce-global-options|),
however for the client view mapping to work correctly, you need to have
b:p4Client and b:clientRoot set. >

        :let b:p4Options = '-H my_host'
<
All commands executed when this buffer is active will automatically inherit
these global options.

NOTE: Currently the b:clientRoot variable needs to be set manually.

                                            *perforce-client-root*
                                            *p4ClientRoot*
The client root is required for certain commands (it is same as what you
specify in the Root: property in the client settings), so if not specified and
if the |p4EnableActiveStatus| setting is enabled, the plugin will run the "p4
info" command to read the client root setting from the perforce server. But
this will introduce a short delay in autoload time (especially if you are
talking to a perforce server that is installed out side your network). To avoid
this, use the following setting to specify the client root.
>
        :let g:p4ClientRoot = '<client_root_directory>'
<
    Example: >
        :let g:p4ClientRoot = 'c:/dev'
<
If |p4EnableActiveStatus| is disabled, the current directory is used as the
default.

                                            *perforce-gui-dialogs*
                                            *p4UseGUIDialogs*
By default the plugin uses console dialogs for some of the prompts. This is
convenient as you can then use the input-history and expression register
|quote=|. But if you like, you can enable this setting to force using GUI
dialogs for all the prompts.
>
        :let g:p4UseGUIDialogs = 1
<

                                            *perforce-automatic-checkout*
                                            *p4PromptToCheckout*
The plugin by default prompts you to checkout, when you start editing a
readonly file under the client root. You can disable this behavior by using the
following setting:
>
        :let g:p4PromptToCheckout = 0
<
Note that you can still manually checkout (or edit) the file even when this
option is disabled by using "PE" or "PF edit" command.

When the checkout prompt is given, you have the option saying Yes, No or Cancel.
When accidental changes to the buffer bring up the checkout prompt, you can
select Cancel to revert the state of the buffer as much as possible (you may
still have to press <Esc> sometimes). One advantage of selecting Cancel in these
cases is that the next time you start making a genuine change, you will get the
checkout prompt as expected (otherwise, you will only get this prompt once).

                                            *perforce-list-size*
                                            *perforce-default-list-size*
                                            *p4DefaultListSize*
When you execute "changes", "jobs" and "filelog" perforce commands, the number
of entries is limited to 100 to avoid generating a large volume of data. But you
can change the value to whatever you like:
>
        :let g:p4DefaultListSize = 1000
<
To disabling it completely (show the entire list) set it to a negative number:
>
        :let g:p4DefaultListSize = -1
<

                                            *perforce-default-diff-options*
                                            *p4DefaultDiffOptions*
You can set the default diff options to be passed to all the "diff" and "diff2"
operations (both direct and indirect execution of these commands), by using the
following setting:
>
        :let g:p4DefaultDiffOptions = '-dwbu5'
<
For the options that you can set here, see the help for "diff" or "diff2" by
running the "PH diff" or "PH diff2" command.

Note, this setting can't be used to specify options to the external diff
program.

                                            *perforce-menu*
                                            *p4EnableMenu*
The distribution comes with an additional module called perforcemenu.vim to
install a Perforce sub-menu on the main or PopUp menu.  By default the menu is
not added as many people (including myself) don't use menus (I have the entire
menu bar disabled). Use the following setting to enable the Perforce sub-menu:
>
        :let g:p4EnableMenu = 1
<
The above setting will create a very basic menu with the most needed commands.
This makes it easy to use shortcut keys if you have the |winaltkeys| correctly
configured. To enable a more full featured menu, see |p4UseExpandedMenu|.

                                            *perforce-expanded-menu*
                                            *p4UseExpandedMenu*
By default the |p4EnableMenu| option creates a full-featured menu that is
modelled closely after the p4Win utility, which comes with perforce. But you can
disable this and have only a basic menu with the most commonly used set of
commands (this was the default for older versions of the plugin). Use the
following setting in your startup script:
>
        :let g:p4UseExpandedMenu = 0
<
If you want a basic menu on the main menu (for the ease of using the shortcut
keys), then you can consider having the full-featured version on the popup
menu, see |p4EnablePopupMenu| and |p4UseExpandedPopupMenu| settings.

                                            *perforce-popup-menu*
                                            *p4EnablePopupMenu*
This is similar to |p4EnableMenu| except that enabling this option, adds a
Perforce sub-menu on the PopUp menu instead of the main menu.
>
        :let g:p4EnablePopupMenu = 1
<
                                            *perforce-expanded-popup-menu*
                                            *p4UseExpandedPopupMenu*
This is similar to |p4UseExpandedMenu| except that enabling this option, adds a
more full-featured Perforce sub-menu on the PopUp menu.
>
        :let g:p4UseExpandedPopupMenu = 1
<
                                            *loaded_perforcemenu*
Note: If you never use the menu features of the plugin, consider setting
"loaded_perforcemenu" to a non-zero value, to avoid getting this module sourced.

                                            *perforce-max-lines-in-dialog*
                                            *p4MaxLinesInDialog*
Commands that use a dialog box to show the result (such as |PEdit|) assume
that the messages generated by the perforce command are only a few lines. But
depending on the arguments (e.g., "PEdit ..." and there are many files under
the current directory ...), there can be too many lines to display in a dialog
so the display mode is automatically switched to a new window instead of the
dialog. Though the default limit is 1, which helps to draw your attention for
the conditions that you normally expect a one line result (e.g., you checkout a
file and someone else already checked out the file), you can change it by
setting the following line:
>
            :let g:p4MaxLinesInDialog = <number of lines>
<
    Example:
>
            :let g:p4MaxLinesInDialog = 5
<
                                            *p4CheckOutDefault*
When you start modifying a read-only file, the plugin prompts you to checkout
the file from perforce. Set this option to 1 to make the default option to
"Yes" and 2 for "No". The default is 2 to avoid accidentally checking out a
file. >

            :let g:p4CheckOutDefault = <option number>
<
    Example:
>
            :let g:p4CheckOutDefault = 1
<
                                            *p4SortSettings*
The |PFSettings| command by default sorts the setting so that they are in
alphabetical order. But this will alter the position of the settings as new
settings get added, so if you want them to always appear in the same familiar
order, then set this to 0 to disable sorting. >

            :let p4SortSettings = 0
<
                                            *p4TempDir*
This setting points to the directory which should be used by the plugin for
creating any temporary files. This setting is used for vdiff and vdiff2
commands, but currently these commands don't really create any files on the
filesystem, as the directory is used to merely generate the filenames for
temporary files (the filename is still such that it is valid on the filesystem,
so that you can write the contents to it for any reason, but you will have to
reset the 'buftype' option first). But this may change in future when new
features/commands get added which require the temporary files to be on
filesystem. >

            :let p4TempDir = "c:/temp/vim-p4"
<
                                            *p4SplitCommand*
When the plugin creates new windows as a result of issuing perforce commands, it
by default uses |:split| command, which creates a horizontally split window above
or below the current window depending on your 'splitbelow' setting. But if you
would like to change the way the windows are created, you can set this setting
to any split command that is valid (such as |:vsplit| or "topleft split"). For
all possible commands see |:vertical|. >

            :let p4SplitCommand = "vsplit"
<
                                            *p4UseVimDiff2*
If this option is set, the plugin uses vdiff2 instead of diff2 in the filelog
window. See |perforce-vim-diff|. >

            :let p4UseVimDiff2 = 1
<
                                            *p4EnableFileChangedShell*
The plugin normally listens to the |FileChangedShell| events and refreshes the
ruler automatically (See |perforce-ruler|), keeping the status up to date. But
because of the way this event works, the plugin has to emulate the |timestamp|
warning messages that would be generated by Vim by default, when there is no
listener for this event. If you don't like this feature for any reason, you can
disable it by setting this option to 0. >

            :let p4EnableFileChangedShell = 0
<
Note that the plugin no longer refreshes the ruler whenever vim detects that the
file has been modified externally requiring a reload of the buffer (and this
anyway happens only if the buffer is currently visible in a window, or if the
'hidden' option is set). To manually refresh the ruler see
|perforce-refresh-file-status|.

                                            *p4BufHidden*
This setting is useful if you do not normally set the 'hidden' option. The
plugin normally sets the 'bufhidden' option for the perforce plugins to the
value "wipe" such that they are automatically wiped out when they are unloaded.
This keeps your buffer list clean and also conserves the vim resources as you
can potentially end up creating a lot of buffers, one for each perforce command
that you execute from with in Vim. But this would prevent you from switching
back and forth between the perforce result buffers and other regular buffers.
If you often find yourself working with perforce windows for a long time, you
should consider setting this option to the value "hide" instead, avoiding unload
of the buffers when they are hidden. When you set this value, an interesting and
useful side effect is that you can use <C-O> and <Tab> to navigate the preview
window, which can be very useful while viewing the description of list items,
see |perforce-list-commands|. >

        :let g:p4BufHidden = 'hide'

Note: You have three other alternatives to essentially get the same
functionality at different levels, avoiding the unload of the buffers:
        - Set the 'hidden' global option to avoid unloading all buffers. This
          essentially avoids unloading every buffer that is loaded/created in
          Vim, not just perforce windows.
        - Manually set 'bufhidden' local option to "hide" for any particular
          perforce window that you are interested in keeping around. Once set,
          this prevents the buffer from getting wipedout, until explicitly
          requested to do so. >

            :setlocal bufhidden=hide
<
        - Use the |:hide| command instead of quitting the buffer by other means,
          such as the |:quit| command everytime. This again prevents the buffer
          from getting unloaded even after it is hidden, but conveniently so
          only when you use :hide command. If the buffer is later shown back
          in another window and then hidden without having one of the other
          settings appropriately set, then it will get unloaded and will get
          wipedout.

See |PFWipeoutBufs| command for a way to cleanup all the hidden perforce buffers
that get accumulated, when you use one of the above techniques.

Note: There are other values that the 'bufhidden' can take, and so does the
g:p4BufHidden option, but they are not useful. They leave the perforce result
buffers lying around, without any useful side effect.

                                            *p4Depot*
The plugin at any time can operate only on one preset depot, which by default is
"depot". If your perforce server has multiple depots or if your depot name is
not "depot", then you can use this setting:
>
        :let g:p4Depot = 'proj'
>
to switch to a different depot than "depot". You can also do this at any time by
using the |PFSettings| command interactively.

                                            *p4Autoread*
By default, the plugin automatically reloads the file that get externally
modified as a side effect of some perforce commands (such as get and edit), if
the buffer inside vim is not yet modified. But you can disable this feature by
using this setting: >

        :let g:p4Autoread = -1
>
A value of -1 means, use the 'autoread' vim setting and a value of 0 means don't
autoread and a value of 1 means autoread (the default).

                                            *perforce-ruler*
The below are some additional settings that are related to configuring the
perforce ruler.

                                            *p4EnableRuler*
You can enable this setting to see additional information in the Vim ruler about
the current file's status. If the status for the current file doesn't exist yet,
nothing is shown. To make the status automatically available when you open a
file, you can enable the active status option, see |p4EnableActiveStatus|. You
can also manually obtain the status by executing the |PFRefreshFileStatus|
command any time. See |p4RulerWidth| on how to adjust the width of the ruler. By
default this setting is enabled, to disable it use, >

        :let g:p4EnableRuler = 0
<
The plugin modifies the 'rulerformat' for this to work, so if you are also
modifying this, make sure you do it before the plugin gets loaded (doing it in
the vim startup file will ensure this.)

Note that enabling this option alone is not sufficient, you should also have the
|p4EnableActiveStatus| setting enabled or use the |PFRefreshFileStatus| command.
Also see |p4OptimizeActiveStatus| setting.

                                            *perforce-ruler-width*
                                            *p4RulerWidth*
By default the plugin uses an additional 25 columns to show the perforce file
status. You might want to increase this value if you have long client names in
your perforce setup:
>
        :let g:p4RulerWidth = 50
<
                                            *perforce-active-status*
                                            *p4EnableActiveStatus*
Enabling this option along with |p4EnableRuler| will provide you a quick look
at the current file's status in the perforce depot, as soon as it is opened.
By default this setting is enabled, but you can disable it if it introduces
significant delay for every file you open (as it involves running an external
command which in turn has to talk to a server). >

        :let g:p4EnableActiveStatus = 0
<
If the response is slow and you would still like to have this feature, you can
disable this option and and use the |PFRefreshFileStatus| command, for whichever
file and whenever you want to see/update the ruler.

Besides using the status for showing the ruler, if available, it is also used to
make better decisions during some perforce operations.

Note, you need to still have the |p4EnableRuler| setting enabled to actually see
the status in the ruler. Also the default |p4OptimizeActiveStatus| setting
optimises it such that the "fstat" is done only the first time the file is
opened.

                                        *perforce-active-status-ignore-patterns*
                                        *p4ASIgnoreDefPattern*
                                        *p4ASIgnoreUsrPattern*
These are regular expression patterns matching the filenames for which the
active status should be ignored. If the current filename matches the default
ignore pattern or the user defined ignore pattern, then it is assumed that the
file doesn't exist in the depot and no fstat is done on it. By default the
user pattern is empty and the default pattern is set to all files under tmp
and temp sub-directories and any file with log, dif, diff, out, buf and bak as
extension (case insensitive), which is expressed by the following pattern: >

  '\c\%(\<t\%(e\)\?mp\/.*\|^.*\.tmp$\|^.*\.log$\|^.*\.diff\?$\|^.*\.out$\|' .
      \ '^.*\.buf$\|^.*\.bak$\)\C'
<
To add additional patterns, the "p4ASIgnoreUsrPattern" should be used. The
"p4ASIgnoreDefPattern" can however be set to an empty value such that the
default pattern is completely ignored. Setting the default pattern to empty
string without defining the user pattern will completely disabled this feature,
resulting in a 'p4 fstat' call to every file that is opened (the file still
needs to be under the client root).

                                            *perforce-optimize-filestatus*
                                            *p4OptimizeActiveStatus*
Enabling this option along with |p4EnableActiveStatus| and |p4EnableRuler| will
allow the plugin to determine a brief status of the file in perforce and show it
as part of the ruler, without loosing much of the responsiveness.  When you
enable this option, the plugin determines the status only the first time you
open the file and any other time there is a possibility for change in the status
(after executing the |PEdit|, |PRevert| etc.) and when you manually ask the
plugin to update the status using the |PFRefreshFileStatus| command. By default,
this option is enabled, to disable it use, >

        :let g:p4OptimizeActiveStatus = 0
<
When this option is set, the current file status shown in the ruler may not be
the most up to date status, so when it is important (see
|perforce-negative-revisions|) make sure you update it manually.

                                            *perforce-file-launcher*
                                            *p4FileLauncher*
This setting is used to choose the launcher application for executing the
|PFileLaunch| command in a filelist window. For non-windows platforms, this
needs to be explicitly set before you can use the |PFileLaunch| command, but on
windows, this by default is set to the following command: >

 	start rundll32 url.dll,FileProtocolHandler
<
This works almost the same as double clicking the file under explorer, so proper
file associations are assumed. You can however change the command to whatever
you like.

                                            *perforce-dynamic-client*
For those users who have a need to dynamically switch between different perforce
clients, the plugin provides ability to set expressions that can be used to
provide call back hooks and determine the appropriate client. This is especially
useful when you have multiple clients mapped on to the same root and there is a
way to deduce the client based on the usage patterns and or current file.

                                            *p4CurPresetExpr*
                                            *p4CurDirExpr*
These by default are set to an empty string, but can be assigned any Vim
expression that is valid on the RHS of a variable assignment. The expression is
evaluated and the result is used as the corresponding setting.

The "p4CurPresetExpr" setting is used only when using |P4CONFIG| setting. The
"p4CurDirExpr" at any time can also be used to determine the working directory
of the p4 operation, which in turn could impact which |P4CONFIG| file is picked
up.

For the more demanding users, these expressions provide the call-back hooks
required to determine the client based on your environment.

Note that when you specify an expression which returns a different current
directory than the current Vim working directory (as returned by |getcwd()|),
the plugin doesn't attempt to modify any relative filenames that you specify on
the command-line to be relative to the new directory, so you need to make sure
you specify a valid filename in this case (or specify full paths all the time).
This could get tricky especially if you can't predict which directory your
expression would return. If your logic to find the current directory is really
that complex, then you could use the experimental API (see |perforce-API| that
the plugin provides to manipulate the filename arguments yourself from with in
the "p4CurDirExpr" before returning the directory name. However, while adding
new filenames to arguments (such as the default filename for certain commands)
the plugin automatically uses full filenames, when you specify a "-d" option on
the command-line or through the return value of "p4CurDirExpr".

It is recommended to return an empty string from "p4CurDirExpr", when the
directory is same as Vim's current working directory.

See also |perforce-switch-client|.

See |perforce-tips| for an interesting and useful idea for using "p4CurDirExpr"
setting.

                                            *p4UseClientViewMap*
This is an experimental feature, so defaults to 0.

Use this setting to make the plugin look into your client View: mappings while
translating depot paths to local paths and vice versa. The plugin translates the
paths without needing to run "p4 where" command, by extracting the View: data
from the client specification and building an internal representations for that.
This is done the first time the translation is required and it is cached to
avoid executing the "p4 client" command everytime. When the views in your client
specification change, you need to manually update this mapping by running the
|PFUpdateViews| command.

Make sure you don't have any syntactic errors in your views (such as unmatched
wildcards), as the plugin is not as forgiving as perforce itself in handling
them (this is done for simplicity).
==============================================================================

                                            *perforce-syntax*
The perforce plugin comes with a Vim syntax plugin for perforce filetype, and
works even when the |perforce-filetype| plugin is not setup. Most of the
output windows generated for perforce commands are set to the "perforce"
filetype and results in automatically sourcing this syntax file. Like any syntax
plugin, you can do further customizations and overrides from your vimrc or from
an "after" plugin (as the case may be). To customize syntax colors, here is a
complete list of all the syntax groups that the plugin defines (replace the tag
on the right hand side with your own preferred highlight group such as Comment,
Special etc.):
>
        hi link perforceSpecKey           <your_preferred_highlighting_group>
        hi link perforceComment           <your_preferred_highlighting_group>
        hi link perforceDate              <your_preferred_highlighting_group>
        hi link perforceCommands          <your_preferred_highlighting_group>
        hi link perforceHelpKeys          <your_preferred_highlighting_group>
        hi link perforceClientRoot        <your_preferred_highlighting_group>
        hi link perforceKeyName           <your_preferred_highlighting_group>
        hi link perforceDepotFile         <your_preferred_highlighting_group>
        hi link perforceLocalFile         <your_preferred_highlighting_group>
        hi link perforceVerSep            <your_preferred_highlighting_group>
        hi link perforceVersion           <your_preferred_highlighting_group>
        hi link perforceSubmitType	  <your_preferred_highlighting_group>
        hi link perforceDefaultSubmitType <your_preferred_highlighting_group>
        hi link perforceViewExclude       <your_preferred_highlighting_group>
        hi link perforceDepotView         <your_preferred_highlighting_group>
        hi link perforceClientView        <your_preferred_highlighting_group>
<
==============================================================================

                                            *perforce-help*
The plugin comes with a help browser to browse the perforce help from within
vim window and move back and forth between different help pages. To start the
help just type |PH| or "PF help" command or alternatively choose the appropriate
menu entry. The plugin opens a new window that is positioned the way the vim
built-in help does. Once you close the help window, all the other window sizes
are restored, again the way the vim built-in help does.

Once you are in the help window, you can see that the perforce help keywords
are highlighted with a different color. To get additional perforce help on the
keyword, you can just move on to the keyword and press |Enter| or |K|. You can
also press double-click with your left mouse button.

The |PH|, |PHelp| or "PF help" command takes a set of arguments that are passed
to the perforce help command, which makes it easier to get to the help page if
you know the keywords. The |PH| and |PHelp| commands also support command
completion for help topics.

You can use <BS> and <Tab> to navigate the help history. This makes it easy
to view the perforce help and makes it feel like a hyper-text browser. Use "q"
or any other vim command to quit the help window.
==============================================================================

                                            *perforce-commands*
                                            *:PF*
                                            *perforce-global-options*
                                            *perforce-command-options*
                                            *perforce-command*
                                            *perforce-arguments*
The plugin defines a set of new commands to interact with perforce. The most
basic command is the "PF" command that is equivalent to the "p4" command on
the shell. This command takes arguments that are processed and passed to the
external p4 command and the output is collected back. Depending on the type of
command and various user settings, the output is either displayed in a new
window, a preview window or in a dialog box.

The command syntax resembles that of p4 command. There are five different types
of arguments that can be passed to PF command:
>
        :[range]PF [<p4 global options>] <p4 command>
                [<p4 command options>] [<arguments>]
<
All the argument sections are optional except for the command name itself. It
provides the flexibility to issue complex commands (essentially anything that is
possible at the shell prompt) such as the below:
>
        :PF -c client -u user integrate -b branch -s source target1 target2
<
where, the "-c client -u user" are global options, "integrate" is the p4
command, "-b branch -s source" are the command options and the "target1
target2" are the arguments to the corresponding perforce command.

Note: See |perforce-common-options| for informaton on providing global options
transparently.

All commands executed through "PF" go through a common internal function that
does argument validations/modifications/customizations etc. in addition to any
command specific operations. This results in a very consistent argument handling
throughout all the perforce commands.

    Example: >
        " Run p4 diff on the current file and display the diff in a new window.
        :PF diff

        " Show all the opened files under the src directory (assuming you we are
        "   currnetly above this directory) in a new window.
        :PF opened src/...

        " Open the client specification for editing.
        :PF client
<
Most commands take variable number of arguments. Some commands that require a
filename default to current file or ask you for an argument, if you didn't pass
any.

You can additionally pipe the output of p4 through external commands (filters)
before the plugin sees the output. Anything after an unprotected bar ("|") is
considered as the external filters and so is specially treated by the plugin,
and the processing on such arguments is reduced to a minimum, which means that
you need to take care of the shell specific issues (such as enclosing the
arguments in quotes etc.) yourself. If you need to specify the bar symbol as
part of the perforce arguments (not really as the shell pipe symbol), then you
need to protect it with a back-slash, as discussed in the
|perforce-special-chars| section.

    Example (useful for older versions of p4 client that didn't support -u
    argument): >
        PChanges -s pending | grep hari
<
If you find yourself using a combination frequently, you can create a new
command for it to make it easier to type. For the above combination, the
following can be placed in .vimrc:
>
     command! MyPChanges PChanges -m -1 -s pending | grep hari
<
Note, If you want to by-pass additional command specific processing, then you
can use the |PFRaw| command instead of the "PF" command.

The :PF command also supports custom command completion, to complete partial
perforce command names as well as filenames. Most filename expansions
automatically happen (like, %, <cfile> etc.), and # followed by a revision
specifier is treated specially when occurred at the end of the argument, and is
prevented from getting expanding as a Vim buffer name.

                                            *perforce-special-chars*
Some of the characters in the arguments are treated specially by the plugin,
unless they are protected by prefixing them with a back-slash. The characters
that are treated specially are:

    character       special meaning ~
    <space>         argument separator.
    &               codeline modifier. See
                    |perforce-alternative-codeline-modifier|
    |               pipe symbol.
    \               protects other special characters, unless protected by
                    itself.

                                            *perforce-command-mode-specifier*
                                            *perforce-filter* *perforce-pipe*
You can also specify the run mode of the perforce command as one of the "run"
(default), "filter" or "pipe" by specifying one of the '++r', '++f' or '++p'
option respectively to the PF command in the <p4 global options> section as
described in the |perforce-commands| section. These options are just used as
directives to the command-processor and are not passed to the external p4
command. The "filter" and "pipe" modes are most useful with the "-x -"
perforce global option (see ":PH usage" for details) and "display" mode is used
mainly for internal purposes.

    option  details ~
    ++p     Write (pipe) the lines specified by the given [range] to the p4
            command on standard input. This works like the |:write_c| command.
            This only pipes contents to p4, and doesn't read the output back, so
            the contents are not effected.
    ++f     Filter the lines specified by the given [range] through the p4
            command. This works like the |filter| command. You can create a new
            buffer or modify buffer containing the output of another perforce
            command, and pass the contents as arguments to a perforce command
            and get back the results. In fact the '++c' option of diff does
            exactly this. It first obtains the list of opened files in the given
            change list and passes them as arguments to the diff command. See
            |perforce-extensions|.  The |PW| command is just an alias for this
            feature so that you can skip the bang for convenience (you can't
            specify -x option with this command, however).

The default [range] for the ":PF" command is the whole buffer (1,$). There is no
direct equivalent of Vim's |:read!| syntax here, but it can easily be done using
the "filter" mode on an empty line created at the location where you want to
read the output of p4 command.

                                            *:PEdit*      *:PRevert*   *:PAdd*
                                            *:PDiff*      *:PDiff2*    *:PPrint*
                                            *:PGet*       *:PSync*
                                            *:POpened*    *:PHelp*
                                            *:PDelete*    *:PLock*
                                            *:PSubmit*    *:PUnlock*
                                            *:PClient*    *:PClients*  *:PUser*
                                            *:PUsers*     *:PBranch*
                                            *:PBranches*  *:PLabel*
                                            *:PLabels*    *:PJob*      *:PJobs*
                                            *:PJobspec*   *:PResolve*
                                            *:PChange*    *:PChanges*
                                            *:PDepot*     *:PDepots*   *:PHave*
                                            *:PDescribe*  *:PFiles*    *:PFstat*
                                            *:PGroup*     *:PGroups*
                                            *:PLabelsync* *:PIntegrate*
                                            *:PPasswd*

While the perforce commands can be executed using the "PF xxx" syntax, some
of them have an equivalent PXxx command. So the following two: >

        :PF opened -c 123456
<
    and >

        :POpened -c 123456
<
are identical. However, if you intend to pass some global arguments to p4,
then you are forced to use the first syntax. E.g., if you want to change the
user specification of another user, instead of changing the P4USER env.
variable, or using the |PFSwitch| command, you can use the following approach:
>
        :PF -u other_user user
<
                                            *perforce-describe*
The describe command by default adds the "-s" option to avoid generating the
diff, unless a diff option is explicitly specified (implying that you would like
to see the diff too).

Note that the commands that normally prompt a confirmation message (such as
revert) accept a "++y" argument to avoid the prompt.
>
        :PF ++y revert -c 12345
<
                                            *:PE*  *:PR*  *:PA*  *:PD*  *:PD2* *:PP*
                                            *:PG*  *:PO*  *:PH*
Some of the more frequently used commands have a shortcut to make it faster to
type.  Following table gives the mapping:

        Short-cut       Command ~
        PA              add
        PD              diff
        PD2             diff2
        PE              edit
        PG              get/sync
        PH              help    |perforce-help|
        PO              opened
        PP              print
        PR              revert

You can also define your own shortcuts easily, e.g., >

        :command! -nargs=* PB :PF branch <args>
<
Place this command in your .vimrc so that it gets executed every time you
start Vim.

                                            *:PFRaw*
PFRaw command is like |PF| command except that it bypasses all the processing
that the |PF| command does. You should be able to pass most of the perforce
arguments as they are to this command. The raw output from the p4 command is
collected and placed in a new window

Note that you can't use PFRaw to execute any p4 command that requires user
interaction (such as "PFRaw client") unless you can pass in a "-o" options to
it. In fact the |PF| command and the corresponding specialized commands (such
as PClient) pass the "-o" argument internally to generate forms.

                                            *perforce-initialize*
                                            *perforce-reinitialize*
                                            *:PFInitialize*
Changing some settings may have impact on other plugin or Vim settings, so to
propagate these changes, you should execute the :PFInitialize command.
When you want to change a setting while within Vim, you can directly set the
value of the corresponding global variable, but you should also call the
:PFInitialize command. It is recommended to use the |:PFsettings| command, which
not only makes it easier to find and enter values for these settings, it will
also execute :PFInitialize for you.

    Examples:
        You can remove the Perforce sub-menu from the main menu by using
        the following commands: >

            :let g:p4EnableMenu = 0
            :PFInitialize
<
        You can re-enable the menu, may be the full-featured one by setting: >

            :let g:p4EnableMenu = 1
            :let g:p4UseExpandedMenu = 1
            :PFInitialize
<
                                            *:PFSettings*
To make the above process easier, the PFSettings command prompts you with a
list of settings to select from (without the common p4 prefix) and let you
modify them. You can optionally pass in the setting name and value on the
command line too. If passing the setting name, you can use Vim's completion
mechanism to complete partially typed in name.
>
        :PFSettings [setting name] [new value]
<
The command reinitializes the plugin after making the modifications. A typical
dialog to turn on perforce menu for a gvim window could look like this:
>
            :PFSettings
            0   User                  1   Client                2   Password
            3   Port                  4   Presets               5   ClientRoot
            ...
            9   EnableMenu            ...
            ...
            .
            .
            Select the setting: 9<Enter>
            Current value for EnableMenu is: 0
            Enter new value: 1<Enter>
<
You should see the menu turned on at the end of this process. You can quit the
dialog at any time by just pressing <Enter> without typing anything.

If you know the name of the setting (or use command-completion), you can specify
the setting and its new value directly on the command-line, to avoid the
dialogs.  E.g., to change the default diff options: >

            :PFSettings DefaultDiffOptions -dwbu
            Current value for DefaultDiffOptions: "-du" New value: "-dwbu"
<
Note, there is also an abbreviation defined for this command as "PFS".

                                            *perforce-switch-client*
                                            *:PFSwitchPortClientUser*
                                            *:PFSwitch*
If you are connecting to multiple perforce installations, the PFSwitch command
can be used to quickly switch between them. For an explanation of how to
store these configurations to avoid typing, or use the Settings menu, see
|p4Presets|.

When you want to switch to a different perforce server, or just switch to a
different client or user, without leaving Vim or needing to change any
environment variables, use the PFSwitch command in one of the following ways:

    1. Prompt for the setting to choose from. Enter the index in the list of
       settings.  >

        :PFSwitch
<
    2. If you know the index, pass it as an argument.  >

        :PFSwitch <index into p4Presets starting with 0>
<
    3. To switch to an arbitrary setting, pass in the arguments as below: >

        :PFSwitch <port> [<client>] [<user>]
<
       As a special case, you can pass in P4CONFIG as the only argument to
       switch to using the P4CONFIG feature of the external p4 command (see
       also |perforce-dynamic-client| and |perforce-P4CONFIG|. You can use Vim
       command completion mechanism to complete from the |p4Presets|.
    4. You can also use PFSwitchPortClientUser which prompts you for the
       individual values. >

        :PFSwitchPortClientUser
<
See also |p4Presets|.

Note, this command resets the cached file statuses of all the buffers such that
their statuses are determined again based on the new client.

                                            *:PFWipeoutBufs*
This command can be used periodically to cleanup all the hidden perforce buffers
that are not already wipedout because they are not yet unloaded (see
|p4HideOnBufHidden| for ways to do this). By default, this command only prints
the list of buffers that will be wipedout, so to actually wipeout the buffers,
run the command with "++y" option. >

        :PFWipeoutBufs ++y
<
                                            *perforce-update-views*
                                            *:PFUpdateViews*
Use this command to update the internal structures corresponding to the client
view mapping. When run, it discards the local cache and reconstructs it by
running "p4 client" command.
==============================================================================

                                            *perforce-revisions*
For convenience most commands (such as sync and print) take in a revision (as
specified by "help revisions") as the last argument and apply it to the
current file. You need to however protect the '#'s with a backslash such that
it is not substituted by vim with the current alternative-file |#|.
    Examples: >

        :PP \#1 - To see the revision 1 of the current file.
        :PP @2002/01/01 - To see the current file as of a date.
        :PP @65000 - To see the current file as of change 65000.
<
                                            *perforce-negative-revisions*
In addition, you can also pass in a negative or positive number as a revision
to specify an offset from the have revision. If you have the
|perforce-active-status| feature enabled, the have revision value is available
automatically, otherwise the plugin executes the file status such that it can
generate the new revision after the offset.  >

        :PP \#-2 " To see the (#head - 2)'th revision.
        :PD2 \#-1 \#-0 " Diff between the have and the previous revisions.
        :PD2 #\#have #\#head " Diff between the have and the head revisions for
                            "   the alternate file..
<
Note: Observe the "-0" given as the revision number to mean the head revision.

Note: PD2 (which is a shortcut for "PDiff2" or "PF diff2") also supports an
interactive mode in which you can just type in PD2 by its own with no
arguments, and the plugin will prompt you to specify the two revisions. You
can specify any revision specifier that is normally supported on the
command-line, in addition numbers are always treated as revisions so you don't
have to prefix them with a \#. >

        :PD2
        Version 1? 10
        Version 2? 2002/12/15
<
Note: To be able to specify revision offsets, you need to have all the resultant
files already open in the current vim session.

                                    *perforce-alternative-codeline-modifier*
Another convenient feature supported by plugin is to allow specifying an
alternative codeline in addition to the revision specifiers by using the '&'
modifier. Suppose you want to diff between the revision 2 of the currently
opened file with the head revision of the same file but from another codeline
called 'other', then the following syntax makes it easy >

        :PD2 \#head&other \#2 " Same as 'PD2 \#1 \#2' if 'other' is the parent
                              "   codeline and if they are in sync.
<
You can pass multiple such modifiers too, though the main use is with the
depot-modifier as described below.

                                            *perforce-depot-modifier*
The '&depot' modifier is treated specially. Instead of treating 'depot' (or the
name of the current depot) as an alternative codeline, the filename is converted
to its corresponding depot name. This is useful if the local file is not part of
your client spec or is deleted from the depot. See also
|perforce-edit-alternative-file| >
        :PF filelog a-deleted-file&other&depot
<

                                            *perforce-local-modifier*
The '&local' modifier is treated specially. Instead of treating 'local' as an
alternative codeline, the filename is converted to its corresponding local name.

==============================================================================

                                            *perforce-forms*
                                            *perforce-specifications*
                                            *perforce-interactive-commands*
Most of the perforce forms can be edited right from with in vim. The perforce
command line normally invokes the external editor to edit the forms and when
you save and quit the editor, the form is read back and the corresponding
settings are updated. E.g., the following steps describe how you modify client
specification using the p4 command:
>
        $ p4 client

        # A Perforce Client Specification.
        #
        #  Client:      <so and so>.
        .
        .
        :wq

        Client <so and so> saved.
<
    The aim of the plugin is to be able to do most of such actions without
needing to leave Vim. So when you execute a command that requires editing a
form, the plugin automatically generates the form in a new window for you to
edit. You can then modify it as you would normally in the external editor
invoked by the p4 command, and to finally save it, use the normal |:write| or
the special "W" (|perforce-W|) command. The plugin then tries to send the
changes back to the server and generates the result also on the same window. The
entire process would appear the same as above, except for

        1. you would use "PF client" or |PClient| in Vim, instead of the
           "p4 client" in the shell.
        2. Edit the specification as you would otherwise.
        3. The specification will be automatically written back to perforce when
           you save it like any other file (using :w or :W).

Note that you can also use :wq to save and quit the window at the same time, but
because of a known issue in Vim as of the release version of 6.1, your changes
could be lost if the specification has an error. There is a patch available for
this that fixes the problem, so apply the patch or use the safer :WQ command.

What is the advantage?

        - You don't have to leave your Vim window or look for a command prompt.
        - If you change your mind, it is easy to quit/leave or even postpone
          (especially for submits, where you can convert it to a new
          change list) the spec window.
        - On errors you can just undo (by pressing 'u') and retry, as many
          times as you need to.
        - You have the option of opening the specification while viewing its
          corresponding list. E.g., you can execute "PF changes -s pending"
          and press "O" command on any change to open its change specification
          and easily modify it.
        - You can also view multiple specifications at the same time. You can
          for example easily move files from one change list into another.
        - You have additional commands defined local to the spec window, that
          are specific to the type of spec being edited.
        - Based on your working habits, you have other advantages that are
          inherent in using the same Vim session for multiple things.
        - It is much easier to use the Vim editing techniques to filter the
          filelist or edit the description instead of using the GUI in p4Win.
        - To me, it is also more fun to do it this way :)

Unlike in earlier versions of the plugin, the specification buffers are now
regular buffers, so they get marked as 'modified' when you start editing them.
This prevents you from accidentally quitting the buffers, without writing them
back to perforce. Also, Vim creates 'swapfile's for these buffers, so in case
your session crashes, you can retrieve your changes (such as the description or
your filelist) from the swapfile (see |crash-recover|). The swapfile will
usually be created in the current directory or in a fixed directory specified by
'directory' setting. When working with perforce specifications, the swapfiles
could also be created in the temp directory, as the buffer names are often
invalid on the file system (in which case the swap filename may not be that
obvious).

                                            *perforce-W*
                                            *perforce-WQ*
The W command accepts arguments that are in turn passed to the corresponding
p4 command, so you can pass additional arguments such as "-r" while using
submit form.

There is also a WQ command which is same as the W command except that it also
close the form window when there are no errors.

The equivalent menu entries are "Save Current Spec" and "Save and Quit Current
Spec".

                                            *perforce-changelist*
The change command accepts a set of perforce filename patterns that are
passed directly to "opened" to filter the files that should be included in the
changelist. Without specifying the patterns, the command would work exactly the
way the native "p4" command works, which means the changelist will start with
all the opened files that are in the "default" changelist.

==============================================================================

                                            *perforce-submit*
The submit command is handled slightly differently than other interactive
commands, as the "PF submit" or |PSubmit| internally runs the "PF change"
command to generate a submission template. There are a few additional features
implemented which are discussed below.

PSubmit command accepts additional arguments which are passed in as they are
to "opened" command to generate the list of files to submit, so it is possible
to create the template with a set of files to submit such as, "PSubmit % #" to
submit the current and alternate files only (which is more flexible than the
native command). Of course you can always run with out arguments to generate a
full list of files and then remove the ones that you don't want. You can also
pass in the -c changelist# to submit the given changelist non-interactively (or
submit it from "changes" list). You can convert a submission template into a
changelist by simply using the PSubmitPostpone instead of the W or WQ command.
Similarly, when you are in the change specification, you can use the
PChangeSubmit to submit the current change instead of first saving it using W or
WQ command and then submitting the change list using the "PSubmit -c
changelist#".

On partial errors during the submissions (such as those that require a resolve
before submission), perforce sometimes automatically creates a changelist for
the files in the submission template, in which case the changelist number is no
longer "new" and the status is no longer "pending", so the plugin automatically
detects this scenario and adjusts the template for these values. All you have to
do in such cases is to 'undo' as you normally would, and fix the error before
trying to submit again.

Note, arguments such as '-r' are remembered when the PSubmit is first invoked
and are used during the :W or :WQ command.

==============================================================================

                                            *perforce-list-commands*
                                            *perforce-list-view*
                                            *perforce-item-list*
When executing a perforce command that generates a list of {something} such as
changes, you have special commands defined that are local to the buffer and
are specific to the list you are viewing. This allows you to visually perform
some operations on the individual item without needing to type a separate
command on the item.

There are commands defined for both the commandline as well as key mappings
and menu items for these operations. Note however that the same mapping can
behave differently on different list views, depending on what is the list that
you are viewing. E.g., pressing D normally means delete the specific item, but
on a filelog window when you select two history entries (select all the lines
between the two versions, inclusive) and press D, you get a diff between the two
versions.

There are some generic list commands that work in most of the list views with
somewhat consistent behavior:

Note that for commands that generate a list of files (such as opened), there
is a different set of commands defined, see |perforce-filelist|.

                                            *perforce-common-list-commands*
These commands are available in all the listing windows.

                                            *:PItemDescribe* *:PItemOpen*
                                            *:PItemDelete*
    Command             Key         Meaning ~
    PItemDescribe       <Enter>     Describe the current item. This shows a
                                    summary of the current item in a
                                    |preview-window|.
    PItemOpen           O           Open the current item for editing.
    PItemDelete         D           Delete the current item. You will have be
                                    prompted to confirm the deletion.

                                            *perforce-client-list*
You can use all the commands described in |perforce-common-list-commands|, as
well as the below:

                                            *:PClientsTemplate*
    Command             Key         Meaning ~
    PClientsTemplate    P           Using the current client as a template,
                                    start creating a new client spec. You will
                                    prompted for the name of the new client.

                                            *perforce-labels-list*
You can use all the commands described in |perforce-common-list-commands|, as
well as the below:

                                            *:PLabelsSyncClient*
                                            *:PLabelsSyncLabel* *:PLabelsFiles*
                                            *:PLabelsTemplate*
    Command             Key         Meaning ~
    PLabelsSyncClient   S           Sync the client to the current label.
    PLabelsSyncLabel    C           Sync the the label to the current client.
    PLabelsFiles        I           List the files associated with this label.
    PLabelsTemplate     T           Using the current label as a template, start
                                    editing a new label spec. You will be
                                    prompted to enter the name of the new label.

                                            *perforce-changes-list*
You can use all the commands described in |perforce-common-list-commands| as
well as the below:

                                            *:PChangesSubmit* *:PChangesOpened*
                                            *:PChangesDiff*
    Command             Key         Meaning ~
    PChangesSubmit      S           Submit the current change list. You will
                                    be prompted to confirm.
    PChangesOpened      o           List files associated with this
                                    changelist.
    PChangesDiff        d           Show diff for the current pending or
                                    submitted changelist.

                                            *perforce-filelog-list*
You can only use the describe command described in
|perforce-common-list-commands| however there are other convenience commands
defined for this view:

                                            *:PFilelogDiff* *:PFilelogDSync*
                                            *:PFilelogDescribe* *:PFilelogPrint*
    Command             Key         Meaning ~
    PFilelogDiff        D           Show diff between two selected versions
                                    (works only in the visual mode).
    PFilelogDSync       S           Sync to the current version.
    PFilelogDescribe    C           Describe the changelist for the current
                                    change.
    PFilelogPrint       p           Run print on the current version.

You can generate the diff between two version while viewing the history. For
this, you need to select all the lines between the two version, inclusive, and
press the 'D' key. You can also use the PFilelogDiff with a range of lines as
a prefix, without needing to select the lines.

    Example:
        You can mark the first version as 'a' using the 'ma' command and mart
        the second line as 'b' using the 'mb' command and execute: >

            :'a,'bPFilelogDiff
<

                                            *perforce-filelist*
When you execute the commands |POpened|, |PHave|, |PFiles| and |PDescribe| that
generate a list of files, you can use the file list window to do further
operations on the files.

                                        *:PFileDiff* *:PFileProps* *:PFileEdit*
                                        *:PFileRevert* *:PFilePrint* *:PFileSync*
                                        *:PFileChange* *:PFileLaunch* *:PFileLog*
    Command             Key         Meaning ~
    PFileDiff           D           Run "p4 diff" on the current file.
    PFileProps          P           Print the properties (fstat) of the
                                    current file.
    PFileEdit           I           Edit (checkout) the current file.
    PFileRevert         R           Revert the current file.
    PFilePrint          P           Print the current file in the preview
                                    window. This is mostly same as
                                    PItemDescribe, but handles the deleted and
                                    binary files correctly.
    PFileGet                        Sync the current file to the revision
                                    specified in the filelist.
    PFileSync           S           Sync the current file to the head
                                    revision.
    PFileChange         C           Open change list for the current file.
    PFileLaunch         A           Launch the current file. On windows, it
                                    works almost the same way as double clicking
                                    the file in explorer. On non-windows
                                    platforms, you need to explicitly configure
                                    a launcher command by using the
                                    |p4FileLauncher| setting. You need to have
                                    (correct revision of) the file already on
                                    the filesystem, if not first do a sync as
                                    described above.
    PFileLog                        Run "filelog" on current file.

In addition, the plugin sets up 'includeexpr' such that you can use |gf| and
|<cfile>| on the depot files. Since |gf| would result in the current buffer
getting hidden, the current perforce buffer showing the filelist could get
wipedout (unless this is prevented using the techniques described in
|p4BufHidden|). If you have any mappings using |<cfile>| they should work well.

Note: There is no quick help available to see which commands are available and
what the mappings are for any given perforce result buffer. However, the output
of nmap command is pretty useful and sufficient for this purpose. Type the
following command as it is to see the perforce commands with their mappings
(among others) >
        :nmap <buffer>
<
==============================================================================

                                            *perforce-extensions*
There are some useful extensions provided over the perforce commands to make
your job easier.

|perforce-pending-change-diff|      Restricting diff to an open changelist.
|perforce-vim-diff|                 Diffing using vim's built-in diff feature.
|perforce-external-diff|            Diffing using external diff tool.

                                            *perforce-pending-change-diff*
This provides an useful "++c" option to the PDiff command to specify a change
number that is open on this client. The plugin internally queries the open files
under this change list and restricts the diff to only these files. >

        PF diff ++c 1111 //depot/branch/src/...
<
The above restricts changes to only the changelist '1111' and under the src
directory.

                                            *perforce-builtin-commands*
                                            *perforce-vim-diff*
The plugin provides two built-in commands vdiff and vdiff2 to view diff using
the Vim's built-in diff features instead of using the perforce diff and diff2
commands respectively. If you need to customize the view, then read help on
|diff-options|. These commands do not accept any options and will ignore them if
any are provided. Make sure you don't have any windows that have diff mode set
before running these commands as otherwise they will participate in the diff
too.

                                            *perforce-vdiff*
                                            *:PVDiff*
                                            *perforce-vdiff2*
                                            *:PVDiff2*
These commands are an alternative to the perforce diff and diff2 commands that
use the Vim's built-in |vdiff| feature to generate the diff. Both command work
exactly same as both accept upto two arbitrary local or depot files as
arguments, but while "vdiff" command works with the files as they are specified
(local or depot paths), the "vdiff2" command tries to convert them to depot
paths as much as possible. There is also difference in how they choose default
arguments when the number of arguments is less than 2. The "vdiff" commands are
also a lot more flexible than the "diff" commands in that you can mix any two
filenames as arguments, including those from different codelines, local and
depot files and even those that are not even related.

With only one file (or the current file when no arguments) specified as
argument, the "vdiff" command like the "diff" command, diffs the file against
that of depot, where as the "vdiff2" command, like the "diff2" command prompts
you to enter the two depot version that you would like to diff for the specified
file.
>
        :PF vdiff " Diff the current file against depot.
        :PVDiff % &altBranch " Diff the current file against the same from a
                              " different branch.
        :PVDiff2 \#1 \#2 " Diff the revisions 1 and 2 for the current file.
<
                                            *PFDiffOff*
These commands always open new windows split vertically side-by-side to start
diff settings (diff settings are local to windows), so that your existing
windows are not disturbed. When you are done viewing the diff, you can just
close the diff windows and be done. But in case you need to reset the diff
settings, there is a command called "PFDiffOff" provided for convenience. The
command is very flexible in the sense that, it can identify the diff windows
that belong to one diff operation and when run from one of them, can turn off
the diff settings on all the related windows.  This is useful to incrementally
add/remove diff windows using PVDiff and PVDiff2 commands. If run outside of any
perforce diff windows, it turns off diff for all perforce windows.

                                            *perforce-default-diff-format*
Pass the dummy option "-d" (with no diff flags) to perforce commands that
produce diff output to force the format to be in the default diff format. This
is useful in case the |p4DefaultDiffOptions| is used and you temporarily want
the diff output to be of default type. This option is not really recognized by
the p4 command, and so will be removed from the command string before seen by
the p4 command (and so is merely used to avoid adding the default diff options).
>
        :PF describe -d 100
<
                                            *perforce-external-diff*
                                            *perforce-GNU-diff*
The "diff" command now supports running external GNU diff to generate the diff
output. To use this feature, make sure you have GNU diff installed in the path
and pass one or more of the valid GNU diff command options using the following
syntax:
>
        +<short or long option>[=<optional argument>]
<
E.g., to generate diff output for the current file in unified format with the
whole file in context (like the diff output in p4Win), you could use the
following comand:
>
        :PDiff +U=99999
<
Just make sure that the number is large enough to include the whole file.
Another example is:
>
        :PDiff +strip-trailing-cr +context=10 +W=120 +w
<
                                            *perforce-execute-direct*
                                            *:PExec*
This is a built-in command that executes arbitrary vim commands after
processing the command-line the same way as it would if you executed any regular
perforce command. This is useful to execute external perforce commands (though
not limited to them) directly, when you find that you can't do some task using
the features provided by the plugin alone. You typically want to execute
perforce commands using Vim's |:!| feature, e.g.: >

        :!p4 sync %
<
But if you want to take advantage of the various command-line shortcuts provided
by the plugin, then you would just pass the command as it is to :PExec: >

        :PExec !p4 sync %&altbranch#3
<
The above would sync the current file in a parallel branch called
"altbranch" to the version 3. Using the command also has the other inherent
advantages such as, you don't have to protect the filenanme special character
such as "#". The plugin also performs the same escaping mechanism on the
external command that it does on the regular plugin commands, however any
filters specified are not currently escaped.

Note, the above two commands are just examples that can easily be achieved using
the following plugin commands: >

        :PF sync
        :PF sync &altbranch#3
<
==============================================================================

                                            *perforce-misc-commands*
These are some misc. commands that are provided by the plugin in addition to the
commands that are already described.
    |PFRefreshActivePane|, |PFRefreshFileStatus|,
    |perforce-edit-alternative-file|, |PFSwitch|, |PW|, |PFToggleCkOut|,
    |PFLastMessage|, |PDiffLink|, |PDiffPLink|

                                            *perforce-refresh-active-pane*
                                            *:PFRefreshActivePane*
This command allows you to refresh the active perforce window (the window where
the cursor currently is). The window should have been a result of a perforce
command, to be able to refresh it. There is also a menu entry and a normal-mode
mapping <Leader>prap to do the same.

                                            *perforce-refresh-file-status*
                                            *:PFRefreshFileStatus*
Use this command to manually refresh the |perforce-ruler|. Useful when you
have the automatic refresh disabled by setting the |p4EnableActiveStatus|
to 0. You can also use the normal-mode mapping <Leader>prfs to do the same.

                                            *perforce-edit-alternative-file*
                                            *E*
                                            *ES*
These commands allow you to open the current file from an alternative codeline.
The syntax of the command is: >

    E [codeline] [files: default %]
    ES [codeline] [files: default %]
<
The difference between the two is that ES opens the file by splitting the
current window, where as E opens the file in the current window. You can specify
more than one file in which case the first one is still opened, but the
remaining files are just added to the buffer list so you can open them later
using a buffer explorer, or using :e #<buf>. If no arguments are passed, (just
type E or ES on its own), you will be prompted to enter the codeline.

                                            *perforce-write-file-contents*
                                            *:PW*
The |PW| command is a special command that you can use to filter the current
file contents through p4. You can specify the range of lines that need to be
written to the command and the default range is the entire file (1,$). The "W"
(|perforce-W|) or "WQ" (|perforce-WQ|) command described in |perforce-forms|
internally uses this command to write the form back to the perforce command and
read the result back. The command itself uses the |perforce-filter| feature to
do its job.

The following command can be used to revert the contents of the current file
without using the perforce "revert" command.  You can save the file, but you can
always do |:undo| to get back to your original contents (provided you haven't
lost your undo history). So this can be used to temporarily revert contents to
the depot version and then get back to your original version.
>
        :PW print -q
        :w
        :undo
<
Also see |perforce-command-mode-specifier| for alternatives to using this
command.

                                            *perforce-toggle-checkout-prompt*
                                            *:PFToggleCkOut*
This command can be used to disable/enable the automatic checkout prompt while
editing the readonly files. This is useful while you are in a read-only vim
(started with -R option), so even the files that are already checked out also
appear as read-only files, in which case, you don't want to see the checkout
prompt when you accidentally start modifying a file (or for that matter even
when you deliberately modify a file).

                                            *perforce-last-message*
                                            *:PFLastMessage*
Prints the last given message again.

==============================================================================

                                            *perforce-special-commands*

                                            *:<pfitem>*
You can use the special tag <pfitem> on the command-line to mean the current
list item. This works very close to how |:<cword>| etc. work. The command-line
parser would replace this with the value of the current item (which is dependent
on the type of list view) at runtime. This is useful to create your own
mappings/commands over what the plugin provides.

                                            *perforce-special-mappings*
There are some special mapping created for the command-line usage.

While you are in a list view (such as list of labels), you can get the name of
the current label on to the command-line by just typing <Ctrl-X><Ctrl-I>. This
is useful to quickly and accurately execute commands on the items that have
long names.

On the same lines as the E command (|perforce-edit-alternative-file|), there
is another command-line mapping created for inserting the name of an
alternate file right at the command-line. You can do this by typing
<Ctrl-X><Ctrl-P>. You will be prompted to enter the name of the alternative
codeline.
==============================================================================

                                            *perforce-utils*
These are available only when you install the perforce/perforceutils.vim plugin
as described in the |perforce-installation| section.

                                            *perforce-diff-mode*
                                            *perforce-diff-hyperlink*
                                            *:PDiffLink* *:PDiffPLink*
Executing various commands such as |PDiff| and |PDescribe| produce output in the
form of perforce diff (very similar to GNU diff output). The plugin provides two
commands to make it easier to navigate from the diff output to the original
source file like a hyperlink. The location of the original source file and the
line number are extracted from the diff output (supports the default, context
and unified formats). To open the source file and take the cursor to correct
location, use :PDiffLink command or press "O". To open the source file and
position the correct location in the preview window, use :PDiffPLink or press
<CR>. These commands are defined for only those windows that contain perforce
diff output.

Note that the commands can be executed on both the old and new source lines, and
the plugin either opens the appropriate file on the local filesystem or
"print"s the correct version from Perforce to position the cursor. When diff
refers to a depot file and the corresponding local file is already open in Vim
and has the same revision as of the depot file that the diff refers to, the
plugin opens the local file instead.

Note these commands are capable of handling regular GNU diff output formats too,
so you can use it on diff outputs generated using the "diff" command alone.

                                            *:PFDiffLink*
                                            *:PFDiffPLink*
These commands provide the same functionality that |PDiffLink| and |PDiffPLink|
provide in a diff windows, except that you can run them in any buffer that has
diff style output. Mostly useful if you are viewing diff obtained in a patch.

                                            *perforce-show-conflicts*
                                            *:PFShowConflicts*
This command is useful while resolving conflicts using an interactive
"p4 resolve" command. When you choose the "e" option to edit files, perforce
generates a single file containing changes from ORIGINAL, THEIRS and YOURS. It
is usually hard (especially when the conflicting region is large) to figure out
what others have changed and how to resolve them. Using a visual merge tool
usually helps, but this commands provides an alternative by allowing you to use
the |diff-mode| features in Vim. Once p4 invokes Vim as the EDITOR using a
tempfile as the argument, you can run this command to generate three vertical
windows each containing changes from ORIGINAL, THEIRS or YOURS only, and invokes
the |diff-options| on them. Edit the YOURS file as usual and use the |:diffget|
command from within YOURS or the |:diffput| command from the other two windows
to move diff regions into the YOURS file, and finally write the changes back to
the original temp file using the |:write| command.

                                            *perforce-selectbuf-ftplugin*
                                            *perforce-selectbuf-integration*
The perforce plugin now comes with ftplugin that adds some perforce commands to
the SelectBuf buffer browser. If you have the SelectBuf plugin installed, you
don't need to do anything special to take advantage of this. When you are
viewing the buffer list, you can execute the following commands directly on the
current buffer in the list, or the current selection of buffers:

        P4 Command      Map ~
        add             <Leader>pfa
        sync            <Leader>pfg
        edit            <Leader>pfe
        delete          <Leader>pft
        revert          <Leader>pfr
        submit          <Leader>pfs
        lock            <Leader>pfl
        unlock          <Leader>pfu
        diff            <Leader>pfd
        diff2           <Leader>pf2

I also recommend also installing multiselect.vim plugin that you can download
from www.vim.org that allows you to select multiple buffers that are
non-adjacent to do operations on them. This allows you to e.g., submit a few
files together that are spread out far from each other in the buffer list.
==============================================================================

                                            *perforce-API*
The plugin comes with an experimental API that you can use to extend the
functionality and provide some integration. Please send in your feedback to
improve the API. You should also look at the perforce/perforcemenu.vim and
perforce/perforcebugrep.vim for examples.
>
        " Return the value of the variable in the script context (so add
        "   appropriate prefix).
        " Ex:
        "   let curClient = perforce#PFGet('s:p4Client')
        String perforce#PFGet(String var)

        " Set the value of the specified variable in the script context, to the
        "   value given.
        " Ex:
        "   call perforce#PFSet('s:p4Client', 'xxx')
        void perforce#PFSet(String var, String val)

        " Call the specified function in the script context with the arguments
        "   passed and return the result. Pass appropriate number of arguments
        "   based on the function that you are calling.
        " Ex:
        "   echo perforce#PFCall('s:PFIF', '0', '4', 'info')
        "   let client = perforce#PFCall('s:GetSettingValue', 'Client')
        String perforce#PFCall(String func, ...)

        " Evaluate the given expression in the script context and return the
        "   result. The expression can be any Vim expression that is valid on
        "   RHS of a variable assignment.
        " Ex:
        "   let client = perforce#PFEval('s:p4Client')
        "   let client = perforce#PFEval('s:GetSettingValue("Client")')
        String perforce#PFEval(String expr)
<
==============================================================================

                                            *perforce-tips*
- If you are new to Perforce, try the help browser using the |PH| command. You
  can easily move back and forth in the help history using <BS> and <Tab> keys.

- The :W and :WQ commands also accept arguments that are passed as they are to
  the external p4 command. If you forgot to specify '-r' option to PSubmit,
  you can still specify it to the :W or :WQ command.

- How to quickly open the current file from a different codeline?
>
    :E <codeline>
<
- How to quickly and easily find and open a file, say x.y, which you know is
  somewhere under the current directory?
>
    :PF files .../x.y   - List the files that match x.y in the codeline. This
                          opens a new window with all the files that match x.y.
                          You can move cursor to the file-line that you want to
                          open.
    O                   - Open the file that is displayed under the cursor.
    ^Wo                 - Close all other windows (see |CTRL-W_o|).
<
  This technique can also be used with other wildcards that perforce supports.
  E.g, you can find all the shell scripts that are checked in to a branch by the
  following command (assuming they all have .sh extension):
>
>
    :PF files //depot/branch/.../*.sh
<
- How to quickly and easily find and launch a file in its associated
  application (needs configuration on non-windows platforms)?
>
    :PF files .../x.y   - List the files that match x.y in the codeline. This
                          opens a new window with all the files that match x.y.
                          You can move cursor to the file-line that you want to
                          open.
    A                   - LAunch the file.
<
- How to easily reach to a file that you know is currently checked out?
>
    :PO                 - This will create a new window with all the opened
                          files. You can move cursor to the file-line that you
                          want to open.
    O                   - Open the file that is displayed under the cursor.
    ^Wo                 - Close all other windows.
<
- You can temporarily disable the p4DefaultListSize (by default set to 100)
  while running some list commands by using the -m -1 arguments, to see all
  the results.
>
    :PChanges -s pending -m -1
<
- The plugin defines some long normal mode mappings, which could be hard to type
  without making errors or pausing for a brief moment. To type in such long
  mappings comfortably, you can download and install the execmap.vim plugin from
  www.vim.org.
- You can create aliases for most used command combinations using the Vim
  |:command| feature (from your vimrc). E.g. the following gives my pending
  change lists.
>
    :command! PendingChanges :PF changes -s pending -u hkrishna -m -1 <args>
<
- To quickly go to the lines that you have modified in the current file, open
  the diff window against the depot, scroll/find the line that you are
  interested in and use |perforce-diff-mode| features.
>
    :PD
    /FIXME
    O
<
- To quickly start over with the depot version, without needing to execute
  "revert" followed by an "edit", use the |PW| command.
>
    :PW print -q

- To insert the output of any perforce command at the current location, first
  open a blank line and run the command using |PW.
>
    o<Esc>
    :.PW describe -s 100
<
- Set "p4CurDirExpr" to the following:
>
    let g:p4CurDirExpr = "(isdirectory(expand('%')) ? substitute(expand('%:p'),
            \ '\\\\$', '', '') : '')"
<
  to have the commands run from the directory that you are currently viewing,
  instead of the current directory of Vim.

- If your colleague sends you diff for review, you can make use of :PFDiffLink
  and :PFDiffPLink commands to make it easier to reach the "before" file. In
  addition, if your colleague's dev folder is accessible by you in the same m/c
  (typically for a UNIX server), you should be able to look at the "after"
  changes in context. Even if the dev folder is accessible only over the
  network, you can convert the local paths in the diff to the network paths
  (E.g., you could convert "c:\dev" to "\\tom\dev"), and browse the changes
  comfortably.

- Do you know that :PFDiffLink and :PFDiffPLink commands can be used on regular
  "diff" command output too?

- To quickly search for change descriptions, you can print the list of changes
  matching a given restriction, with their descriptions and use Vim to search
  for the pattern. You can then describe the change for more information. Ex: >

    :PChanges -l //depot/branch/src/server/...
    /socket
<
- Use VDiff if you want to revert only parts of your changes.
                                            *perforce-explore-changed-lines*
- Here is a technique I often use to track who and when someone made a
  particular change. The technique assumes you have a branch which includes all
  the releases (typically called "release" or "main"). You would first get the
  annotations as below: >

    :PF annotate -a &main&depot
<
  Locate the line that has been changed (you might find multiple lines due to
  reformatting) and identify the version. Run the below command to identify the
  change (can be executed from the annotate window): >

    :PF filelog -i
<
  This gives you the change number and integration history for that version.
  Sometimes this is not enough to find the origin branch, so you can continue to
  execute "annotate" and "filelog" commands until you find the original branch
  and change number.

==============================================================================

                                            *perforce-limitations*
    - Interactive resolves can't be done using the plugin. You can however use
      auto resolves by passing options such as -as to the 'resolve' command. See
      "PH resolve" for help on auto-resolves. Also take a look at the
      |PFShowConflicts| command.
    - The plugin can work with only one depot at any time, but you can easily
      switch between different depots by changing the |p4Depot| setting through
      the |PFSettings| command.
    - When executing commands that take a lot of time, such as syncing on the
      entire branch, Vim waits for the command to complete and exit before
      the plugin can display the result. So until Vim becomes more capable in
      executing external commands in this regard, I recommend not to run such
      commands using the plugin.
    - Since 'q' is mapped to quit the perforce windows, it is hard to record
      macros that involve dealing with perforce windows. A workaround is to
      create a new mapping to the "q" command and use that to start and stop
      recording instead, something like this:
>
        nnoremap <F12> q
<
                                            *perforce-troubleshooting*
    - If none of the perforce operations work for you, then make sure you set
      your |p4CmdPath| setting correctly. You can run PFS command and select
      CmdPath setting to see what the current value is. On windows, if you have
      back-slashes in the path, then make sure your 'shell' setting can honor
      them. The 'shellslash' setting is also important if you use a UNIX-like
      shells on windows. IF all seems to be well, then please report the problem
      to me with your 'shell' setting and OS details.
    - If you get E485 errors occassionally or most of the time, and your shell
      related settings seem to be fine, then point your $TMP and $TEMP
      environmental variables to some path that is shorter ("/tmp" instead of
      "C:/DOCUME~1/HARI/LOCALS~1/Temp").
    - If the online perforce help is not working (ie., you are reading this by
      directly opening the file, instead of by typing :h
      perforce-troubleshooting :), then make sure you ran |:helpt| command.
    - If you are not getting automatic checkout prompt when you modify a
      read-only file for the first time (and everything else seems to work
      fine), then make sure you set your |p4ClientRoot| property correctly. The
      plugin ignores any files that are not under your root from giving this
      prompt.
    - If vdiff and vdiff2 commands don't work for you, make sure the vimdiff
      itself works for you. Try running the following command on any two files:
      >
            gvim -d file1 file2
<
      If the above command doesn't produce any diff though they are different,
      or gives any error messages, then first go through the help on |vimdiff|
      to get the standalone diff working.
    - While editing perforce specifications from commandline, if you don't see
      the perforce syntax or cursor is not positioned at a convenient position,
      then make sure you added perforce filetype as described in
      |perforce-filetype|.
    - If |perforce-ruler| doesn't work for you, make sure you have 'ruler'
      option set. Also make sure you didn't disable |p4EnableRuler| setting. It
      is also possible that another plugin is overwriting the 'rulerformat'
      setting (instead of appending to it, as done by the perforce plugin) after
      the perforce plugin configures it. Also, if you are in the 'paste' mode,
      Vim automatically disables ruler, so make sure you don't currently have
      'paste' option set.
    - If you observe a noticiable delay in Vim startup time after you installed
      perforce plugin, it may be because, the plugin is trying to obtain the
      value of |p4ClientRoot| setting by executing the "PF info" command. You
      can avoid this by setting this property yourself in your vimrc.
    - If piping a spec manually to a perforce command such as 'change' or
      'submit' using ++p option is not working, make sure the command accepts a
      '-i' option to read the spec from stdin and that you are passing in this
      option.
    - If you get a weird invalid option error, or if the command behaves
      weirdly, make sure you don't have a typo in the command-name. The
      command-line parser recognizes only the known perforce commands, which
      makes an incorrect command name a global option, making it an invalid
      syntax. E.g., if you mistype "opened" as "open", you get an error that
      "-u" is an invalid option.

                                            *perforce-version-changes*
These are just a summary of the changes done in the current and previous
versions. Though I have done a good attempt to list all, I could have very well
missed some changes.

                                            *perforce-changes-4.1*
    - Fixed broken handling of <SHOW DIFF> in describe windows. But it is better
      than before, as you can now describe multiple changelists and show diffs
      selectively.
    - For newer perforce servers, <Enter> on a pending change (in changelist)
      showed the file list twice. Removed special handling for this, which means
      for older perforce servers, you will see no file list.
    - Force a file status update on auto checkout.
    - File status handling has in general been improved.
        - Now executing command on multiple files that result in changing the
          file statuses (such as add, edit, revert etc.) will correctly result
          in their file statuses getting reset.
        - While create a new changelist or submitting a change, the Files:
          section is examined and the file statuses for all of them will be
          reset. This also works for most of the cases of modifying a changelist
          to remove/add files.
        - This will also solve a long standing issue that reload during submit
          doesn't update its file status.
    - All windows are getting navigatation commands mapped (like in help window)
    - Workaround for one of the E788 errors (originating from the plugin) during
      the auto-checkout. This part of the code has been cleaned up and
      simplified. During the auto-checkout, if there are other users editing the
      same file, it now results in the plugin echoing the output as a
      |WarningMsg|. If you missed to read the output (because you pressed
      <Enter> in advance), you can see it again using the |PFLastMessage|
      command. The other E788 originating from Vim code can't be
      fixed/workedaround, it has to be fixed by Bram.
    - Fixed broken submit from changelist.
    - When you create changelists, you can now safely undo to make any further
      changes, and save them. This also works for submissions (to edit
      description only), though you may have to remove the Files section before
      saving the change description.

                                            *perforce-changes-4.0*
    - Using Vim7 features, so it is no longer backwards compatible with older
      Vim releases. All the logic using multvals has been changed to take
      advantage of the Vim7 Lists, so it should be a lot more cleaner and
      flexible.
    - No longer depends on multvals plugin.
    - It is now autoloaded on demand, which means it will help your vim session
      load faster. Read the impact on the installation due to this change,
      |perforce-installation|.
    - A new Cancel option for checkout prompt, see
      |perforce-automatic-checkout|. The default for checkout prompt is now
      "Cancel".
    - The perforce/perforcemenu.vim needs to be loaded from your vimrc if you
      want menu to be enabled. See |perforce-installation|.
    - The plugin no longer removes the global user setting variables but you
      still need to call |:PFInitialize| for effect of some settings to
      propogate further. This should have no user visible impact (except in rare
      cases).  This will only make it easier to deal with settings. You can
      still use |:PFSettings| command conveniently for its prompting or
      completion features.
    - Setting a preset to the g:p4DefaultPreset directly now works fine.
    - Most settings can now be overridden at the buffer/window/tab level.
    - PFRefreshActivePane doesn't work well on the diff windows (especially when
      the ++c option is used).

                                            *perforce-changes-3.2*
    - Fixed PVDiff to work with two filenames. The problem was only with PVDiff
      command, as "PF vdiff" worked fine.
    - PFDiffOff command is a lot more flexible now, see |PFDiffOff|.
    - New command PPasswd for changing passwords.
    - Don't confirm revert if -a or -n option is passed.
    - Avoid accidentally loosing existing buffers while opening new ones from
      diff and other windows.
    - Recognize additional p4 commands as valid.
    - You can now pass multiple codeline modifiers, see
      |perforce-alternative-codeline-modifier|.
    - Misc. tuneups for peforce diff hyperlinking feature.
    - Misc. bugfixes in the menu.

                                            *perforce-changes-3.1*

    - This version introduces the concept of overriding settints at the
      buffer/window level (an extension of the existing support for
      b:p4Options). Makes it easier to work with multiple clients from a single
      vim instance. Currently only the p4Client/p4Port/p4User/clientRoot can be
      set at buffer/window level.
    - Now view mappings are maintained separately for each client. This allows
      us to easily work with multiple clients at once. Also see
      |perforce-buffer-local-options|.
    - For diff hyperlinking, avoid refreshing the depot file if it already
      visible.
    - Now supports <pfitem> tag to mean the current list item. See |:<pfite>|
    - New :PExec command to make it easier to execute exeternal perforce
      commands directly, when plugin can't do what you want. See |PExec|.
    - PFDiffLink and PFDiffVLink commands couldn't handle "diff -r" output.
    - If the current directory is not same as the directory of file being
      resolved PFShowConflicts didn't work.
    - PItemOpen in describe window now opens the local file, as PItemDescribe
      can be used to open the depot file.
    - Misc. bug fixes:
        - Negative revisions are not working any more. E.g., PP #-1
        - PW is not using the custom completion, so revision specifier (#1)
          still needs to be escaped.
        - While rerunning a command that opens up a new buffer (such as PD),
          unexpected warning messages about matching an existing buffer.
          Instead, it should silently refresh the output.
        - Diff hyperlinking, prints the depot file everytime, this causes
          unnecessary delays.
        - PFRefreshActivePane would fail if there are filename special
          characters in the command.
    - PF command now implements a special completion mode to complete both the
      perforce command as well as files. Now you no longer need to protect the
      revision specifier (#<revision) as long as it appears at the end of the
      argument.

                                            *perforce-changes-3.0*
    - Discard the diff output if P4DIFF env. var. is set (Denis Perelyubskiy).
    - There is an experimental API to allow some modularization of the plugin.
      See |perforce-API|. There are plugin modules available under perforce
      directory that take advantage of this.
    - New PFBugReport command to generate "perforcebugrep.txt" file. This is
      implemented as a new module perforcebugrep.vim using the above API.
    - The menu creation is now separated as a new module that is executed on
      demand. Other than giving some modularity, this effectively reduces the
      resources consumed by the plugin, especially when the menus are disabled.
    - New settings and features that allow dynamic switching of perforce client
      settings (Mark Brophy). See |perforce-dynamic-client|.
    - The default options don't get saved with the perforce windows (Mark
      Brophy).
    - IsFileUnderDepot() should ignore case for windows (Mark Brophy).
    - Some enhancements to the "diff-hyperlink" feature, see |PFDiffLink|.
    - The plugin now translates the depot paths to local paths and vice versa
      accurately by reading the client specification. This is an experimental
      feature and so will very likely have bugs in it. While reporting bugs,
      please include the "View" section in your client specification and the
      path. See |p4UseClientViewMap| and |PFUpdateViews|.
    - For consistency and to avoid potential conflict with the actual perforce
      commands, most of the plugin commands that are not associated with any
      external perforce command are prefixed with "PF". This involves renaming
      of the following commands. If you would like to continue to use the old
      command, you can add your own commands with the old names that in turn
      call the new commands.
            PWipeoutBufs          -> PFWipeoutBufs
            PDiffOff              -> PFDiffOff
            PToggleCkOut          -> PFToggleCkOut
            PRefreshFileStatus    -> PFRefreshFileStatus
            PRefreshActivePane    -> PFRefreshActivePane
            PSwitch               -> PFSwitch
            PSwitchPortClientUser -> PFSwitchPortClientUser
            PLastMessage          -> PFLastMessage
            PBugReport            -> PFBugReport
    - :PFSettings command now optionally takes the name of the setting (as
      displayed in the interactive session) and the value. The command also
      supports completion, so you can type in a partial setting name and let Vim
      complete it for you.
    - I have changed the way the perforce client related settings are done.
      Instead of using three different settings, "p4Port", "p4Client" and
      "p4User", I have introduced a single setting for all the three called
      |p4DefaultPreset|. The old settings are no longer recognized and these
      will not appear when |PFSettings| is run. However, you can use |PSwitch|
      and |PSwitchPortClientUser| commands to change to an arbitrary client at
      runtime. Other than |p4DefaultPreset|, there are two new settings,
      |p4CurPresetExpr| and |p4CurDirExpr|. Also, to be consistent, the
      p4Password setting is no longer supported. Use "P4PASSWORD" environmental
      variable for the same effect, or just let the plugin prompt you for one
      when required.
    - New command |PFileEdit| in filelist view.
    - New plugin perforce/perforceutils.vim. Adds a useful |PFShowConflicts|
      command. See |perforce-utils|. The |perforce-diff-hyperlink| feature is
      also moved into this module with some enhancements.
    - For consistency, some built-in options have been changed. Now all the
      built-in options should be prefixed with "++". The options prefixed with a
      single "+" are reserved for passing options to the external commands. The
      following options have been modified to accommodate this:
            Old option  New option  Scope ~
            +y          ++y         PF, PWipeoutBufs
            +c          ++c         PDiff
    - New diff mode to execute external GNU diff command to generate the diff
      output. See |perforce-external-diff|.
    - New commands on filelist view, PFileLaunch, PFileLog. PFilePrint has been
      enhanced to print previous version if the head action is "delete" and
      avoid printing binary files.
    - Many misc. bug fixes and enhancements and general toning down of the code.
    - A new integration with SelectBuf plugin. If you install SelectBuf, you can
      execute a bunch of commands right from the buffer list. See
      |perforce-selectbuf-integration|.
    - The default value for 'bufhidden' setting in the perforce result buffers
      is now set to "wipe". This works much better than the earlier approach to
      wiping out buffers as they get unloaded, and gives better control to
      users. Consequently, the g:p4HideOnBufHidden option is now replaced with
      the g:p4BufHidden option.
    - The plugin no longer handles all the FileChangedShell events, instead only
      the events generated during the execution of the perforce commands are
      captured to refresh file-status. This is so that the default Vim mechanism
      is least impacted. To manually refresh the ruler see
      |perforce-refresh-file-status|.
    - New :PChangesDiff command in changes window.
    - Fixed the argument parser to recognize context size in the diff flags
      (such as "-du10"), didn't actually know that you could pass context to the
      diff flags. Also, the |perforce-default-diff-format| option has been
      changed from "-dd" to simply "-d".
    - All the perforce commands now implement a custom completion that completes
      arguments in a context sensive manner. They can also complete depot paths
      by running the "dirs" and "files" commands. In addition, |PHelp| supports
      help topic completion, |PFSettings| supports setting name completion and
      |PFSwitch| commands supports preset completion.

                                            *perforce-changes-2.0*
    - Renamed g:p4CodelineRoot to g:p4ClientRoot.
    - Fixed a problem with choosing a default username on cygwin.
    - Added support for showing ruler with the file status from "Tom Slee",
      Perforce plugin with some enhancements.
    - Added support to obtain the clientRoot from the perforce server, if it
      is not already defined.
    - More robust error handling. Now there is very less chance (or none) of
      messing up the current window.
    - Fixed to use setlocal instead of set command for changing some settings.
    - Filelog also honors the defaultListSize option.
    - Better formatting options for the form windows.
    - The default option for checkout file dialog is changed from "Yes" to
      "No". Use the |p4CheckOutDefault| option to get the old behavior.
    - On Windows, allow execution of commands containing filename special
      characters by replacing them with a [x] sequence. They are mapped as,
>
          '*' -> [S], 
          ':' -> [C],
          '?' -> [Q],
          '"' -> [D],
          '<' -> [L],
          '>' -> [G],
          '|' -> [P],
<
    - Now you can use -ve revisions to indicate previous revisions from the
      head. You can also use branch specifiers to mean the same file from a
      different branch. Also these enhanced revision specifiers are now
      acceptable anywhere.
    - Extended diff to take "++c" argument to specify change number. See
      |perforce-pending-change-diff|.
    - Added vdiff and vdiff2 commands. Added p4UseVimDiff
      option. See |perforce-vim-diff|.
    - Added PFileChange command for the filelist window.
    - You can now pass "++y" option to revert to skip the prompt.
    - New command |PFSettings| to interactively change the settings of a
      session.
    - The script now has a more robust and compact architecture, which actually
      helped reducing the size of the plugin even after adding many more
      features. I have also consolidated all the logic into one method described
      by a set of metadata variables. Adding new features in the future should
      be easier.
    - The opened list is now better than ever. You can use it to quickly reach
      to a file that you have already checked out of perforce. See
      |perforce-filelist|
    - You now have a way to preserve the perforce windows from getting wipedout
      as soon as they are hidden. This feature can be used if you are intending
      to keep them opened for a long time (such as "opened" list windows).
    - You can now change the name of the depot from the default "depot". This is
      useful if you have multiple depots in your system.
    - I have extended the command syntax with the
      |perforce-command-mode-specifier| for the more demanding users.
    - The "change" command now takes perforce filename patterns to filter out
      the initial list of files that should be included in the change. The
      "submit" command already does this. See |perforce-changelist|.
    - You can now press "q" to quit in read-only perforce windows (David
      Fishburn).
    - Improved the handling of back-slashes and spaces in filenames.
    - The vim built-in :w and :wq commands work exactly like the :W and :WQ
      commands respectively. For "submit", they now prompt for confirmation,
      which can be suppressed by passing a "-y" option.
    - Now the specification windows are regular buffers. For reasons on why this
      is much better than the earlier approach, read towards the end of
      |perforce-forms|.
    - The plugin now uses try/finally blocks to avoid leaking any changes done
      to global settings in case of unexpected errors.
    - The submit command now detects partial errors that results in an
      automatic changelist creation, and modify the template appropriately. This
      also works while creating a new changelist, so that after saving the
      changelist, you can just undo and continue making further changes.
      See |perforce-submit|.
    - Hyperlink the diff window to the source. Pressing O or <CR> on a line
      takes you to the source line. See |perforce-diff-mode|.
    - Fixed some bugs with passing special characters and whitespace to shell.
    - A dummy option "-dd" to mean the default diff format. See
      |perforce-default-diff-format|
    - A new ftplugin for perforce forms which can be made to work even while
      starting forms from p4 directly. See |perforce-ftplugin|
    - This help file itself is new.

                                            *perforce-todo*
                                            *perforce-known-issues*
Not in any particular order:
    - PChangesDescribeCurrentItem doesn't work for pending changelists from
      other clients.
    - A deleted file is showing up as unopened.
    - Consider #none also as revision in the syntax highlighting.
    - I don't think the p4Depot setting is being handled correctly. We need to
      investigate how depots created using "p4 depot" are used.
    - There is a Syntax highlighting for: "<file>#1 - added as <file>". How is
      this message generated?
    - When you open a spec window with perforce wildcard patterns as arguments
      (such as "P4 submit .../*") saving works as long as you don't change the
      current working directory of Vim after creating the spec window, otherwise
      because of some weird behavior in Vim, you get an E212.
    - You can't login using the plugin.
    - <pfitem> should be handled at a higher level for it to be more useful.
    - During the auto-checkout, Vim will give error E788 if the ftplugin uses
      :compiler command. This is a known issue with Vim7.0 release, and might
      get fixed in a future patch.
    - When PFSwitch fails because the perforce server is not up, you are forced
      to switch to another setting and come back to it to select it again.
    - When reverting files from files view, if you select No for the prompt, it
      still refreshes the window.

                                            *perforce-wishlist*
Here is a list of changes that I think will be useful to do, in no particular
order:
    - PChangeSubmit etc. should have menu entries in change menu.
    - Sort change lists and show those that are by the current client and
      others separately.
    - The "nmap <buffer>" output can probably be used to generate a simple help.
    - A command to rename files (Raj). Invoke integrate and delete internally,
      for convenience.
    - It will be nice if the change number is automatically remembered.
      Also, we should be able to set a change number which should be
      automatically applied to all the edits, deletes etc.
    - How can we support interactive resolves? Will it be worth doing it?
    - In filelist view, allow visual select on the files to be operated upon
      (for revert etc.).
    - I should be able to parse the output of p4 resolve using this command:
        sh -c "while true; do echo s ;done" | p4 resolve
    - How can we avoid prompting for checkout when the current vim session is
      in view mode (-R option)? For now just use PFToggleCkOut command in such
      sessions.
    - The script now has knowledge of client-view settings. There may still be
      places that assume that the branch name and local directory name are same.
    - The menus can be further improved.
    - The list specific menus should be disabled unless you are in that
      window.
    - Backup/Restore commands for opened files will be useful. For now, just use
      the included shell scripts.
    - A simple p4win style explorer will be helpful for quickly browsing the
      depot.
    - Negative revisions for dates also? Is it possible using vim functions?
    - Check for unsaved buffers during submit. Requires us to look into the
      buffer list.
    - There should be an option to show/hide deleted files in the filelists
      (PFiles).
    - The PPasswd can't be used when either the old or new password is empty.
    - There should be an option to have a single perforce-log window where all
      the output gets appended, instead of opening new windows for each command.
    - We should be able to pass file patterns to be used as the View while
      creating a new label command.
    - We should have a feature to diff2 in labels and changes views when started
      with a filename as an argument. Also diff from changes view.
    - A command to refresh only the files that are in a label. Works well for
      lables containing only a partial list of files.
    - Supporting backquotes could be useful when the shell is unixy.
    - In list views (and filelog view), we should be able to map the mouse
      presses such a way that single mouse click results in selecting the entire
      line and mouse drag automatically selects the entire line. We will then
      need to make sure all the list view local commands will work with visual
      mode.
    - If the current buffer is a directory (i.e. opened with the vim
      filebrowser), it would be nice if the plugin could simply append '...'
      to the relative path, so something like PSync would make perforce sync
      all files under the current directory (Mark). In otherwords, it would make
      sense to append '...' to the directory name whenever a command that
      defaults to current buffer is executed on a directory buffer.
    - How about using v:dying to determine if the vim session is crashing and
      preserve the spec buffers?
    - Executing "admin" command shouldn't open up a new window.
    - Better support for "monitor" command.
    - There should be an option to position the current line in the diff (if
      exists) (like view current line in the diff).
    - While viewing a directory, it will be nice if the file completion
      happens relative to the directory that is being viewed, rather than the
      working directory of Vim. We probably should have an option to turn it
      off.
    - It is possible to have a command that starts p4win with options such as
      -s.
    - vdiff should print the have version not head version, unless this
      information is for some reason not available.
    - While doing custom expansion for files (:PF command), the spaces in the
      filenames should be escaped.
    - For diff hyper linking, there should be a way to always open the depot
      file (even for the context lines).
    - In DiffLink, detect the column position also. Also add a way to jump the
      diff region containing the current line.
    - There should be a way to force deletion from the users list (-f option).
    - Need a "blame" built-in command to produce annotated output with change
      numbers in them.

                                            *perforce-bugreporting*
Please read the entire plugin online help before you report any bugs, as it will
help clear up scenarios which may not indeed be a bug. In addition,
    - Refer the p4 user manual and online help to be clear about the right
      behavior.
    - Check if it is already mentioned in the |perforce-limitations| or
      |perforce-known-issues| sections.
    - Run :PFBugReport command to generate "perforcebugrep.txt" file in the
      current directory and attach that with your email. Before sending this
      out, check to make sure it doesn't contain any confidential information!

Please send your reports to hari_vim at yahoo dot com.

                                            *perforce-acknowledgements*
- Tom Slee (tslee at ianywhere dot com) for his idea of creating a status
  bar with the p4 fstat information (see
  http://www.vim.org/script.php?script_id=167).
- Leo L. Schwab (leo dot schwab at openwave dot com) for reporting problems and
  helping me with debugging them.
- David Fishburn (fishburn at ianywhere dot com) for his idea with mapping the
  'q' key to quit non-editable perforce windows, and reporting various bugs.
- Mark Brophy (mbrophy at esmertec dot com) for his ideas with using P4CONFIG
  and others that allow dynamic configuration.
- Various others for sending bugs, patches, ideas and feedback. Some of them
  are:
    - Denis Perelyubskiy (denisp at CS dot UCLA dot EDU)
    - Kevin McCarthy (tunacat at yahoo dot com)
    - Paul Wright (paul at noctua dot org dot uk)
    - Reva Revadigar (reva dot revadigar at autodesk dot com)
    - Peter Hutkins (PHUTKINS at altera dot com)
    - Brett Humphreys (bretth at aiinet dot com)
    - Craig Emery (craig dot emery at ntlworld dot com)

 vim6:tw=80:ts=8:ft=help:ai:sw=4:et