July 30, 2013

Power User Tip - Properties, Counters, and Attributes

Traceability
Version Control

Many Perforce power users and administrators know about counters and attributes already. These are two mechanisms for storing extra metadata in Perforce. The 2013.1 release adds some new power for storing extra metadata, so it's worth reviewing why and how you would use these storage mechanisms.

The story starts with counters. These are simple name-value pairs stored in Perforce's database. The original use was for system data like the value of the next pending changelist and the system security level. You can also store extra data in there, like the value of the last changelist a review daemon has processed. Counters aren't associated with files and have very limited access control: any user can see the value of a counter, and you only need review a changelist to update a counter. (That harks back to the use for review daemons.)

> p4 counter nextChangeToBuild 230
    Counter nextChangeToBuild set. 
> p4 counter nextChangeToBuild
    230

Next we have attributes. Attributes have been around a while as an undocumented part of Perforce, but are now fully visible. Attributes are used to store arbitrary key-value pairs on files. They are protected by the same access control as the file they apply to, and can be propagated and merged across revisions. They're very useful for creating some workflow around files or building custom applications on top of Perforce.

> p4 attribute -f -n ReviewedBy -v JoeCoder variable.c
     //streams/main/src/variable.c#1 - ReviewedBy set
> p4 fstat -T "attr-ReviewedBy" -Oa variable.c
... attr-ReviewedBy JoeCoder

And now in the 2013.1 release, we have properties. Properties are extra key-value pairs that are not attached to a file, like counters. Properties can also use simple access control, with visibility limited to specific users or groups. As a very trivial example, you could set a property telling different groups of users which stable branch to work from. A more exciting idea is the ability to centrally store application settings that apply to programs like P4V. (More to come on the later.)

> p4 property -a -n BranchToUse -v devBranch -g Dev.G      # tell Dev team to use
development branch
> p4 property -a -n BranchToUse -v intBranch -g QA.G       # tell QA team to use
integration branch 

> p4 -u JoeCoder property -l -n BranchToUse                # Developer sees devBranch
    BranchToUse = devBranch (group Dev.G) 
> p4 -u AnnTester property -l -n BranchToUse               # QA team sees intBranch 
    BranchToUse = intBranch (group QA.G)

If properties look useful to you, check out the 2013.1 release note and give them a try. You'll probably be surprised at how useful they are.