Basic tasks

This chapter describes tasks you commonly perform when setting up and using your version control system. It discusses both tasks you perform just once when getting your system set up, and tasks you may perform one or more times during the lifetime of your installation.

Overview of initial tasks

This section gives you an overview of the tasks for setting up your command client and shared server. The tasks in this workflow should be performed once, and in the order presented in the following table:

Step	Task	Stream or classic user	Link
1	Create a working directory	Both	Create a working directory
2	Log in to the shared server or start up a shared server	Both	Log in to the shared server or Start up a shared server
3	Start up the command line client and verify the connection to the server	Both	Start up the command line client and verify the connection to the server
4	Create a stream depot	Stream	Create a stream depot
5	Create a mainline stream	Stream. Classic users, see Organizing the depot.	Create a mainline stream
6	Define a workspace	Both	Define a workspace and bind it to the stream
7	Bind the workspace to the stream	Stream	Define a workspace and bind it to the stream
8	Populate the mainline stream	Stream. Classic users populate a codeline.	Populate the mainline stream

Overview of recurring tasks

This section gives you an overview of the tasks you perform during the lifetime of your installation, divided between file-level tasks and other tasks. You may perform them one or more times, or never.

The following table summarizes file-level recurring tasks:

Task	Stream or classic user	Link
Sync files from the depot	Both	Sync files
Edit files	Both	Edit files and check in changes
Rename and move files	Both	Rename and move files
Diff files	Both	Diff files
Revert files	Both	Revert files, to discard changes
Add files	Both	Add files
Delete files	Both	Delete files
Resolve conflicts	Both	“Resolve conflicts”

The following table summarizes other recurring tasks:

Task	Stream or classic user	Link
Work with changelists	Both	Changelist-related tasks
Configure client behavior	Both	“Configure clients”
Configure stream behavior	Stream	Configure a stream
Branch and populate child streams	Stream	Branch and populate child streams
Propagate changes between streams	Stream	Propagate changes

Initial tasks

You perform the tasks in this section once, in the order presented.

Create a working directory

Create a working directory and then change to the directory. In this example, we create a working directory called work in the user’s home directory.

$ mkdir /Users/bruno/work
$ cd /Users/bruno/work

Log in to the shared server

Typically, your administrator starts up a shared server for you. If you need to start up your own shared server, see Start up a shared server.

Your admin provides you with a user id, a password, and the server’s address. You then follow these steps:

Set the P4PORT environment variable to the server address the admin gave you.

The server is running on as server1 on port 1666. For the client to communicate with the server, you must set the client’s P4PORT variable to server1:1666.

On UNIX and OSX
```
$ export P4PORT=server1:1666
```
On Windows
```
$ set P4PORT=server1:1666
```
Log in to the server with the p4 login command
```
$ p4 login
```

Helix displays the following:

Enter password:

Enter the password your admin gave you.

Helix displays the following:

User bruno logged in.

Start up a shared server

Download into your computer’s /usr/local/bin directory the server (p4d) and client (p4) binaries, as described in “Installation”. Then, follow these steps:

Make the server and client binaries executable, if they’re not already
```
$ chmod +x /usr/local/bin/p4d
$ chmod +x /usr/local/bin/p4
```
Make a subdirectory in which to start up the server and client.

When started, the server creates a large number of database files; it’s best not to clutter your working directory with these files, so we will start up the server and client in a different directory, in this case /Users/bruno/server.
```
$ mkdir /Users/bruno/server
```
Start up the shared server.

Start up the shared server, using the -r dir option to specify the directory created in the previous step.
```
$ p4d -r /Users/bruno/server
```

This produces the following output:

Perforce db files in 'server' will be created if missing...
Perforce Server starting...

Start up the command line client and verify the connection to the server

Start up the command line client.
```
$ p4
```

To verify a connection, issue the p4 info command. If P4PORT is set correctly, information like the following is displayed:

User name: bruno
Client name: bruno_ws
Client host: computer_12
Client root: c:\bruno_ws
Current directory: c:\bruno_ws
Peer address; 10.0.102.24:61122
Client address: 10.0.0.196
Server address: ssl:example.com:1818
Server root: /usr/depot/p4d
Server date: 2012/03/28 15:03:05 -0700 PDT
Server uptime: 752:41:33
Server version: P4D/FREEBSD/2012.1/406375 (2012/01/25)
ServerID: Master
Server license: P4Admin <p4adm> 20 users (expires 2015/01/01)
Server license-ip: 10.0.0.2
Case handling: sensitive

The Server address: field shows the host to which p4 connected and also displays the host and port number on which the Helix server is listening. If P4PORT is set incorrectly, you receive a message like the following:

Perforce client error:
   Connect to server failed; check $P4PORT.
   TCP connect to perforce:1666 failed.
   perforce: host unknown.

If the value you see in the third line of the error message is perforce:1666 (as above), P4PORT has not been set. Set P4PORT and try to connect again.

If your installation requires SSL, make sure your P4PORT is of the form ssl:hostname:port.

You will be asked to verify the server’s fingerprint the first time you attempt to connect to the server. If the fingerprint is accurate, use the p4 trust command to install the fingerprint into a file (pointed to by the P4TRUST environment variable) that holds a list of known/trusted Helix servers and their respective fingerprints. If P4TRUST is unset, this file is .p4trust in the user’s home directory. For more information, see SSL-encrypted connections.

If your installation requires plain text (in order to support older Helix applications), set P4PORT to tcp:hostname:port.

Create a stream depot

Typically your administrator will create a stream depot for you and provide you with the depot name.

However, if you are creating a stream depot yourself, type the following:

$ p4 depot -t stream depotname

The -t option specifies the type of depot to create, in this case a stream depot.

Helix opens the depot specification in an editor:

# A Perforce Depot Specification.
#
#  Depot:       The name of the depot.
#  Owner:       The user who created this depot.
#  Date:        The date this specification was last modified.
#  Description: A short description of the depot (optional).
#  Type:        Whether the depot is 'local', 'remote',
#               'stream', 'spec', 'archive', 'tangent',
#               or 'unload'.  Default is 'local'.
#  Address:     Connection address (remote depots only).
#  Suffix:      Suffix for all saved specs (spec depot only).
#  StreamDepth: Depth for streams in this depot (stream depots only).
#  Map:         Path translation information (must have ... in it).
#  SpecMap:     For spec depot, which specs should be recorded (optional).
#
# Use 'p4 help depot' to see more about depot forms.

Depot:          JamCode

Owner:          bruno

Date:           2016/02/22 13:20:06

Description:
                Created by bruno.

Type:           stream

StreamDepth:    //JamCode/1

Map:            JamCode/...

Adjust the value of other fields as desired and save the specification.

Create a mainline stream

To create a mainline stream:

Issue the p4 stream, command, specifying the depot followed by the stream name.

For example:
```
$ p4  stream -t mainline //JamCode/main
```
The stream specification form is displayed.
Change options in the spec to assign the stream the desired characteristics and save the spec. See Configure a stream for details on the stream spec.
To verify that your mainline stream has been created, issue the p4 streams command.

For example:
```
$ p4  streams //projectX/...
```

Define a workspace and bind it to the stream

Before you can work in a stream, you must define a workspace associated with the stream. When you associate a workspace with a stream, Helix generates the workspace view based on the structure of the stream. Stream users never need edit the workspace view (and, in fact, cannot manually alter it). If the structure of the stream changes, Helix updates the views of workspaces associated with the stream on an as-needed basis.

Note

Classic Helix users define a workspace by issuing the p4 client command without passing the -S option, and edit the workspace view manually by editing the View: field in the client spec. See Configure workspace views.

Your Helix administrator may already have configured a client workspace for your computer. If so, the Client field in the client spec - displayed when you issue the p4 client command — contains this name.

If not, to create a workspace for a stream:

Issue the p4 client command, using the -S option to specify the name of the associated stream.

For example:
```
$ p4 client -S //JamCode/main
```
The workspace specification form is displayed.
Configure the workspace root directory and any other desired settings, and save the specification. See Define a client workspace for details.
Verify that your workspace has been created using p4 clients.

For example:
```
$ p4 clients -S //JamCode/main
```

Now you can populate the mainline with files, as described in the next step.

Populate the mainline stream

Note

Classic users populate a branch. See “Codeline management”.

There are two ways to populate a mainline stream:

Add files from the local filesystem. This is the most typical way.
Branch files from another depot. This way only applies if you have existing "classic" Helix depots.

If you need to preserve file history, branch the source files to the mainline stream. If you have no requirement for preserving file history, simply add them. The sections that follow describe each approach.

Add files

If you do not need to preserve file history, simply add the files. To add files to the mainline stream:

Create the workspace root directory if it does not exist.

For example:

C:\bruno_ws> cd C:\Users\bruno\p4clients
C:\Users\bruno\p4clients> mkdir bruno_projectX_main

Copy the files and folders to the workspace root directory.
Change into the client workspace root directory, and use the p4 reconcile command to detect files not under Helix control and open them for add.
```
C:\Users\bruno\p4clients> cd bruno_projectX_main
C:\Users\bruno\p4clients\bruno_projectX_main> p4 add ...
```

To verify that the files are set up to be added correctly, issue the p4 opened command. To populate the stream, submit the changelist in which the files are open.

For details on working with changelists, see Changelist-related tasks.

Branch from other depots

You can branch files from other stream depots, classic depots, or remote depots into a stream. If you populate the mainline by branching, Helix preserves the connection between the revision history of the source and target files. Your workspace must be set to one associated with the target stream (example: p4 set P4CLIENT=bruno_projectX_main).

To populate the mainline by branching, issue the p4 copy command, specifying source and target. Example:

$ p4 copy -v //mysourcedepot/mainline/... //ProjectX/main/...

In this example the -v option performs the copy on the server without syncing the newly-created files to the workspace. This can be a significant time-saver if there are many files being copied; you can then sync only the files you intend to work with from the new location.

p4d displays a series of “import from” messages listing the source and target files, and opens the file(s) in a pending changelist. To preview the results of the operation without opening files, specify the -n option.

To populate the stream with the files from the mainline, issue the following commands:

To verify that the files are set up to be added correctly, issue the p4 opened command.
To populate the stream, p4 submit the changelist in which the files are open.

If you are populating an empty stream, you can simplify this process by using p4 populate. For example:

$ p4 populate //mysourcedepot/mainline/...  //ProjectX/main/...

does the same thing as p4 copy -v followed by a p4 submit. If you are unsure of the results of p4 populate, use p4 populate -n, which previews the result of the command.

To undo an erroneous copy operation, issue the p4 revert command; for example:

$ p4 revert //ProjectX/main/...

Recurring file-level tasks

This section describes tasks you perform during the lifetime of your installation that occur at the file level.

Before we look at the tasks in detail, here’s a table that provides a snapshot of the sequence in which you perform the most common file-related tasks.

For details on working with changelists, see Changelist-related tasks.

Here are the basic steps for working with files. In general, to change files in the depot (file repository), you open the files in changelists and submit the changelists with a description of your changes. Helix assigns numbers to changelists and maintains the revision history of your files. This approach enables you to group related changes and find out who changed a file and why and when it was changed.

Task Description

Syncing (retrieving files from the depot)

Issue the p4 sync command, specifying the files and directories you want to retrieve from the depot. You can only sync files that are mapped in your client workspace view.

Add files to the depot

Create the file in the workspace.
Open the file for add in a changelist (p4 add).
Submit the changelist (p4 submit).

Edit files and check in changes

If necessary, sync the desired file revision to your workspace (p4 sync).
Open the file for edit in a changelist (p4 edit).
Make your changes.
Submit the changelist (p4 submit). To discard changes, issue the p4 revert command.

Delete files from the depot

Open the file for delete in a changelist (p4 delete). The file is deleted from your workspace.
Submit the changelist (p4 submit). The file is deleted from the depot.

Discard changes

Revert the files or the changelist in which the files are open. Reverting has the following effects on open files:

Add	no effect - the file remains in your workspace.
Edit	the revision you opened is resynced from the depot, overwriting any changes you made to the file in your workspace.
Delete	the file is resynced to your workspace.

Files are added to, deleted from, or updated in the depot only when you successfully submit the pending changelist in which the files are open. A changelist can contain a mixture of files open for add, edit and delete.

For details on working with changelists, see Changelist-related tasks.

Sync files

Syncing — with the p4 sync command — adds, updates, or deletes files in the client workspace to bring the workspace contents into agreement with the depot. If a file exists within a particular subdirectory in the depot, but that directory does not exist in the client workspace, the directory is created in the client workspace when you sync the file. If a file has been deleted from the depot, p4 sync deletes it from the client workspace.

Example 1. Sync files from the depot to a client workspace.

The command below retrieves the most recent revisions of all files in the client view from the depot into the workspace. As files are synced, they are listed in the command output.

C:\bruno_ws> p4 sync
//Acme/dev/bin/bin.linux24x86/readme.txt#1 - added as c:\bruno_ws\dev\bin\bin.linux24x86\readme.txt
//Acme/dev/bin/bin.ntx86/glut32.dll#1 - added as c:\bruno_ws\dev\bin\bin.ntx86\glut32.dll
//Acme/dev//bin/bin.ntx86/jamgraph.exe#2 - added as c:\bruno_ws\dev\bin\bin.ntx86\jamgraph.exe
[...]

Note

You cannot sync files that are not in your workspace view. See Configure workspace views for more information.

To sync revisions of files prior to the latest revision in the depot, use revision specifiers. For example, to sync the first revision of Jamfile, which has multiple revisions, issue the following command:

$ p4 sync //Acme/dev/jam/Jamfile#1

To sync groups of files or entire directories, use wildcards. For example, to sync everything in and below the jam folder, issue the following command:

$ p4 sync //Acme/dev/jam/...

The Helix server tracks which revisions you have synced. For maximum efficiency, Helix does not re-sync an already-synced file revision. To re-sync files you (perhaps inadvertently) deleted manually, specify the -f option when you issue the p4 sync command.

Add files

To add files to the depot, create the files in your workspace, then issue the p4 add command. The p4 add command opens the files for add in the default pending changelist. The files are added when you successfully submit the default pending changelist. You can open multiple files for add using a single p4 add command by using wildcards. You cannot use the Helix ... wildcard to add files recursively.

To add files recursively, use the p4 reconcile command. See p4 reconcile in the P4 Command Reference.

Example 2. Add files

Bruno has created a couple of text files that he must add to the depot. To add all the text files at once, he uses the * wildcard when he issues the p4 add command.

C:\bruno_ws\Acme\dev\docs\manuals> p4 add *.txt
//Acme/dev/docs/manuals/installnotes.txt#1 - opened for add
//Acme/dev/docs/manuals/requirements.txt#1 - opened for add

Now the files he wants to add to the depot are open in his default changelist. The files are stored in the depot when the changelist is submitted.

Example 3. Submit a changelist to the depot.

Bruno is ready to add his files to the depot. He types p4 submit and sees the following form in a standard text editor:

Change: new
Client: bruno_ws
User:   bruno
Status: new
Description:
        <enter description here>
Type:   public
Files:
    //Acme/dev/docs/manuals/installnotes.txt   # add
    //Acme/dev/docs/manuals/requirements.txt   # add

Bruno changes the contents of the Description: field to describe his file updates. When he’s done, he saves the form and exits the editor, and the new files are added to the depot.

You must enter a description in the Description: field. You can delete lines from the Files: field. Any files deleted from this list are moved to the next default changelist, and are listed the next time you submit the default changelist.

If you are adding a file to a directory that does not exist in the depot, the depot directory is created when you successfully submit the changelist.

For details on working with changelists, see Changelist-related tasks.

Add files outside of Helix and then use p4 reconcile -k

In certain situations, you may need to copy a very large number of files into your workspace from another user’s workspace. Rather than doing this via Helix, you may, for performance reasons, choose to copy them directly — via a snapshot, for example — from the other user’s workspace into yours.

Once you’ve done this, you will need to:

Inform Helix that these files now exist on your client.

That is, you want to update your client’s have list to reflect the actual contents of your workspace. See the p4 have page in P4 Command Reference for details on have lists.
Ensure that your workspace view contains mappings identical to those contained in the workspace view of the client you copied from

This ensures that Helix doesn’t think these files are new.

To do this, run the p4 reconcile -k command.

You can also ignore groups of files when adding. See Ignoring groups of files when adding for details.

Edit files and check in changes

You must open a file for edit before you attempt to edit the file. When you open a file for edit — with the p4 edit command — Helix enables write permission for the file in your workspace and adds the files to a changelist. If the file is in the depot but not in your workspace, you must sync it before you open it for edit.

Example 4. Open a file for edit.

Bruno wants to make changes to command.c, so he syncs it and opens the file for edit.

C:\bruno_ws\dev> p4 sync //Acme/dev/command.c
//depot/dev/command.c#8 - added as c:\bruno_ws\dev\command.c

C:\bruno_ws\dev> p4 edit //Acme/dev/command.c
//Acme/dev/command.c#8 - opened for edit

He then edits the file with any text editor. When he’s finished, he submits the file to the depot with p4 submit.

Delete files

To delete files from the depot, you open them for delete by issuing the p4 delete command, then submit the changelist in which they are open. When you delete a file from the depot, previous revisions remain, and a new head revision is added, marked as “deleted.” You can still sync previous revisions of the file.

When you issue the p4 delete command, the files are deleted from your workspace but not from the depot. If you revert files that are open for delete, they are restored to your workspace. When you successfully submit the changelist in which they are open, the files are deleted from the depot.

Example 5. Delete a file from the depot.

Bruno deletes vendor.doc from the depot as follows:

C:\bruno_ws\dev> p4 delete //Acme/dev/docs/manuals/vendor.doc
//Acme/dev/docs/manuals/vendor.doc#1 - opened for delete

The file is deleted from the client workspace immediately, but it is not deleted from the depot until he issues the p4 submit command.

Revert files, to discard changes

To remove an open file from a changelist and discard any changes you made, issue the p4 revert command. When you revert a file, Helix restores the last version you synced to your workspace. If you revert a file that is open for add, the file is removed from the changelist but is not deleted from your workspace.

Example 6. Revert a file

Bruno decides not to add his text files after all.

C:\bruno_ws\dev> p4 revert *.txt
//Acme/dev/docs/manuals/installnotes.txt#none - was add, abandoned
//Acme/dev/docs/manuals/requirements.txt#none - was add, abandoned

To preview the results of a revert operation without actually reverting files, specify the -n option when you issue the p4 revert command.

Rename and move files

To rename or move files, you must first open them for add or edit, and then use the p4 move command:

C:\bruno_ws> p4 move source_file target_file

To move groups of files, use matching wildcards in the source_file and target_file specifiers. To move files, you must have Helix write permission for the specified files. For information about using wildcards with Helix files, see Helix wildcards.

For details about Helix permissions, see the Helix Versioning Engine Administrator Guide: Fundamentals.

When you rename or move a file using p4 move, the versioning service creates an integration record that links it to its deleted predecessor, preserving the file’s history. Integration is also used to create branches and to propagate changes.

Diff files

Helix allows you to diff (compare) revisions of text files. By diffing files, you can display:

Changes that you made after opening the file for edit
Differences between any two revisions
Differences between file revisions in different branches

To diff a file that is synced to your workspace with a depot revision, issue the p4 diff filename#rev command. If you omit the revision specifier, the file in your workspace is compared with the revision you last synced, to display changes you made after syncing it.

To diff two revisions that reside in the depot but not in your workspace, use the p4 diff2 command. To diff a set of files, specify wildcards in the filename argument when you issue the p4 diff2 command.

The p4 diff command performs the comparison on your computer, but the p4 diff2 command instructs the Helix server to perform the diff and to send the results to you.

The following table lists some common uses for diff commands:

To diff	Against	Use this command
The workspace file	The head revision	`p4 diff file` or `p4 diff file#head`
The workspace file	Revision 3	`p4 diff file#3`
The head revision	Revision 134	`p4 diff2 file file#134`
File revision at changelist 32	File revision at changelist 177	`p4 diff2 file@32 file@177`
The workspace file	A file shelved in pending changelist 123	`p4 diff file@=123`
All files in release 1	All files in release 2	p4 diff2 //Acme/rel1/... //Acme/rel2/...

By default, the p4 diff command launches Helix’s internal diff application. To use a different diff program, set the P4DIFF environment variable to specify the path and executable of the desired application. To specify arguments for the external diff application, use the -d option. For details, refer to the P4 Command Reference.

Resolve conflicts

When you and other users are working on the same set of files, conflicts can occur. Helix enables your team to work on the same files simultaneously and resolve any conflicts that arise.

“Resolve conflicts” explains in detail how to resolve file conflicts.

Other recurring tasks

This section describes other basic tasks you perform during the lifetime of your installation.

Changelist-related tasks

This section explains how to work with changelists.

To change files in the depot, you open them in a changelist, make any changes to the files, and then submit the changelist. A changelist contains a list of files, their revision numbers, and the operations to be performed on the files. Unsubmitted changelists are referred to as pending changelists.

Submission of changelists is an all-or-nothing operation; that is, either all of the files in the changelist are updated in the depot, or, if an error occurs, none of them are. This approach guarantees that code alterations that affect multiple files occur simultaneously.

Helix assigns numbers to changelists and also maintains a default changelist, which is numbered when you submit it. You can create multiple changelists to organize your work. For example, one changelist might contain files that are changed to implement a new feature, and another changelist might contain a bug fix. When you open a file, it is placed in the default changelist unless you specify an existing changelist number on the command line using the -c option. For example, to edit a file and submit it in changelist number 4, use p4 edit -c 4 filename. To open a file in the default changelist, omit the -c option.

You can also shelve changelists in order to temporarily preserve work in progress for your own use, or for review by others. Shelving enables you to temporarily cache files in the shared server without formally submitting them to the depot.

The Helix server might renumber a changelist when you submit it, depending on other users' activities; if your changelist is renumbered, its original number is never reassigned to another changelist.

You can restrict a changelist from public view by changing the Type: field from public to restricted. In general, if a changelist is restricted, only those users with list access to at least one of the files in the changelist are permitted to see the changelist description.

To control what happens to files in a changelist when you submit the changelist to the depot, see Configure submit options.

Submit a pending changelist

To submit a pending changelist, issue the p4 submit command. When you issue the p4 submit command, a form is displayed, listing the files in the changelist. You can remove files from this list. The files you remove remain open in the default pending changelist until you submit them or revert them.

To submit specific files that are open in the default changelist, issue the p4 submit filename command. To specify groups of files, use wildcards. For example, to submit all text files open in the default changelist, type p4 submit "*".txt. (Use quotation marks as an escape code around the * wildcard to prevent it from being interpreted by the local command shell).

After you save the changelist form and exit the text editor, the changelist is submitted to the Helix server, and the files in the depot are updated. After a changelist has been successfully submitted, only a Helix administrator can change it, and the only fields that can be changed are the description and user name.

If an error occurs when you submit the default changelist, Helix creates a numbered changelist containing the files you attempted to submit. You must then fix the problems and submit the numbered changelist using the -c option.

Helix enables write permission for files that you open for edit and disables write permission when you successfully submit the changelist containing the files. To prevent conflicts with Helix’s management of your workspace, do not change file write permissions manually.

Before committing a changelist, p4 submit briefly locks all files being submitted. If any file cannot be locked or submitted, the files are left open in a numbered pending changelist. By default, the files in a failed submit operation are left locked unless the submit.unlocklocked configurable is set. Files are unlocked even if they were manually locked prior to submit if submit fails when submit.unlocklocked is set.

Create numbered changelists

To create a numbered changelist, issue the p4 change command. This command displays the changelist form. Enter a description and make any desired changes; then save the form and exit the editor.

All files open in the default changelist are moved to the new changelist. When you exit the text editor, the changelist is assigned a number. If you delete files from this changelist, the files are moved back to the default changelist.

Example 7. Working with multiple changelists.

Bruno is fixing two different bugs, and needs to submit each fix in a separate changelist. He syncs the head revisions of the files for the first fix and opens the file for edit in the default changelist:

C:\bruno_ws> p4 sync //JamCode/dev/jam/*.c
[list of files synced...]

C:\bruno_ws> p4 edit //JamCode/dev/jam/*.c
[list of files opened for edit...]

Now he issues the p4 change command and enters a description in the changelist form. After he saves the file and exits the editor, Helix creates a numbered changelist containing the files.

C:\bruno_ws\dev\main\docs\manuals> p4 change

    [Enter description and save form]

Change 777 created with 33 open file(s).

For the second bug fix, he performs the same steps, p4 sync, p4 edit, and p4 change. Now he has two numbered changelists, one for each fix.

The numbers assigned to submitted changelists reflect the order in which the changelists were submitted. When a changelist is submitted, Helix might renumber it, as shown in the following example:

Example 8. Automatic renumbering of changelists

Bruno has finished fixing the bug that he’s been using changelist 777 for. After he created that changelist, he submitted another changelist, and two other users also submitted changelists. Bruno submits changelist 777 with p4 submit -c 777, and sees the following message:

Change 777 renamed change 783 and submitted.

Submit a numbered changelist

To submit a numbered changelist, specify the -c option when you issue the p4 submit command. To submit the default changelist, omit the -c option. For details, refer to the p4 submit command description in the P4 Command Reference.

Note

Using parallel submits can significantly improve performance. For additional information see the description of the p4 submit command in the P4 Command Reference.

Undo a submitted change

One of the fundamental benefits of version control is the ability to undo an unwanted change, either to undo the effects of a bad changelist or to roll back to a known good changelist.

You use the p4 undo command to accomplish this. For details, refer to the p4 undo command description in the P4 Command Reference.

Shelve changelists

The Helix shelving feature enables you to temporarily make copies of your files available to other users without checking the changelist into the depot.

Shelving is useful for individual developers who are switching between tasks or performing cross-platform testing before checking in their changes. Shelving also enables teams to easily hand off changes and to perform code reviews.

Example 9. Shelving a changelist.

Earl has made changes to command.c on a UNIX platform, and now wants others to be able to view and test his changes.

$ p4 edit //Acme/dev/command.c
//Acme/dev/command.c#9 - opened for edit
...

$ p4 shelve
Change 123 created with 1 open file(s).
Shelving files for change 123.
edit //Acme/dev/command.c#9
Change 123 files shelved.

A pending changelist is created, and the shelved version of command.c is stored in the server. The file command.c remains editable in Earl’s workspace, and Earl can continue to work on the file, or can revert his changes and work on something else.

Shelved files remain open in the changelist from which they were shelved. (To add a file to an existing shelved changelist, you must first open that file in that specific changelist.) You can continue to work on the files in your workspace without affecting the shelved files. Shelved files can be synced to other workspaces, including workspaces owned by other users. For example:

Example 10. Unshelving a changelist for code review

Earl has asked for code review and a cross-platform compatibility check on the version of command.c that he shelved in changelist 123. Bruno, who is using a Windows computer, types:

C:\bruno_ws\dev> p4 unshelve -s 123 //Acme/dev/command.c
//Acme/dev/command.c#9 - unshelved, opened for edit

and conducts the test in the Windows environment while Earl continues on with other work.

When you shelve a file, the version on the shelf is unaffected by commands that you perform in your own workspace, even if you revert the file to work on something else.

Example 11. Handing off files to other users.

Earl’s version of command.c works on UNIX, but Bruno’s cross-platform check of command.c has revealed a bug. Bruno can take over the work from here, so Earl reverts his workspace and works on something else:

$ p4 revert //Acme/dev/command.c
//Acme/dev/command.c#9 - was edit, reverted

The shelved version of command.c is still available from Earl’s pending changelist 123, and Bruno opens it in a new changelist, changelist 124.

$ p4 unshelve -s 123 -c 124 //Acme/dev/command.c
//Acme/dev/command.c#9 - unshelved, opened for edit

When Bruno is finished with the work, he can either re-shelve the file (in his own changelist 124, not Earl’s changelist 123) for further review — with the p4 reshelve command — or discard the shelved file and submit the version in his workspace by using p4 submit.

The p4 submit command has a -e option that enables the submitting of shelved files directly from a changelist. All files in the shelved change must be up to date and resolved. Other restrictions can apply in the case of files shelved to stream targets; see the P4 Command Reference for details. (To avoid dealing with these restrictions, you can always move the shelved files into a new pending changelist before submitting that changelist.)

Example 12. Discarding shelved files before submitting a change.

The Windows cross-platform changes are complete, and changelist 124 is ready to be submitted. Bruno uses p4 shelve -d to discard the shelved files.

C:\bruno_ws\dev> p4 shelve -d -c 124
Shelve 124 deleted.

All files in the shelved changelist are deleted. Bruno can now submit the changelist.

C:\bruno_ws\dev> p4 submit -c 124
Change 124 submitted.

Bruno could have shelved the file in changelist 124, and let Earl unshelve it back into his original changelist 123 to complete the check-in.

Display information about changelists

To display brief information about changelists, use the p4 changes command. To display full information, use the p4 describe command. The following table describes some useful reporting commands and options:

Command	Description
`p4 changes`	Displays a list of all pending, submitted, and shelved changelists, one line per changelist, and an abbreviated description.
`p4 changes -m count`	Limits the number of changelists reported on to the last specified number of changelists.
`p4 changes -s status`	Limits the list to those changelists with a particular status; for example, `p4 changes -s submitted` lists only already submitted changelists.
`p4 changes -u user`	Limits the list to those changelists submitted by a particular user.
`p4 changes -c workspace`	Limits the list to those changelists submitted from a particular client workspace.
`p4 describe changenum`	Displays full information about a single changelist. If the changelist has already been submitted, the report includes a list of affected files and the diffs of these files. (You can use the `-s` option to exclude the file diffs.)
`p4 describe -O changenum`	If a changelist was renumbered, describe the changelist in terms of its original change number. (For example, the changelist renumbered in the example on Example 8, “Automatic renumbering of changelists” can be retrieved with either `p4 describe 783` or `p4 describe -O 777`.)

For more information, see Changelist reporting.

Move files between changelists

To move files from one changelist to another, issue the p4 reopen -c changenum filenames command, where changenum specifies the number of the target changelist. If you are moving files to the default changelist, use p4 reopen -c default filenames.

Delete changelists

To delete a pending changelist, you must first remove all files and jobs associated with it and then issue the p4 change -d changenum command. Related operations include the following:

To move files to another changelist, issue the p4 reopen -c changenum command.
To remove files from the changelist and discard any changes, issue the p4 revert -c changenum command.

Changelists that have already been submitted can be deleted only by a Helix administrator. See the Helix Versioning Engine Administrator Guide: Fundamentals for more information.

Configure client behavior

You can configure many aspects of the behavior of both the client workspace and the client binary running on your computer.

“Configure clients” discusses client configuration in detail.

Configure stream behavior

You can configure a stream’s characteristics — such as its location, its type, and the files in its view, among other things.

Configure a stream discusses stream configuration in detail.

Branch and populate child streams

After populating the mainline — as described in Populate the mainline stream — you can branch files for development and for release. For example, to create a development stream that is a clone of its mainline parent, issue the following command:

$ p4 stream -t development -P //Acme/main //Acme/dev

Helix displays the stream specification with the type set to development. Save the specification. To populate the stream with the files from the mainline, issue the following commands:

$ p4 populate -d "From main" -S //Acme/dev -r
$ p4 sync

Propagate changes

Streams enable you to isolate stable code from work in progress, and to work concurrently on various projects without impediment. Best practice is to periodically update less stable streams from streams that are more stable (by merging), then promote changes to the more stable stream (by copying). Merging and copying are streamlined forms of integration. In general, propagate change as follows:

For copying and branching, use p4 copy or p4 populate.
For merging, use p4 merge.
For edge cases not addressed by p4 merge or p4 copy, use p4 integrate.

The preceding guidelines apply to classic Helix as well.

Merge changes from a more stable stream

To update a stream with changes from a more stable stream, issue the p4 merge -S source-stream command, resolve as required, and submit the resulting changelist. By default, you cannot copy changes to a more stable stream until you have merged any incoming changes from the intended target. This practice ensures that you do not inadvertently overwrite any of the contents of the more stable stream.

Assuming changes have been checked into the mainline after you started working in the development stream (and assuming your workspace is set to a development stream), you can incorporate the changes into the development stream by issuing the following commands:

$ p4 merge
$ p4 resolve
$ p4 submit -d "Merged latest changes"

Copy changes to a more stable stream

After merging, your stream is up to date with its more stable parent or child. Assuming you’ve finalized the changes you want to make in the development stream, you can now promote its new content with no danger of overwriting work in the target stream. The copy operation simply propagates a duplicate of the source to the target, with no resolve required. For example, (and assuming your workspace is set to a mainline parent stream) to promote changes from the development stream to its parent mainline, issue the following commands:

$ p4 copy --from //Acme/dev
$ p4 submit -d "Check my new feature in"

Compare changes between streams

Using the p4 interchanges command, you can compare changes between streams to look for outstanding merges. Suppose you have a mainline stream //Acme/main and its child, a development stream, //Acme/dev. The following command tells you which changes exist in //Acme/dev but not in its parent stream:

$ p4 interchanges -S //Acme/dev

The following command tells you which changes exist in the parent of //Acme/dev but not in //Acme/dev:

$ p4 interchanges -S -r //Acme/dev

Propagate change across the stream hierarchy

You might need to propagate a specific change between two streams that do not have a natural parent-child relationship, for example, to obtain an in-progress feature or bug fix from a peer development stream. To merge from or copy to such a stream, you can re-parent your stream by editing its specification and setting the Parent: field to the desired source or target. This practice is not considered optimal but might be necessary.

Alternatively, you can use the -P option with the p4 merge command to do a one-off merge of the streams.

Helix Versioning Engine User Guide (2016.2)

Basic tasks

Overview of initial tasks

Overview of recurring tasks

Initial tasks

Create a working directory

Log in to the shared server

Start up a shared server

Start up the command line client and verify the connection to the server

Create a stream depot

Create a mainline stream

Define a workspace and bind it to the stream

Note

Populate the mainline stream

Note

Add files

Branch from other depots

Recurring file-level tasks

Sync files

Note

Add files

Add files outside of Helix and then use p4 reconcile -k

Edit files and check in changes

Delete files

Revert files, to discard changes

Rename and move files

Diff files

Resolve conflicts

Other recurring tasks

Changelist-related tasks

Submit a pending changelist

Create numbered changelists

Submit a numbered changelist

Note

Undo a submitted change

Shelve changelists

Display information about changelists

Move files between changelists

Delete changelists

Configure client behavior

Configure stream behavior

Branch and populate child streams

Propagate changes

Merge changes from a more stable stream

Copy changes to a more stable stream

Compare changes between streams

Propagate change across the stream hierarchy