Overview
This chapter provides an overview of the Helix version management system.
Important
Read the "Basic Concepts" chapter of Introducing Helix before reading this guide.
This guide documents the command-line client only. For documentation on other clients, see the Helix documentation website.
Although this guide presents the command line interface, it discusses all the other things you need to know regardless of interface choice.
Introduction
Helix is an enterprise version management system in which you connect to a shared versioning server; you sync files from a shared repository called the depot, and edit them on your computer in your workspace. You manage files with the help of changelists. You have the option of submitting to the depot any changes you make locally to make them available to other users.
The Helix server also known as p4d, manages depots, which contain every
revision of every file under version management. Files are organized into
directory trees. The server also maintains a database to track data associated
with files and client activity: logs, user permissions, metadata, configuration
values, and so on.
Helix clients provide an interface that allows you to check files in and out of the depot, resolve conflicts, track change requests, and more. Helix includes a number of clients: a command-line client, a graphical user interface client, and various plugins that work with commercial IDEs and productivity software.
Helix also supports a decentralized (“distributed”) workflow. See the "Basic Concepts" chapter of Introducing Helix, and Using Helix for Distributed Versioning.
File management
You use Helix clients to manage a special area of your computer, called a workspace. Directories in the depot are mapped to directories in your workspace, which contain local copies of managed files. You always work on managed files in your workspace:
- You populate your local workspace by syncing files from the depot.
- You check the files out of the depot (and into your workspace).
- You make changes to the files.
- You check them back into the depot, also known as submitting.
- If the changes you try to submit conflict with changes that other users, working in parallel with you, have already submitted, you must resolve conflicts as needed.
Changelists
The unit of file submission is the changelist; it is the means by which you check files in and out of the depot. A changelist must contain at least one file and may contain tens of thousands. A changelist is numbered and allows you to track all changes with respect to the contents of the depot: file modifications, the addition of a file, or the deletion of a file.
A changelist is the simplest way to organize your work. A changelist also represents the atomic unit of work in Helix: if a changelist includes several files, changes for all the files are committed to the depot or none of the changes are. For example, if a network connection between the client and the server fails during changelist submission, the entire submit fails.
Parallel development
As with all version management systems, Helix is designed to let multiple users work on the same files, codelines, or digital assets in parallel and then reconcile differences later. When conflicts occur, the system resolves them if the user cannot.
Helix permits parallel development at two levels:
- At the file level, with shared files
- At the codeline level, with branching.
Branching: branches versus streams
In the course of a collaborative development project, you may find it useful to split off the codeline into multiple codelines, each having a distinct intended purpose. For example, when a certain milestone is reached in development, you may choose to copy the code — also known as branching it — into a new codeline for testing, thereby creating a QA branch. After it passes all tests, it is copied up to the Beta test line where it is subjected to real-world use. Later, you may choose to merge one or more of these new branches back into the main codeline.
Streams: branches with additional intelligence
Streams are like branches, with additional intelligence built in. They provide clues of where and how to do branching and merging. They guide merging and branching actions that support both stability and innovation. In addition, using streams eliminates a lot of the work needed to define branches, to create workspaces, and to manage merges.
When you create a stream, you specify its type, information about the files it is associated with, its relationship to other streams, and how files are to be treated for branching and merging. The system uses the information you provide to encourage merging best practices and to track parallel development.
The stream type tells the system how stable the stream is relative to other streams. The stream’s path info tells the system a number of things; including which files to populate the workspace with, which files child streams are allowed to branch, and, if necessary, which changelist to lock the files at. Parent labeling specifies how the stream relates to other streams in the system, helping to determine how change flows through the system.
Streams are ideal for implementing the mainline branching model, in which less stable streams merge changes to keep up to date with their parents, then copy work to the parent when the work is stable enough to promote. In addition, streams enable the system to generate views for associated workspaces, eliminating the need for you to update views manually to reflect changes to your stream structure.
Note
This guide assumes the reader is using streams, but notes where instructions differ for branch users.
Security
The Helix command line client supports a number of security-related features, mostly having to do with SSL encryption.
Organizing your work: jobs and labels
In addition to using changelists and streams to organize your work, you can use two other methods: jobs and labels.
- Jobs provide lightweight issue tracking that integrates well with third party defect tracking and workflow systems. They allow you to track the status of a bug or an enhancement request. Jobs have a status and a creator and are associated with changelists that implement the bug fix or the enhancement.
- Labels are sets of tagged file revisions that allow you to handle a heterogeneous group of files as one unit. While a changelist refers only to the contents of a given set of files at the time they were submitted, a label can refer to a group of file revisions from different points in time. You might want to use labels to define the group of files contained in a particular release, to sync a set of files, to populate a workspace, or to specify a set of file revisions to be branched. You can also use a label as an alias for a changelist number, which makes it easier to remember the changelist and easier to refer to it in issuing commands.
Scripting and reporting
You can use client commands in scripts and for reporting purposes. For example, you could:
- merge and then resolve multiple files in one script
- use the UNIX Stream Editor (sed) in conjunction with a Helix client command to create a job
- issue a command reporting all labels containing a specific file revision (or range)