Specifying file revisions

Each time you submit a file to the depot, its revision number is incremented. To specify revisions prior to the most recent, use the # revision specifier to specify a revision number, or @ to specify a date, changelist, client workspace, or label corresponding to the version of the file you are working on. Revision specifications can be used to limit the effect of a command to specified file revisions.

Warning

Some operating system shells treat the Helix Server revision character # as a comment character if it starts a word. If your shell is one of these, escape the # when you use it in p4 commands.

The following table describes the various ways you can specify file revisions:

Revision needed	Syntax and example
Revision number	`file#n` $ p4 sync //JamCode/dev/jam/Jambase#3 Refers to revision 3 of file `Jambase`
The revision submitted as of a specified changelist	`file@changelist_number` $ p4 sync //JamCode/dev/jam/Jambase@126 Refers to the version of `Jambase` when changelist 126 was submitted, even if it was not part of the change. $ p4 sync //JamCode/dev/...@126 Refers to the state of the entire depot at changelist 126 (numbered changelists are explained in Submit a numbered changelist.
The revision in a specified label	`file@label_name` $ p4 sync //JamCode/dev/jam/Jambase@beta The revision of `Jambase` in the label called `beta`. For details about labels, refer to Labels.
The revision last synced to a specified client workspace	`file@client_name` $ p4 sync //JamCode/dev/jam/Jambase@bruno_ws The revision of `Jambase` last synced to client workspace `bruno_ws`.
Remove the file	`file#none` $ p4 sync //JamCode/dev/jam/Jambase#none Removes `Jambase` from the client workspace.
The most recent version of the file	`file#head` $ p4 sync //JamCode/dev/jam/Jambase#head Same as `p4 sync //JamCode/dev/jam/Jambase` (If you omit the revision specifier, the head revision is synced.)
The revision last synced to your workspace	`file#have` $ p4 files //JamCode/dev/jam/Jambase#have
The head revision of the file in the depot on the specified date	`file@date` $ p4 sync //JamCode/dev/jam/Jambase@2011/05/18 The head revision of `Jambase` as of midnight May 18, 2011.
The head revision of the file in the depot on the specified date at the specified time	`file@"date[:time]"` $ p4 sync //JamCode/dev/jam/Jambase@"2011/05/18" Specify dates in the format `YYYY/MM/DD`. Specify time in the format `HH`:`MM`:`SS` using the 24-hour clock. Time defaults to `00:00:00`. Separate the date and the time by a single space or a colon. (If you use a space to separate the date and time, you must also enclose the entire date-time specification in double quotes.)

Example Retrieving files using revision specifiers

Bruno wants to retrieve all revisions that existed at changelist number 30. He types:

$ p4 sync //JamCode/dev/jam/Jambase@30

Another user can sync their workspace so that it contains the same file revisions Bruno has synced by specifying Bruno’s workspace, as follows:

$ p4 sync @bruno_ws

Example Removing all files from the client workspace

$ p4 sync ...#none

The files are removed from the workspace but not from the depot.

Date and time specifications

Date and time specifications are obtained from the time zone of the computer that hosts the Helix Server. To display the date, time, offset from GMT, and time zone in effect, issue the p4 info command. The versioning service stores times as the number of seconds since 00:00:00 GMT Jan. 1, 1970), so if you move across time zones, the times stored in the service are correctly reported in the new time zone.

Revision ranges

Some commands can operate on a range of file revisions. To specify a revision range, specify the start and end revisions separated by a comma, for example, #3,4.

The commands that accept revision range specifications are:

p4 annotate p4 changes p4 dirs p4 filelog

p4 files p4 fixes p4 grep p4 integrate

p4 interchanges p4 jobs p4 labels p4 labelsync

p4 list p4 merge p4 print p4 sizes

p4 sync p4 tag

For the preceding commands:

If you specify a single revision, the command operates on revision #1 through the revision you specify (except for p4 sync, p4 print, and p4 files, which operate on the highest revision in the range).
If you omit the revision range entirely, the command affects all file revisions.

Example Listing changes using revision ranges

A release manager needs to see a quick list of all changes made to the jam project in July 2010. He types:

$ p4 changes //JamCode/dev/jam/...@2010/7/1,2010/8/1

The resulting list of changes looks like this:

Change 673 on 2010/07/31 by bruno@bruno_ws 'Final build for QA'
Change 633 on 2010/07/1 by bruno@bruno_ws 'First build w/bug fix'
Change 632 on 2010/07/1 by bruno@bruno_ws 'Started work'