February 14, 2012

New in 2012.1: P4IGNORE


Every workspace has some files that aren't meant to be added to the depot. As of Release 2012.1, the P4IGNORE environment variable gives us a new way to ignore workspace files. Simply create a file at the root of your workspace that contains a list of file names to ignore. For example, create a file called .ignore, containing this list:

# no tmp directory

(Note that the name of the file in this example is itself listed in the file.) Now, set your P4IGNORE environment variable to the base file name of the file just created. On Windows or MacOS, for example:

p4 set P4IGNORE=.ignore

(On non-MacOS Unix systems you'll have to use the native shell to set P4IGNORE.) You can also set P4IGNORE in your P4CONFIG file. Add a line to your P4CONFIG file that looks like this:


P4IGNORE affects only the commands that search for or add new files: p4 add, p4 status, and p4 reconcile. If you need to bypass P4IGNORE -- to ignore your ignore files -- you can use the -I flag with any of these commands. For example:

p4 status -I .../.ignore

Once P4IGNORE-listed files are opened for adding, Perforce ceases to ignore them. If you've opened files you meant to ignore, you'll need to revert them or they'll be treated like normal, opened Perforce files.

You can put P4IGNORE files in any of your workspace subdirectories. If you're used to P4CONFIG, be aware that there's a big difference between how P4CONFIG and P4IGNORE are treated by Perforce:

  • The P4CONFIG check runs in the current directory. It continues through parent directories, and stops as soon as the first P4CONFIG file is found.
  • The P4IGNORE check runs in every directory that is searched for new files to add. It continues through parent directories, and doesn't stop until all of the P4IGNORE files are found.

Each P4IGNORE file contains rules to ignore filenames in its own subdirectory path. And each P4IGNORE file's rules are added to the rules of the P4IGNORE files in its parent directory. A P4IGNORE rule is simply a file name pattern, with a bit of special syntax. For example:

# somethingA comment.
*.xmlIgnore all files with the ".xml" suffix
!special.xmlOverride preceding rules and do not ignore files named "special.xml"

If you've ever used Git, you'll recognize this behavior. (In fact, if you're using Perforce in combination with Git, you can simply set P4IGNORE to ".gitignore".)

So with Release 2012.1, we now have three methods for making Perforce ignore workspace files:

  1. Using exclusionary mappings in the workspace client view. This affects all Perforce commands. You can use this method in your own non-stream workspaces.
  2. Using the 'Ignored' field in stream view templates. This generates exclusionary mappings as well. It is the same as method 1, but for stream workspaces. A stream owner can use this method to control everyone's workspaces for the stream.
  3. Setting P4IGNORE in the local environment. This combines with methods 2 and 3. It affects only the Perforce commands that open files for adding. You can use this method in any workspace you own.

As I write this post, the topmost request on p4ideax is support for .ignore files. In the second-highest position is a request for a recursive add command. Both of these requests are satisfied in Release 2012.1, by P4IGNORE and p4 reconcile, respectively. Kudos to the Perforce development team for delivering what customers want most!