Tutorial // Helix Versioning Engine User Guide

Read me first

This tutorial is for users not experienced with the Helix Versioning Engine. After working through this tutorial, you should understand the following:

the basics of starting up a shared server and command line client
getting a shared server and client communicating with each other
adding, editing, deleting, and syncing files on your client computer
checking those files into the server.

The sections that follow take you — step-by-step — through the tutorial.

Important

Before running this tutorial install the shared server and command client binaries onto the same computer. See “Installation” for instructions.

Make binaries executable, on UNIX and OS X

On UNIX and OS X, make the server and client binaries executable, if they aren’t already.

$ cd /usr/local/bin
$ chmod +x p4d
$ chmod +x p4

Create a working directory

Create a working directory in which to perform the rest of the steps in this tutorial, and then change to that directory. In this example, we create a directory called tutorial in the user’s home directory.

On Unix and OS X

$ mkdir /Users/bruno/tutorial
$ cd /Users/bruno/tutorial

On Windows

$ mkdir C:\Users\bruno\tutorial
$ cd C:\Users\bruno\tutorial

Start up the shared server

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 designated directory.

On Unix and OS X
```
$ mkdir /Users/bruno/server
```
On Windows
```
$ mkdir C:\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 and the -p port option to set the hostname:port number to localhost:1666, the required setting for running the shared server and the client on same computer.

On UNIX and OS X
```
$ p4d -r /Users/bruno/server -p localhost:1666
```
On Windows
```
$ p4d -r C:\Users\bruno\server -p localhost:1666
```
This produces the following output:
```
Perforce db files in 'server' will be created if missing...
Perforce Server starting...
```
Because the shared server runs in the foreground, you must open a new terminal window in which to run subsequent commands.

Start up the command line client

Change to your working directory.

This is the working directory you created in Create a working directory.

On UNIX and OS X
```
$ cd /Users/bruno/tutorial
```
On Windows
```
$ cd C:\Users\bruno\tutorial
```
Set the P4PORT environment variable

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

On UNIX and OSX
```
$ export P4PORT=localhost:1666
```
On Windows
```
$ set P4PORT=localhost:1666
```

Start up the command line client.

$ p4

This produces the following output, followed by a list of help commands.

Perforce -- the Fast Software Configuration Management System.

p4 is Perforce's client tool for the command line.

Verify the connection to the server

To verify a connection, run the p4 info command.

$ p4 info

If P4PORT is set correctly, information like the following is displayed:

User name: bruno
Client name: dhcp-133-n101
Client host: dhcp-133-n101.dhcp.perforce.com
Client unknown.
Current directory: /Users/bruno/tutorial
Peer address: 127.0.0.1:49917
Client address: 127.0.0.1
Server address: localhost:1666
Server root: /Users/bruno/server
Server date: 2016/03/01 16:15:38 -0800 PST
Server uptime: 00:03:26
Server version: P4D/DARWIN90X86_64/2015.2/1340214 (2016/02/03)
Server license: none
Case Handling: insensitive

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 you get the "host unknown" error, speak to your administrator.

Create a stream depot

Create a stream depot in which the stream you create in the next step will reside. Type the following:

$ p4 depot -t stream JamCode

The -t option specifies the type of depot to create, in this case a stream depot. JamCode is the name of the depot you’re creating.

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/...

Create your first stream

A stream is where you store your work. The first stream is always a mainline stream. To learn more about streams, see “Streams”.

To create the stream:

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

Here, we name the stream main and — with the -t option — specify the stream type as mainline:

$ p4 stream -t mainline //JamCode/main

Helix opens the stream specification (spec) in an editor:

# A Perforce Stream Specification.
#
#  Stream:       The stream field is unique and specifies the depot path.
#  Update:       The date the specification was last changed.
#  Access:       The date the specification was originally created.
#  Owner:        The user who created this stream.
#  Name:         A short title which may be updated.
#  Parent:       The parent of this stream, or 'none' if Type is mainline.
#  Type:         Type of stream provides clues for commands run
#                between stream and parent.  Five types include 'mainline',
#                'release', 'development' (default), 'virtual' and 'task'.
#  Description:  A short description of the stream (optional).
#  Options:      Stream Options:
#                       allsubmit/ownersubmit [un]locked
#                       [no]toparent [no]fromparent mergedown/mergeany
#  Paths:        Identify paths in the stream and how they are to be
#                generated in resulting clients of this stream.
#                Path types are share/isolate/import/import+/exclude.
#  Remapped:     Remap a stream path in the resulting client view.
#  Ignored:      Ignore a stream path in the resulting client view.
#
# Use 'p4 help stream' to see more about stream specifications and command.

Stream: //JamCode/main

Owner:  bruno

Name:   main

Parent: none

Type:   mainline

Description:
        Created by bruno.

Options:        allsubmit unlocked notoparent nofromparent mergedown

Paths:
        share ...

A stream spec defines the stream’s name and location, its type, its parent stream, the files in the workspace view of workspaces bound to it, and other configurable behaviors. Note that the stream name is composed of the stream depot name followed by the stream name. You edit the stream spec’s fields to configure the stream’s behavior, as explained at length in Configure a stream.

To verify that your mainline stream has been created, issue the p4 streams command.

For example:
```
$ p4 streams //JamCode/...
```
This produces the following output:
```
Stream //JamCode/main mainline none 'main'
```

Define a client workspace and bind it to the stream

A client workspace is the set of directories on your local computer where you work on the file revisions that Helix manages. At minimum, you should assign your workspace a name and specify a workspace root where you want local copies of depot files stored. The client workspace name defaults to the hostname of the computer on which your client is running. For details, see Configure a client workspace.

Before you can work in a stream, you must associate your workspace with the stream. When you associate a workspace with a stream, Helix generates the workspace view based on the structure of the stream. Workspace views are a crucial concept in Helix and are discussed in detail in Configure workspace views.

To create a workspace and bind it to a stream:

Set the P4CLIENT environment variable to desired workspace name.

On UNIX and OS X
```
$ export P4CLIENT=bruno_ws
```
On Windows
```
$ set P4CLIENT=bruno_ws
```

Use the p4 client command to bind your workspace to the stream.

$ p4 client -S //JamCode/main

The -S option specifies the name of the associated stream.

Helix opens the client specification (spec) in an editor:

# A Perforce Client Specification.
#
#  Client:      The client name.
#  Update:      The date this specification was last modified.
#  Access:      The date this client was last used in any way.
#  Owner:       The Perforce user name of the user who owns the client
#               workspace. The default is the user who created the
#               client workspace.
#  Host:        If set, restricts access to the named host.
#  Description: A short description of the client (optional).
#  Root:        The base directory of the client workspace.
#  AltRoots:    Up to two alternate client workspace roots.
#  Options:     Client options:
#                      [no]allwrite [no]clobber [no]compress
#                      [un]locked [no]modtime [no]rmdir
#  SubmitOptions:
#                      submitunchanged/submitunchanged+reopen
#                      revertunchanged/revertunchanged+reopen
#                      leaveunchanged/leaveunchanged+reopen
#  LineEnd:     Text file line endings on client: local/unix/mac/win/share.
#  Type:        Type of client: writeable/readonly.
#  Backup:      Client's participation in backup enable/disable. If not
#               specified backup of a writable client defaults to enabled.
#  ServerID:    If set, restricts access to the named server.
#  View:        Lines to map depot files into the client workspace.
#  ChangeView:  Lines to restrict depot files to specific changelists.
#  Stream:      The stream to which this client's view will be dedicated.
#               (Files in stream paths can be submitted only by dedicated
#               stream clients.) When this optional field is set, the
#               View field will be automatically replaced by a stream
#               view as the client spec is saved.
#  StreamAtChange:  A changelist number that sets a back-in-time view of a
#                   stream ( Stream field is required ).
#                   Changes cannot be submitted when this field is set.
#
# Use 'p4 help client' to see more about client views and options.

Client:         bruno_ws

Owner:          bruno

Host:           dhcp-133-n101.dhcp.perforce.com

Description:
                Created by bruno.

Root:           /Users/bruno/tutorial

Options:        noallwrite noclobber nocompress unlocked nomodtime normdir

SubmitOptions:  submitunchanged

LineEnd:        local

Stream:         //JamCode/main

View:
                //JamCode/main/... //bruno_ws/...

At this point you have the option to configure the workspace root directory and any other desired settings. The workspace root is the highest-level directory of the workspace under which the managed source files reside. For more information, see Define a client workspace. Once you’ve done this, save any changes and quit the editor.

For information about configuring other settings, see Configure workspace views.

Verify that your workspace has been created, with the p4 clients command.
```
$ p4 clients -S //JamCode/main
```
This produces the following output:
```
Client bruno_ws 2016/02/22 root /Users/bruno/tutorial 'Created by bruno.'
```

Next, populate the mainline stream with files.

Populate a mainline stream

Now that you’ve created a stream, you can populate it with files. There are two ways to populate a mainline stream:

Add files from the local filesystem.
Branch files from another depot.

In this tutorial, we demonstrate populating by adding files. For information on populating by branching from another depot, see Branch from other depots.

To add files to the mainline stream, copy the files and folders to the workspace root directory and then mark them for add with the p4 add command.

Copy the files and folders to the workspace root directory.

In this example, we add all files residing in a directory named /Users/bruno/repository.

On UNIX and OSX
```
$ cp /Users/bruno/repository/* /Users/bruno/tutorial
```
On Windows
```
$ copy C:\Users\bruno\repository\* C:\Users\bruno\tutorial
```
Change into the client workspace root directory.

On UNIX and OSX
```
$ cd /Users/bruno/tutorial
```
On Windows
```
$ cd C:\User\bruno\tutorial
```
Mark the files for add.
```
$ p4 add *
```
This creates a default changelist, which you will use when you submit to the depot the file you added to your workspace. For more information on changelists, see Changelist-related tasks.
Submit the added files.

To populate the stream, submit the default changelist in which the files are open for add.
```
$ p4 submit
```
Helix opens the change specification in an editor:

# A Perforce Change Specification.
#
#  Change:      The change number. 'new' on a new changelist.
#  Date:        The date this specification was last modified.
#  Client:      The client on which the changelist was created.  Read-only.
#  User:        The user who created the changelist.
#  Status:      Either 'pending' or 'submitted'. Read-only.
#  Type:        Either 'public' or 'restricted'. Default is 'public'.
#  Description: Comments about the changelist.  Required.
#  ImportedBy:  The user who fetched or pushed this change to this server.
#  Identity:    Identifier for this change.
#  Jobs:        What opened jobs are to be closed by this changelist.
#               You may delete jobs from this list.  (New changelists only.)
#  Files:       What opened files from the default changelist are to be added
#               to this changelist.  You may delete files from this list.
#               (New changelists only.)

Change: new

Client: bruno_ws

User:   bruno

Status: new

Description:
        <enter description here>

Files:
        //JamCode/main/file1.cc        # add
        //JamCode/main/file1.h # add
        //JamCode/main/file1.txt       # add
        //JamCode/main/file2.cc        # add
        //JamCode/main/file2.h # add
        //JamCode/main/file2.txt       # add
        //JamCode/main/file3.cc        # add
        //JamCode/main/file3.h # add
        //JamCode/main/file3.txt       # add

Enter a description under Description and then save your changes, to store the files you added in the Helix depot. Something like the following output is displayed:

Change 1 created with 9 open file(s).
Submitting change 1.
Locking 9 files ...
add //JamCode/main/file1.cc#1
add //JamCode/main/file1.h#1
add //JamCode/main/file1.txt#1
add //JamCode/main/file2.cc#1
add //JamCode/main/file2.h#1
add //JamCode/main/file2.txt#1
add //JamCode/main/file3.cc#1
add //JamCode/main/file3.h#1
add //JamCode/main/file3.txt#1
Change 1 submitted.

The files you added are now stored in the Helix depot.

Edit files

Now that the files are stored in the depot, you or others can check them out of the depot to edit them. To open files for edit, issue the p4 edit command, followed by the names(s) of the files you want to edit:

$ p4 edit file1.txt

This displays output like the following:

//JamCode/main/file1.txt#1 - opened for edit

Now you can edit the file in the editor of your choice and make changes. After you’ve made the desired changes, you submit the changelist associated with the file(s):

$ p4 submit

This open a change specification in an editor:

#
#  Change:      The change number. 'new' on a new changelist.
#  Date:        The date this specification was last modified.
#  Client:      The client on which the changelist was created.  Read-only.
#  User:        The user who created the changelist.
#  Status:      Either 'pending' or 'submitted'. Read-only.
#  Type:        Either 'public' or 'restricted'. Default is 'public'.
#  Description: Comments about the changelist.  Required.
#  ImportedBy:  The user who fetched or pushed this change to this server.
#  Identity:    Identifier for this change.
#  Jobs:        What opened jobs are to be closed by this changelist.
#               You may delete jobs from this list.  (New changelists only.)
#  Files:       What opened files from the default changelist are to be added
#               to this changelist.  You may delete files from this list.
#               (New changelists only.)

Change: new

Client: bruno_ws

User:   bruno

Status: new

Description:
        <enter description here>

Files:
        //JamCode/main/file1.txt       # edit

Enter a description under Description and then save your changes, to store the edits you made in the Helix depot. Something like the following output is displayed:

Change 2 created with 1 open file(s).
Submitting change 2.
Locking 1 files ...
edit //JamCode/main/file1.txt#2
Change 2 submitted.

Delete files

Deleting files is more complicated than just deleting them from your filesystem. To mark files for delete, issue the p4 delete command. In this case, we choose to delete just the header files.

$ p4 delete *.h

Helix displays the following:

//JamCode/main/file1.h#1 - opened for delete
//JamCode/main/file2.h#1 - opened for delete
//JamCode/main/file3.h#1 - opened for delete

As in Edit files, you issue the p4 submit command to have the deletion affect files in the depot:

$ p4 submit

Helix opens the change specification in an editor:

# A Perforce Change Specification.
#
#  Change:      The change number. 'new' on a new changelist.
#  Date:        The date this specification was last modified.
#  Client:      The client on which the changelist was created.  Read-only.
#  User:        The user who created the changelist.
#  Status:      Either 'pending' or 'submitted'. Read-only.
#  Type:        Either 'public' or 'restricted'. Default is 'public'.
#  Description: Comments about the changelist.  Required.
#  ImportedBy:  The user who fetched or pushed this change to this server.
#  Identity:    Identifier for this change.
#  Jobs:        What opened jobs are to be closed by this changelist.
#               You may delete jobs from this list.  (New changelists only.)
#  Files:       What opened files from the default changelist are to be added
#               to this changelist.  You may delete files from this list.
#               (New changelists only.)

Change: new

Client: jschaffer_ws

User:   jschaffer

Status: new

Description:
        <enter description here>

Files:
        //JamCode/main/file1.h # delete
        //JamCode/main/file2.h # delete
        //JamCode/main/file3.h # delete

Enter a description under Description and then save your changes, to store the changes you made in the Helix depot. Something like the following output is displayed:

Change 3 created with 3 open file(s).
Submitting change 3.
Locking 3 files ...
delete //JamCode/main/file1.h#2
delete //JamCode/main/file2.h#2
delete //JamCode/main/file3.h#2
Change 3 submitted.

Sync files from the depot to your client workspace

Syncing (retrieving files from the depot) — with the p4 sync command — specifies the files and directories you want to retrieve from the depot. You do this to obtain the latest changes — be they edits, adds, or deletes — that have been made by others and then submitted to the depot.

You can only sync files that are mapped in your workspace view. For more information on workspace views, see Configure workspace views.

$ p4 sync ...

By passing in …, we request to sync all files in the current directory.

Suppose that another user has made changes to file1.cc and file3.cc. A sync request, would yield output like the following:

//JamCode/main/file1.cc#3 - updating /Users/bruno/workspace/tutorial/file1.cc
//JamCode/main/file3.cc#5 - updating /Users/bruno/workspace/tutorial/file3.cc

Populate child streams

After populating the mainline, 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 //JamCode/main //JamCode/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 //JamCode/dev -r
$ p4 sync

Helix Versioning Engine User Guide (2016.2)

Tutorial

Read me first

Important

Make binaries executable, on UNIX and OS X

Create a working directory

Start up the shared server

Start up the command line client

Verify the connection to the server

Create a stream depot

Create your first stream

Define a client workspace and bind it to the stream

Populate a mainline stream

Edit files

Delete files

Sync files from the depot to your client workspace

Populate child streams