Thursday, June 29, 2006

The force of Perforce

INTRO: Kick start

I'm a new colleague and I do not know how to start with Perforce. Can you explain me just the basics steps?
* Install Perforce
* Second you have to setup your client. Client in Perforce world is your workstatation, your workspase.
--- Open P4V this is a GUI for Perforce. Then Connections -> Open New Connection
Now you have to fill fields. Here is some terms:
The client name. The name of your workspace.
The user who created this client.
The root directory of the client file workspace, under which all client files will be placed. Here is mine:

Just use default...

A mapping from the files in the depot to files in the client workspace.
A new view takes effect on the next 'p4 sync'.
See view(mapping) example:
//depot/mainline/... //ZLATOZAR/...

So //depot/mainline/... will be mapped to my root.
--- Get things from depot. Depot is the repository. Type in workspace(root) command prompt:
p4 sync

* Before you start change file you have to declare that you want to edit it. Weird indeed but don't forget it.
All other knows that you are going to change this file. Your file is in changelist.
p4 edit //depot/mainline/Project1/MyFile.cs

* When you finish submit your changelist
p4 submit

or file by file
p4 submit TelephoneComponentHandler.cs

That is. Now more details.

PART ONE: The depot

1. Filespec Syntax
Perforce provides its own uniform syntax for referring to workspace and depot contents. This syntax is known as a file specifier, or "filespec."
Its converts filespecs to native file references for local operations. Depots, where Perforce keeps master file content, and workspaces, where users work on files, are hierarchical structures of directories and files.

A filespec uses "//" to indicate the root of the hierarchy, and "/" as a directory path and file name separator.
For example:

File names are case insensitive or case sensitive it depends from instalation.
Just check it and remeber.
is the same? And also spaces in filenames and pathnames have to be quoted when they are referenced in views
-- It is possible to use wild cards

--- Use "dot-dot-dot"
The "..." wildcard matches filename characters at or below a directory level.

2. File and directory revisions
Perforce's filespecs always refer to files, not directories. In fact there are no Perforce commands that operate on directories.
Use wild cards to refer directories.
I will describe a lot of commands, but for more information use command prompt help. Just type:
p4 help

p4 help [some of subjects]
p4 help [command that you are interested]

Perforce stores file versions in a sequence of numbered revisions. A filespec can refer to an absolute, numbered file revision, prefixed with #.
Filespecs can also refer to dates and labels, prefixed with @. And also label can be used to refer to file revisions to which it has been applied.
--- displays all files in Project1
p4 files //depot/mainline/Project1/*
//depot/mainline/Project1/MyFile.cs#15 - edit change 5401 (text)

--- display revisions of files for a specific version
p4 files //depot/mainline/Project1/*#15

--- display files using date and first letter of the file name
p4 files //depot/mainline/Project1/M*@5/16/2006

3. Changes and changelists
Perforce uses changelists to track changes submitted to the depot. Every changelist commit number is a snapshot of the depot (It is similar to tags in CVS). Versioning numbers are global
See my ASCII graphic:
Date:           05/05/2006  07/05/2006      23/05/2006
|          |               |
|    |        |            |    |
file1 -----------| #1 |--------|------------| #2 |------
|    |        |            |    |
|          |               |
|        |    |            |
file2 -----------------------| #1 |----------------------
|        |    |            |         
|          |               |
|    |        |               |
file3 -----------| #1 |---------------------------------
|    |        |               |
|          |               |
Changelist trak:   @102       @109             @114

4. Browsing the file tree
See examples:
--- to list all depots
p4 depots

(or p4 dirs "//*")
--- to list all dirs and subdirs
p4 dirs "//depot/*"

--- see file changes history
p4 changes -m5 //depot/mainline/Project1/TheFile.cs

Note:: The -m5 flag restricts the output to the five most recent changes. Each change is identified with a changelist number and the first 30-odd characters of a description. If you want to see entire descriptions, use changes -l.
--- what is on the default change list when I commit my files
p4 describe -s 5401

--- shows file revision numbers and the action (add, delete, etc.) that took place at each revision
p4 filelog //depot/mainline/Project1/TheHandler.cs

--- to see all changes and changelist
p4 annotate -c //depot/mainline/Project1/TheHandler.cs | more

(P4V's Time-lapse View is generated from the output of the annotate command.)
--- if you want to take a file(some revision) and pass it to another file
p4 print -q //depot/mainline/Project1/TheHandler.cs > newTCH.txt

--- compare revisions
p4 diff2 //depot/mainline/Project1/TheHandler.cs#14
//depot/mainline/IProject1/TheHandler.cs#15 | more

(p4 diff [old revision] [new revision])
In P4V the Tools -> Diff files command can be used to diff any two files or revisions. It shows only different lines! Eclipse diff wins...
The same command can be used to compare any two revisions of a directory. That is realy impressive. Keep in mind that Perforce can compare and merge onky text files.
--- discover file types
p4 help filetypes

The workspace file is executable.
The file is writable as soon as it's copied to the workspace. (Normally you have to open files to make them writable.)
RCS-like keywords in the file are expanded when the file is copied to the workspace.
The file is exclusively locked when opened so that only one person can have it open at a time.
The file's modification time is propagated with the file so that it shows up in the timestamp of synchronized copies.
Only one revision (the head revision) of the file is stored in the depot.
(This is useful for files generated and submitted by nightly builds, for example.)

Commbinations are also posible:

PART TWO: Files, workspace and change list

1. Creating workspace. Working with local files
The first thing you do before you can work on files is define a client workspace for yourself. A client workspace specification, or client spec, tells Perforce where in your local filesystem you want your workspace to be rooted. It has a view that defines the areas of the depot you want access to, and maps them to directories beneath the workspace root.
--- set up new
Note:: If P4CLIENT is not set, the name of your host machine will be used as the current workspace name.

For example, say you want to configure a workspace named Zlatozar-BG. First, you open up a client form in default editor:
p4 client Zlatozar-BG

An easy way: In P4V with the Connection -> Open Connection. Fill fields.
--- synchronyze workspace. Current dir.
p4 sync

--- get only one part
p4 sync //depot/mainline/Project1/

--- view all changes that are made after my commit
p4 changes "@>5401"

How to rewrite all my current changes?
* Check all files that you have changed
p4 diff -sa

* Reverting files is how you discard changes you've made to local files, rather than submitting them
p4 revert //depot/[path to the file]

How to restore localy removed files?
* Find them
p4 diff -sd

* List the files Perforce thinks you have with the have command
p4 have //.../Project1/...

* Restore(force) them
p4 sync -f //.../Project1/...

Note:: Workspace files are under your control and there's nothing to stop you or the programs you run from erasing files Perforce put there. But because Perforce thinks you have them already, you won't be able to replace them with a simple sync. So force it.
2. Working with local files
When you synchronize your workspace with depot files, Perforce normally puts read-only files on your local disk. To make files writable, you have to open them. You also have to open files you plan to add to or delete from the depot.Remember, in Perforce, an "open file" is a file you plan to submit to the depot. Don't confuse Perforce's meaning of "open" with the idea of opening files in an application.
--- open for edit
p4 edit //depot/mainline/Project1/TheHandler.cs

Now file is writable and in changelist. Team knows that you are working on that file if they type:
p4 opened -a //.../Project1/...

How many programers can work(open) on the same file?
All programers but first commiter wins. Rest of them have to resolve possible conflicts.
When you open file Perforce worns you thst another programmer works on it. Somthing like:
... - also opened by gosho@...

(Read more about p4 is not so easy.)
--- add files to depot
There is no need to open file to add it. You can open files only if they're in your workspace view.
p4 add //.../Project1/SofiaHandler.cs
p4 submit

--- delete files from depot
p4 delete //.../Project1/StrangeHandler.cs
p4 submit

As you open files, they are associated with a pending changelist. Your local changes don't affect the depot until you submit your files. What you submit to the depot is not individual files, really, but the entire pending changelist.
Remove all uchenged files first or commit files one by one
p4 revert -a
p4 submit

This is a weak point realy... be careful. It is posible to commit unchanged files. Realy realy weak point. Sorry. You can use this script:
# throw away (opened but) unchanged files
# (in Perforce it's a little bit too easy
# to checkin unchanged files)

p4 diff -sr | p4 -x - revert

Hi. I'm very creative programmer and I work on many differen tasks. How can I separate my works?
* The answear is - create different changelist for diffrent tasks an gave them proper names.
p4 change

This command brings up a spec form, just like submit. The form will list all the files opened in your default changelist. Simply fill in a description and save the form to move files to the new changelist.
* Open for edit in the right changelist
p4 edit -c dt-456

* Submit right changelist (eg. "dt-456")
p4 submit -c dt-456

* Empty pending changelists can be deleted
p4 change -d dt-456


1. Snapshots
Every time a user submits files to Perforce, a snapshot of the depot is created automatically. The changelist number created at submit time is effectively a global revision number. It can be use to reference any file or set of files in the depot snapshot. Don't forget that.
For example when submit change list:
p4 submit
Change 5401 submitted.

As you see the submit number is global. So you can refer it. If you want to take spesific change list (actually this is a snapshot):
p4 sync //depot/mainline/...@5401

p4 diff2 -q //depot/mainline/...@5400 //depot/mainline/...@5401

(and I found out all my changes)
or just use P4V's Folder Diff tool to compare snapshots...
2. Labels
In Perforce, as in many SCM systems, you can tag files with a label. To give names to snapshots. A label lets you use memorable names like REL2.0.1 to refer to specific configurations of file revisions.
--- see all labels maded from karl
p4 labels |grep alex

--- applying a label to files
p4 tag -l rel-2.0.1 //depot/mainline/...

--- referring label
p4 sync @rel-2.0.1

--- all files in label
p4 files @rel-2.0.1

3. Jobs
A job is an object in the Perforce database that can be used to tie development activity to external information. Jobs can be used for anything—requirements, project plans, to-do lists — but their most common use is for defect tracking.

PART FOUR: Resolving and merging (advanced level)

PART FIVE: Branching and merging (black belts)

To be continued...

No comments:

algorithms (1) cpp (3) cv (1) daily (4) emacs (2) freebsd (4) java (3) javascript (1) JSON (1) linux (2) Lisp (7) misc (8) programming (16) Python (4) SICP (1) source control (4) sql (1) думи (8)