December 3, 2015

P4IGNORE: Ignorance is Bliss

Media & Entertainment
Traceability

Over the years my way of working with Perforce (now Perforce Helix) has changed dramatically.

When I started out eight years ago, I mapped every project to my client workspace, including the mainline and the most recent release branches as well as my development branches. This made integrating between different branches easy, but it came with a price: a careless p4 sync brought the whole repository down and several pending changes in different projects infrequently found their way into a single submitted change.

These days I split my work into separate workspaces, one for each project and branch (actually, I am using DVCS more and more, which has some nice tricks concerning branches.) The directory structure on my local disk still resembles what we have in our depots, but now there is a P4CONFIG file in each project root. Syncs and pending changelists are confined to individual project branches, which restored my sanity.

I also used to sync every file in read-only mode and opened the files explicitly with p4 edit, causing some grumbling occasionally when I forgot to add new files with p4 add, which resulted in a broken build.

Now that we have p4 reconcile and p4 status it allows me to work the Subversion or Git way: make edits first, then discover easily (and very quickly) what has changed, and submit the changes. That’s great, but chances are you’ll wind up with more files in your depot than you bargained for: all the IDE configuration files and binary artefacts from your builds, for example. P4IGNORE to the rescue!

P4IGNORE

Define the environment variable P4IGNORE or specify it in your P4CONFIG file to point to a filename like .p4ignore for example. Then create a file with that name in your workspace root and list the files and directories you want ignored (find the exact syntax in the documentation here).

There are some great features build into the P4IGNORE architecture that I found really useful:

Combine several P4IGNORE files

You can create a general P4IGNORE file in your home directory, a project specific P4IGNORE file in your project root and maybe even a different P4IGNORE file in a subdirectory for a particular module. You can even undo an ignore rule in a more specific P4IGNORE with an exclamation mark “!”. For example:

The P4IGNORE file in my home directory:

# Standard P4 stuff
.p4
.p4ignore

# prevent Mac OS from polluting my depots
.DS_Store
.project

# Avoid submitting joined Git repositories
.git
.gitignore

For a particular project I might decide to add the .gitignore file to my depots, so I place another .p4ignore file into the workspace root of the project with the following line:

# Override rule for .gitignore
!.gitignore

Git ignore syntax is fully supported

I can have a joined project that lives both on GitHub and the Perforce Workshop with a single .gitignore file. All I have to do is to set P4IGNORE=.gitignore in my P4CONFIG.

In fact, you can specify more than one filename in P4IGNORE. In reality, my P4IGNORE looks like this (this is a new feature in 2015.2):

P4IGNORE=$home/.p4ignore;.gitignore;.p4ignore;

I can list several file separated by semicolons and $home is also supported. Now my defaults are picked up, I can ignore Git-specific files in Perforce but keep all project specific ignores in a single Git-ignore file.

Easy verification of ignored files

All these different options and files can make it quite daunting to determine if and why a file is ignored, or, indeed, not. The P4 command line tool has picked up a new trick here in 2015.2 as well: p4 ignores. This command is built into the P4 client itself, so you do not need to upgrade your server to be able to access it.

p4 ignores by itself displays a mapping of all the ignore rules, which can be a bit daunting. I found the options “-i” and “-v” together with a list of file and directory names to be particularly useful. To find out why I do not seem to be able to add the file “Readme.md” to my project, I run the command:

p4 ignores –i –v Readme.md

and might get back this answer:

/Users/sknop/main/Readme.md ignored by /Users/sknop/main/.p4ignore:1:*.md

This tells me that all files ending in “.md” are ignored by the first line in my local .p4ignore file. As expected, a p4 add or p4 rec (the useful shortcut for p4 reconcile) will now not pick this file up:

/Users/sknop/main/Readme.md - ignored file can't be added.

If I remove the line from my .p4ignore file, I get this report instead:

/Users/sknop/main/Readme.md not ignored

Conclusion

Now you can ignore files and directories to your heart’s content, and only submit files you really wanted in your Helix server. Ignorance, it seems, can really be bliss.

Oh, and if you are using Perforce Helix 2015.1 or newer, try p4 add ... :)

As usual, contact me @p4sven if you have any questions or feedback. Happy hacking!