Perforce Plugin


An Updated version is now available at Sublime Plugins – Perforce


What is Sublime Text 2 and what does the Perforce Plugin do?

Sublime Text 2 is a light weight text editor that is really fast and extendable. At the moment, I use it to edit PHP, Python, HTML, CSS and JavaScript files. There is a lot of community support to provide plugins (programmed in Python) so the editor keeps improving.

Trying to do my part, I did a small Perforce integration plugin. Right now it takes for granted that you have an open ticket with your Perforce server, otherwise the actions will simply fail. The plugin is still work in progress but I try to work on it daily to add features here and there.

For troubleshooting, click here.

Getting Started

Getting Sublime Text 2

At the time of writing, Sublime Text 2 is “free” (a pop up will appear every now and then to suggest you buy a license) or available for pretty cheap, 59$. For such a great editor, I highly recommend buying it to support the developer. Download

Getting Perforce Plugin

My plugin is available in a couple of ways, but here’s my recommendations:

  • Download and install Package Control for Sublime Text 2
  • Open the command window (ctrl+shift+p in the default install)
  • Select Package Control: Install Package
  • Type “perforce”, press enter


  • Browse to GitHub for my Sublime Text 2 Perforce Plugin repository
  • Download the Zip File
  • Locate your “roaming app data” folder, on Vista (old laptop, I know…) it’s located here: C:\Users\*your username*\AppData\Roaming
  • Browse to Sublime Text 2\Packages
  • Create a Perforce folder
  • Copy the content of the folder ericmartel-Sublime-Text-2-Perforce-Plugin-?????? in the newly created Perforce folder so that resides in the root of Sublime Text2\Packages\Perforce


Event Handling

The plugin has two commands that react to events related to saving files.

Auto Add

When the plugin detects that you’re trying to save a new file (didn’t exist pre-save, exists post-save) and the file resides within your client root, it will automatically mark it for add.

You can disable this feature by changing the value of perforce_auto_add to false.

Auto Checkout

When the plugin detects that you’re modifying (perforce_auto_checkout_on_modified set to true) or you’re trying to save an existing file (exists pre-save – perforce_auto_checkout_on_save set to true) and the file resides within your client root, it will automatically try to checkout the file. For the moment there’s no handling of exclusive checkout or other conditions that could make the checkout fail.

You can disable this feature by changing the value of perforce_auto_checkout to false.

Text Commands

The text commands are all available through the command window (ctrl+shift+p in the default install). By typing perforce you can filter only the commands related to this plugin:

Filtered Perforce Text Commands

As you can see, you will even see the keyboard shortcuts assigned to these commands, as an example I assigned “ctrl+alt+x” to the Graphical Diff with Depot. Triggering the command from this window, from the Console (ctrl+`), from a menu item or from a keyboard shortcut will all result to the same thing.

These commands all redirect the p4 output to the Console window (ctrl+`) and a warning in some cases where the file in the view is not in the client root, if the perforce_warnings_enabled setting is set to true.


This command will attempt to checkout the file in the current view. Not much error handling is made. Use this command to manually control your checkout, if the perforce_auto_checkout setting is set to false.


This command will attempt to add the file in the current view. This is useful if the file was not created directly through Sublime Text 2 or if the perforce_auto_add setting is set to false.


This command will prompt you for a new name for the file in the current view.


This command will delete the file in the current view from Perforce.


This command will attempt to revert the changes made to the file in the current view.


This command outputs directly the result of a call to p4 diff with the file in view to the Console (ctrl+`). Recommended to more advanced users as the output is not really user-friendly.


This command calls p4diff and compares the local version of the current file with the version in the depot. I wish I could extend this to support Araxis Merge, but unfortunately I’m on sick leave for a couple of months and don’t feel like buying a license for my personal needs. Feel free to donate one and I’ll make the plugin configurable 😉


This command will create an empty changelist and prompt the user for a single line description.


This command lists all the available changelists and then lets the user type a line to be added to the description.


This command lists all the available changelists, adding “New” to the list. By selecting a changelist, the file will be moved to this changelist. If new is selected, the user is prompted to enter a description for the new changelist.


This command lists all the files that are currently checked out sorted by changelist with part of the changelist description.

List of Checkedout Files

Here’s my current listing for a small web project I’m working on. Under the black square is the rest of the local path, but I didn’t want to make public the name of my project yet!


All the commands are easily available through the Tools menu (screenshot not updated):


Hopefully this section will help users experimenting issues with the plugin.

p4 not found

The p4 executable needs to be accessible from the plugin.  Under Windows, make sure that you %PATH% contains the folder where you installed p4.exe.  On OSX, things are a little bit different, to try to cope with most issues, the content of .bash_profile is always loaded before executing a command so adding the folder where you put P4 in your export PATH should do the trick.

file is not under client root

To avoid slowing down your system with remote calls to Perforce, the plugin uses the contents of p4 info to know which files should trigger checkouts, adds, etc…

The most common mistake is usually that p4 is not configured with a default client, which can easily be solved using the following:

  • Usage of p4 set P4CLIENT which will set environment variables
  • Usage of P4CONFIG files in your document hierarchy

What’s Next?

Please make suggestions. The plugin does what I need for now, I might polish it or update it depending on my usage but if you’d like something added, feel free to ask!

How you can contribute

I will gladly accept bug reports on GitHub and suggestions by email (or use the contact form on this page if you can’t find my email address – with all the spam I keep receiving recently it shouldn’t be hard to find).

I keep a changelog in the main file of this plugin so you will be credited for your contribution!

Also, please buy Sublime Text 2 to support its developer!

95 thoughts on “Perforce Plugin

  1. IK says:

    Thank you for plugin, but I am having a trouble with plugin.

    I am using Ubuntu 64 bit and Sublime Text 3.(I tried this onto Sublime Text 2, same error encountered)
    P4 is under different directory, but it is executable on terminal without path

    I tried diff, it shows me “/bin/sh: p4: command not found
    So I tried the comment you posted here for Mac OS X, but no luck.
    I’ve checked $PATH, $P4_HOME, $P4USER, $P4CLIENT, $P4PORT, everything is all correctly set. I added these settings on .shell.

    Please help me I really want to use this.
    Thank you in advance

  2. Eric says:


    I will try creating a setup using Ubuntu and ST3 and see what’s happening! I validated it once ages ago, maybe something broke since then 🙁


  3. Darin says:

    How do I edit the settings for Auto Add and Auto Checkout? I installed your Perforce plugin using Package Control on ST3. I assumed there was a Sublime settings file, but I don’t see it.

  4. Darin says:

    I was able to modify the settings by pulling a settings file from GitHub and placing it in ~\AppData\Roaming\Sublime Text 3\Packages\User. That file was not created when installing through the ST3 Package Manager.

    I am experiencing significant typing lag when editing a file that has been checked out with your Perforce plug-in. I disabled all of the auto settings thinking the event checking might be slowing things down. Any other ideas?

  5. Eric says:

    Hi Darin,

    Yes sorry, that’s exactly how to provide a settings file.

    Unfortunately this version of the plugin is synchronous and doesn’t cache anything, so I suspect the on_modify is poking your Perforce server and it takes a while to respond?


  6. Darin says:

    For some reason, something in your Perforce is still causing significant typing lag. I disabled the auto_checkout and auto_add, but is there still something else that the plugin is doing/polling in the background? It seems to me that after I checkout the file, the plugin would be idle until I tell it to do something.

  7. Eric says:

    That’s indeed what it “should” do! I wrote this over a year and a half ago so I’ll dig into the code to see what could be happening.

    It seems like the only other check is to see if the file is writable, this shouldn’t cause that much latency 🙁

  8. Darin says:

    When do you check if the file is writable? Is that with every input? For example, I can move the cursor with no lag at all. However, when I edit the file there is lag. I can then disable the plugin and immediately the lag goes away.

    In my environment, I’m editing files that are not stored locally but on a shared network drive. I’m guessing whatever is happening on_input with your plug-in is exaggerating the latency.

  9. Eric says:

    Check line 286 of the plugin, you could probably move the auto check out check before the writable check and it would solve your current issue!

    I’ll think about shared network drives for the next implementation of the plugin! Thanks

  10. Darin says:

    Yes! Working perfectly now. Just installed the plugin manually from your ST3 github version. Then I re-ordered the auto checks to only check file writability based on the settings. Thanks for the help.

  11. Obi-Wan says:

    Hi Eric!

    I would like to know if the following is possible with this plugin.

    An example:
    If one searches for a keyword the results page returns 100 files that contain that keyword.
    Is there a way to checkout all those files in one shot?

    Thank you in advance.

  12. Eric says:

    Hi Obi-Wan, sorry I didn’t see your message earlier!

    Take a look at p4 edit, it supports wildcards, you can probably use it directly for what you’re looking for:


  13. Chris says:

    I’ve tried this with both Sublime 2 & 3 on OSX, both with the same results. Despite being able to interact with Perforce via command line to my hearts content, when I try to use this, I always get the error “File is not under client root.”

    The file IS under the client root, and doing a ‘p4 edit ‘ works fine.

  14. Eric says:

    Interesting! On OSX I’ve seen cases where the path didn’t match the case (it’s supposed to all be tested in lower case so it shouldn’t be a problem) and it was failing to find it under the client root. Would you mind sharing some of your “p4 info” with me by email? emartel at gmail


  15. Robert Schmidt says:

    Hi Eric,
    Thank you for a great plugin!
    I have an issue with workspaces. I use multiple on the same PC, but the plugin seems to assume it should use the global default name (machine name or the P4CLIENT environment variable?).

    P4 command line tools traditionally support the P4CONFIG variable (defaults to “.p4config”). They then search for a file with this name up the tree from a file’s location on disk. When found, it provides overrides for any/all P4 environment variables.

    My example in a workspace root:

    Do you think this would be feasible to support in the plugin? This would streamline my work in ST3 tremendously! As is, I’m only able to use the plugin in my main workspace, and have to remember to check out/add files in other workspaces before editing or saving. If I don’t the plugin will automatically create a new workspace named after my PC.

    Thanks again!

  16. Eric says:

    Hi Robert,

    Thanks! 🙂

    I’m a bit busy at the moment but I’m taking a note to look at your specific issue ASAP. Since the plugin only calls the command line tools, I would have assumed the .p4config files would be taken into account.

    I’ll do my best to keep you updated soon

    Thank you


  17. Robert Schmidt says:

    Sorry Eric, my mistake!
    Your reply got me thinking that the fault was on my side.

    It turns out I was using ST on a new machine, which didn’t have the P4CONFIG environment variable set. Setting it fixed the problem!

    Thanks again!

  18. Andrew says:

    Like Chris, I am on OSX and am also getting “File is not under client root.”, although the p4 cli works fine. Any updates on this issue?

  19. Eric says:

    After investigation, with a setup similar to yours I got it working no problem. I’ve seen issues in the past with Case Sensitivity on the server, is this turned on?

  20. Andrew says:

    Thanks for looking into this Eric. Oddly turns out I had an error in my .bash_profile which looks like sublime wasn’t letting slip. I found this by watching the console after setting:
    perforce_log_warnings_to_status”: false

    Thanks for the cool plugin!

  21. Eric says:

    I’m glad the plugin is useful to you! Cheers!

  22. VJ Goh says:

    You mentioned that there might be a problem when the server is case sensitive? I’m having the same ‘File is not under client root’ issue that some other people had, and I’m not sure what’s up. I’ve got ~/.p4config specified in the settings file (I’m on Windows, so I hope it’s searching the path specified in the HOME environment variable), but I also created a p4config.txt and filled in the .bash_profile file just in case.

    Checking out in a Windows shell works, though I notice that the cygwin shell bugs out, complaining about some sort of server error. (That seems unrelated; the plugin is complaining about the client root, not that it can’t connect to the server.)

    This looks great; I hope I can get it working. 🙂

    These settings seem to work with my emacs plugin,

  23. Jitendra says:

    I have installed this plugin and it is nice. But I dont know how to connect my perforce server using this plugin. Due to connection issue, I think I am not able to “Checkout” the files.

    Thanks in Advacne.


  24. Eric says:

    Hi Jitendra,

    Can you run “p4 info” on the Command Line and see if its output seems correct?


  25. Steven says:

    Hi Eric,

    Is there a way to change the Perforce workspace? I have a lot of them and changing to another one could really help my workflow. I already use an alternative .p4env file to at least keep the workspace I use in ST different from the standard one I use in my console.

  26. Eric says:

    Hi Steven!

    I started working a while ago on the next version of the plugin which would include a connection manager, but with very limited time at home I didn’t finish it yet.

    P4CONFIG files, like you’re already using, are probably the way to go!


  27. Christine says:

    I installed this package in Sublime Text 3. I then entered my perforce password using the login command. When I try to check out a file, I get an error: “Perforce Plugin: p4 info didn’t supply a valid clientspec, launching p4 client”. The client doesn’t launch automatically, and when I launch it manually, I get asked to log in, even though I’d logged in a few minutes ago. The requested file is also not checked out. What am I doing wrong?

  28. Eric says:

    Hi Christine,

    This usually means that the plugin wasn’t able to parse properly the output of your “p4 info”. When you call the command by hand, what does the output look like? You can email it to me if you want me to take a look at it. Also, make sure that p4 is in your path, I’m surprised p4 client fails.


  29. Christine says:

    I sent you that info (prefer not to publish in the open forum). p4 is installed in the usual location: “C:\Program Files (x86)\Perforce\p4v.exe”. Sublime is installed in “C:\Program Files\Sublime Text 3\sublime_text.exe”.

  30. Donald Organ says:

    I am also on OSX and getting the “file is not under client root” error.

  31. DWishR says:

    I’ve battled with getting this working on OSX in the past. I finally figured out my problem. (“perforce_log_warnings_to_status”: false really helped!)

    I always place executables in /usr/local/bin. For whatever reason, sublime’s shell doesn’t have that in its path. I moved p4 to /usr/bin and everything is working!

    Maybe I’ll find this next time around. :]

  32. Amit says:

    Eric/Christine – Did you guys figure it out? I am struggling with same issue?

  33. Amit says:

    Have you got it working?

  34. Deepak Michael says:

    Nice work. I faced the ‘error: “Perforce Plugin: p4 info didn’t supply a valid clientspec, launching p4 client”’ issue as well. But I was able to find out what the issue was in my case.

    It wasn’t able to launch the p4 client as well after this pop-up. I tried running p4 directly from the command prompt and realized that the p4charset was not set and that’s why it was failing. Setting the p4charset got things going (apart from defining a P4CONFIG, updating PATH and verifying things via p4 set).

  35. Ryan Mustard says:

    Wonderful plugin, thanks for developing it. I had the PATH issue on Mac OS X. Couldn’t find p4. I wanted to add my experience and see if I diagnosed the problem correctly.

    The problem is that launched from Finder doesn’t get the PATH the same way a terminal does. The terminal will use /etc/paths file to build the path but Finder does not. So I was able to move the p4 executable to /usr/bin and everything started working.

    I chose to do that instead of managing the PATH variable.

  36. Anthony says:

    Hi Eric,
    I’m having the same problem as Christine above, Except on ubuntu 12. Was there an update on the situation?

  37. Eric says:

    Configuring your default workspace should do the trick (see p4 set, P4CONFIG, etc…)

  38. Christine says:

    I just got a number of notifications of old posts. Sorry for the delay in responding. Yes, I did eventually get it working. I forget exactly what I changed that finally did the trick. It is very helpful to me. Thank you.

  39. Alex says:

    I have the same issue that perforce plugin:p4 info did not supply a valid clientspec with the sublime text 3 of window installation.
    Is there a checklist that we could verify what might be missing for the setup? Thanks in advance.

  40. George says:

    Hello Eric,

    Thanks for good job on plugin. This is what I’ve always searched for sublime, but I’ve got a question, how can I properly configure it to work with perforce?

    Cause currently I’ve got an error: “file is not under client root”

    IDE: Sublime Text 3 (C:\Program Files\Sublime Text 3)
    OS: Windows 7
    Perforce: C:\Program Files\Perforce

    p4 is in PATH, and from cmd p4 is working.

    p4 SET

    P4EDITOR=C:\Program Files\Sublime Text 3\sublime_text.exe

    name: myworkspace
    root: C:\Users\my.user\Perforce\myworkspace\

    I would greatly appreciate any help you can give me in working this problem.

  41. George says:

    I’ve just changed in config Perforce.sublime-settings parameter to “perforce_p4env”: “” and it fixed issue. Thanks.

  42. Leon says:

    whatever I do, I still receive the same error: “error: Perforce Plugin: p4 info didn’t supply a valid clientspec, launching p4 client”. when check the, I found that the result of command ‘p4 info’ is always empty. do you know how to fix it?

  43. Leon says:

    I fixed the issue by setting the perforce_p4env to my environment variable config file.

  44. Christine Forber says:

    I recently updated to Windows 10 and am unable to get this plugin to work. p4 info shows the correct settings. Not sure what to try next.

  45. Eric says:

    Hi Christine,
    I sent you an email, I’ll most likely need more info to help you out

Leave a Reply

Your email address will not be published. Required fields are marked *