Managing Files and Changelists
This chapter tells you how to manage files and work in a team development environment, where multiple users who are working on the same files might need to reconcile their changes.
Managing files
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. Here are the basic steps for working with files.
Task | Description | ||||||
---|---|---|---|---|---|---|---|
Syncing (retrieving files from the depot) |
Issue the |
||||||
Adding files to the depot |
|
||||||
Editing files and checking in changes |
|
||||||
Deleting files from the depot |
|
||||||
Discarding changes |
Revert the files or the changelist in which the files are open. Reverting has the following effects on open files:
|
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 about the syntax that you use to specify files on the command line, refer to Specifying filenames on the command line. The following sections provide more details about working with files:
Syncing (retrieving) files
To retrieve files from the depot into your client workspace, issue the p4
sync
command. You cannot sync files that are not in your client view. For
details about specifying client views, see Refining workspace views.
Example 15. Copying 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
//depot/dev/main/bin/bin.linux24x86/readme.txt#1 - added as c:\bruno_ws\dev\main\bin\bin.linux24x86\readme.txt
//depot/dev/main/bin/bin.ntx86/glut32.dll#1 - added as c:\bruno_ws\dev\main\bin\bin.ntx86\glut32.dll
//depot/dev/main/bin/bin.ntx86/jamgraph.exe#2 - added as c:\bruno_ws\dev\main\bin\bin.ntx86\jamgraph.exe
[...]
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.
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 //depot/dev/main/jam/Jamfile#1
For more details, refer to Specifying file revisions.
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 //depot/dev/main/jam/...
For more details, see Helix wildcards.
The Helix service tracks which revisions you have synced. For maximum
efficiency, Helix does not resync an already-synced file revision. To resync
files you (perhaps inadvertently) deleted manually, specify the -f
option when
you issue the p4 sync
command.
Adding 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.
For platform-specific details about adding files recursively (meaning files in subdirectories), see “Adding a Directory Tree” in the Helix knowledge base:
http://answers.perforce.com/articles/KB_Article/Adding-a-Directory-Tree
Example 16. Adding files to a changelist.
Bruno has created a couple of text files that he needs to 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\dev\main\docs\manuals> p4 add *.txt
//depot/dev/main/docs/manuals/installnotes.txt#1 - opened for add
//depot/dev/main/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 17. Submitting 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: //depot/dev/main/docs/manuals/installnotes.txt # add //depot/dev/main/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.
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.
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
-
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.
Ignoring groups of files when adding
Sometimes development processes result in the creation of extraneous content that should not be submitted to the depot. Compilers produce object files and executables during development, text editors and word processors produce backup files, and you may have your own personal conventions for notes on work in progress.
To ignore files (or groups of files) when adding, create a file with a list of
file specifications you wish to ignore, and set the P4IGNORE
environment
variable to point to this file.
When you add files, the full local path and parent directories of any file to be
added are searched for P4IGNORE
files. If any P4IGNORE
files exist, their
rules are added to a list, with greater precedence given to P4IGNORE
rules
closest to the file being added.
The syntax for P4IGNORE
files is not the same as Helix syntax. Instead, it
is similar to that used by other versioning systems: files are specified in
local syntax, a #
character at the beginning of a line denotes a comment, a
!
character at the beginning of a line excludes the file specification, and
the *
wildcard matches substrings. The Helix wildcard of ...
is not
permitted.
Character | Meaning in P4IGNORE files
|
---|---|
|
Matches anything except slashes. Matches only within a single directory. Case sensitivity depends on your client platform. |
|
Exclude the file specification from consideration. |
|
Comment character; this line is ignored. |
Example 18. Ignoring groups of files when adding.
Bruno unit tests his code before submitting it to the depot and does not want to accidentally add any object files or generated executables when reconciling his workspace.
Bruno first sets P4IGNORE
to point to the correct file:
$ export P4IGNORE=.p4ignore
He then creates the following file and stores it as .p4ignore
in the root of
his workspace:
# Ignore .p4ignore files .p4ignore # Ignore object files, shared libraries, executables *.dll *.so *.exe *.o # Ignore all text files except readme file *.txt !readme.txt
The next time he runs a command (such as p4 add *.*), the rules are applied across the entire workspace.
To override (or ignore) the P4IGNORE
file, use the -I
option with the
p4 add
, p4 reconcile
, or p4 status
commands.
Reporting ignored files
The p4 ignores
command reports the ignore mappings in effect. Specifically,
it displays the ignore mappings computed from the rules in the P4IGNORE
file.
If you add the -i
option, it reports whether a particular file or set of files
will be ignored.
For more information on p4 ignores
, see the p4 ignores
page in the
P4 Command Reference.
Changing files
To open a file for edit
, issue the p4 edit
command. When you open a file
for edit, Helix enables write permission for the file in your workspace and adds
the file 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. You must open a file for edit
before you attempt to edit the file.
Example 19. Opening 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 //depot/dev/command.c
//depot/dev/command.c#8 - added as c:\bruno_ws\dev\command.c
C:\bruno_ws\dev> p4 edit //depot/dev/command.c
//depot/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
, as described above.
Discarding changes (reverting)
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 20. Reverting a file
Bruno decides not to add his text files after all.
C:\bruno_ws\dev> p4 revert *.txt
//depot/dev/main/docs/manuals/installnotes.txt#none - was add, abandoned
//depot/dev/main/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.
Deleting 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 21. Deleting a file from the depot.
Bruno deletes vendor.doc
from the depot as follows:
C:\bruno_ws\dev> p4 delete //depot/dev/main/docs/manuals/vendor.doc
//depot/dev/main/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.
Managing 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 service without formally submitting them to the depot.
The Helix service 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.
The commands that add or remove files from changelists are:
|
|
|
|
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.
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
.
Note
Using parallel submits can significantly improve performance. For additional
information see the description of the p4 submit
command in the
P4 Command Reference.
Creating 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 22. 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 for edit in the default changelist:
C:\bruno_ws> p4 sync //depot/dev/main/jam/*.c
[list of files synced...]
C:\bruno_ws> p4 edit //depot/dev/main/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 23. 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.
Submitting changelists
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 service, 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.
Deleting 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.
Renaming and moving 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 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. For details, see Integrating changes.
Shelving work in progress
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 24. 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 //depot/dev/command.c
//depot/dev/command.c#9 - opened for edit
...
$ p4 shelve
Change 123 created with 1 open file(s).
Shelving files for change 123.
edit //depot/dev/command.c#9
Change 123 files shelved.
A pending changelist is created, and the shelved version of command.c
is
stored in the service. 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 25. 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 machine, types:
C:\bruno_ws\dev> p4 unshelve -s 123 //depot/dev/command.c
//depot/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 26. 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 //depot/dev/command.c
//depot/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 //depot/dev/command.c
//depot/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, 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 27. 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.
Displaying 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 |
---|---|
|
Displays a list of all pending, submitted, and shelved changelists, one line per changelist, and an abbreviated description. |
|
Limits the number of changelists reported on to the last specified number of changelists. |
|
Limits the list to those changelists with a particular status; for example,
|
|
Limits the list to those changelists submitted by a particular user. |
|
Limits the list to those changelists submitted from a particular client workspace. |
|
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 |
|
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 23, “Automatic renumbering of changelists” can be retrieved with either |
For more information, see Changelist reporting.
Diffing files
Helix provides the ability 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 workstation, but the
p4 diff2
command instructs the Helix service 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 |
|
The workspace file |
Revision 3 |
|
The head revision |
Revision 134 |
|
File revision at changelist 32 |
File revision at changelist 177 |
|
The workspace file |
A file shelved in pending changelist 123 |
|
All files in release 1 |
All files in release 2 |
p4 diff2 //depot/rel1/... //depot/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.
Working offline
The preferred method of working offline (without access to the Helix service) is to use DVCS (distributed versioning) features. For details, refer to Using Distributed Versioning with Helix.
If you work offline, you must manually reconcile your work with the Helix service when you regain access to it. The following method for working detached assumes that you work on files in your workspace or update the workspace with your additions, changes, and deletions before you update the depot:
To work offline:
- Work on files without issuing
p4
commands. Instead, use operating system commands to change the permissions on files. - After the network connection is re-established, use
p4 status
orp4 reconcile
to find all files in your workspace that have changed. - Submit the resulting changelist(s).
To detect changed files, issue the p4 status
or p4 reconcile
commands.
The commands perform essentially the same function, but differ in their default
behavior and output format.
Command | Description |
---|---|
|
When called without arguments, |
|
When called without arguments, |