p4 counter

Synopsis

Access, set, increment, or delete a persistent variable.

Syntax

p4 [g-opts] counter countername
p4 [g-opts] counter [-f -v] countername value
p4 [g-opts] counter [-f] -d countername
p4 [g-opts] counter [-f -v] -i countername
p4 [g-opts] counter [-f] -m [pair list]
p4 [g-opts] counter --from oldvalue --to newvalue countername

Description

Counters provide long-term variable storage for scripts that access Perforce. Counters can be assigned textual values as well as numeric ones.

The command includes the following variants:

  • The variant p4 counter countername returns the value of variable countername.

    If a counter does not exist, its value is returned as zero; counter names are not stored in the database until set to a nonzero value.

  • The variant p4 counter countername value sets the value of variable countername to value. If countername does not already exist, it is created.
  • The variant p4 counter -d countername deletes the counter countername. This has the same effect as setting the counter to zero.
  • The variant p4 counter -i countername increments the counter by one and returns the new value. Use this option instead of a value argument.
  • The variant p4 counter -m pair list defines multiple operations to be performed. Each operation is defined by a value pair in the pair list. To set a counter use a name and value; to delete a counter use a - (hyphen) followed by the name. See Examples.

    This variant is useful in distributed environments where running individual commands is likely to introduce unwanted latency.

  • The final variant (--from …​ --to) sets the specified counter to the new value only if the current value of the counter is oldvalue. A counter that has never been set or that has been deleted cannot be set using this syntax variant.

    This variant effectively provides a compare-and-set function that can be used as a building block for higher-level tools and process that use counters.

Perforce uses a number of counters in the course of its regular operations. These might be useful to various tools. For example, review tools can keep track of which changes have been reviewed and which changes are still under review by writing such status information into counters.

See the p4 counters command for a list of Perforce counters. Superusers can use the -f option to force changes to these counters. Changes to these counters are not without risk; see the Release Notes for examples of the types of situations in which manually resetting these counters might be appropriate.

The last changelist number known to the Perforce service (the output of p4 counter change) includes pending changelists created by users, but not yet submitted to the depot. It can be useful to know the changelist number of the last submitted changelist, which is the second field of the output of the command:

$ p4 changes -m 1 -s submitted

The last changelist number successfully submitted (that is, no longer pending) to the Perforce service is held in the maxCommitChange counter.

Options

-d countername

Delete variable countername.

-i countername

Increment variable countername by 1 and return the new value. This option can only be used with numeric counters.

-f

Set or delete counters that are reserved for use by Perforce (listed in p4 help counters).

Never set the change counter to a value that is lower than its current value.

Only operators or super users can use this flag.

-m pair list

Specify a list of operations to be performed. Each operation is defined by a value pair in the pair list. To set a counter, use a name and value; to delete a counter use a - (hyphen) followed by the name. See Examples.

-v

Display the previous value of the specified counter after the counter has been set or incremented.

g-opts

See “Global Options”.

Usage Notes

Can File Arguments Use Revision Specifier? Can File Arguments Use Revision Range? Minimal Access Level Required

N/A

N/A

list to display a counter’s value
review to set a new value
super to use the -f option

Examples

p4 counter mycounter 123

Set the value of a counter mycounter to 123. If mycounter does not exist, it is created.

Requires review access.

p4 counter mycounter

Display the value of mycounter. If mycounter does not exist, its value is displayed as 0.

Requires list access.

p4 counter -m firstcounter 5 secondcounter 4

Set two counters.

p4 counter -m - xset - yset

Delete two counters.

p4 counter -m firstcounter 6 - secondcounter

Set one counter; delete one counter.

Related Commands

To configure the versioning service

p4 configure

To list all configurables and their values

p4 configure show

To list all counters and their values

p4 counters

List and track changelists

p4 review

List users who have subscribed to particular files

p4 reviews