<!DOCTYPE html>
<html>
<head lang="en">
<meta charset="UTF-8">
<title>p5</title>
</head>
<body style="font-family:Arial;font-size:12px">
<h1>p5: a set of tools for use with Perforce.</h1>
<b>p5</b> is a drop-in replacement for p4 (the Perforce CLI). It
provides some new commands, and enhances the behavior of some existing
commands.
<h2>Enhanced commands</h2>
p5 provides enhanced versions of a few Perforce commands:
<ul>
<li> <code><b>p5 describe</b></code> is an enhanced version
of <code>p4 describe</code>. It will print the contents
of <i>added</i> files, instead of merely showing a diff of
modified files.
<li> <code>p4 submit</code> insists that you manually delete shelved
files before it will let you submit a changeset. <code><b>p5 submit</b></code>
automatically deletes the shelf.
<li> <code>p4 revert</code> leaves abandoned files--files that were
added, and then reverted) in the local workspace. This can be
problematic when using build tools like Maven which happily compile
every Java source it can get its hands on.
<code><b>p5 revert</b></code> notices the abandoned files and asks
if they should be deleted. With the <code><b>-f</b></code> option,
it doesn't ask, it just deletes them.
<li> The default <code>p4 diff</code> format is usually not what one
wants. If the environment variable P5_DIFF_FLAG is set
(e.g., <code><b>export P5_DIFF_FLAG=-du</b></code>, <code><b>export
P5_DIFF_FLAG=-dc10</b></code>, etc.), that will be used by default.
This applies to all the p5 commands that generate diffs. (This is
similar to <code>P4DIFF</code>, but some people find <code>P5_DIFF_FLAG</code>
more convenient to use.)
<li> <code>p5 changes</code> has several shortcuts for common
command line options:
<ul>
<li> <code><b>-u me</b></code> is shorthand
for <code>-u <i>your-user-id</i></code>. (It's also fun to say
out loud.) This shortcut works for the other commands that
take <code><b>-u</b></code> as well
(<code>p5 branches</code>, <code>p5 clients</code>, <code>p5
labels</code>, <code>p5 opened</code>).
<li> The <i>status</i> argument can be abbreviated:
<br>
<table border="1" style="width:500px">
<tr>
<th align="left"><code>p5 command</code></th>
<th align="left"><code>Expands to</code></th></tr>
<tr>
<td><code>p5 changes -s p</code></td>
<td><code>p4 changes -s pending</code></td></tr>
<tr>
<td><code>p5 changes -s sh</code></td>
<td><code>p4 changes -s shelved</code></td></tr>
<tr>
<td><code>p5 changes -s su</code></td>
<td><code>p4 changes -s submitted</code></td></tr>
</table>
<br>
<li> If that's still too much typing for you, there's
<code><b>p5 pending</b></code> and <code><b>p5 shelved</b></code>
which take all the same arguments as <code>p5 changes</code>,
but default to <code>-u me</code> and the appropriate value
for <code>-s</code>.
<li> Finally, <code><b>here</b></code> can be specified for the
optional <i>client</i> argument, as a shortcut for the current
workspace.
</ul>
<li> To summarize by example:
<br>
<table border="1" style="width:500px">
<tr>
<th align="left"><code>p5 command</code></th>
<th align="left"><code>Might expand to</code></th></tr>
<tr>
<td><code>p5 shelved</code></td>
<td><code>p4 changes -u adent -s shelved</code></td></tr>
<tr>
<td><code>p5 changes -c here</code></td>
<td><code>p4 changes -c bypass3</code></td></tr>
<tr>
<td><code>p5 pending -c here</code></td>
<td><code>p4 changes -u adent -s pending -c bypass3</code></td></tr>
</table>
<li> For people who can't remember that <code>p4 describe</code> and
<code>p4 change</code> do not take the <code>-c</code> option, the
p5 versions of these commands allow it.
<li> Similarly, the lower-case <code>-c</code> option to <code>p4
changes</code> is inconsistent with the other commands, so <code>p5
changes</code> accepts upper-case <code>-C</code> as well.
</ul>
<h2>Enhanced changeset syntax</h2>
If you hate remembering and typing changeset numbers, p5 can take care
of that for you. All of the p5 commands that
take <code><b>-c <i>changeset</i></b></code> on the command line will
accept an enhanced changeset specification. The format can be
summarized as
<pre>
-c (p|su|sh)[:<i>userid</i>][:<i>nth</i>]
</pre>
<p>
For example, you can type <code><b>-cp</b></code> and p5 will replace
that "<code><b>p</b></code>" with the most recent pending changeset
number in the current workspace. That way, you never have to look
up the number for the changeset you're working on. Examples:
<ul>
<li> <code><b>p5 share -cp</b></code>
<li> <code><b>p5 change -cp</b></code>
<li> <code><b>p5 submit -cp</b></code>
</ul>
<p>
<code><b>-c sh</b></code> and <code><b>-c su</b></code> do the
same for the most recently <b>sh</b>elved and <b>su</b>bmitted changesets.
<p>
If you specify an optional <i>userid</i>, p5 will show the most recent
changeset for that user, instead of for the current workspace. So, for
example, <code><b>p5 describe -csu:suzanne</b></code> will show
Suzanne's most recently submitted
changeset.
The <code><b>me</b></code> shortcut works here, too. So <code><b>p5
describe -S -c sh:me</b></code> will show your most recently
shelved changeset in <i>any</i> workspace.
<p>
Finally, an optional <i>nth</i> specifier allows you to select the nth
most recent changeset. For example, <code><b>p5 describe -c
su:2</b></code> will show the penultimate submission from the current
workspace. <code><b>p5 describe -c su:me:2</b></code> will show your
penultimate submission across all workspaces.
<p>
Enhanced changeset specifications also work with <code><b>p5 unshelve
-s</b></code>. For example, if you just shelved something in one
workspace, you can unshelve it in another by saying <code><b>p5
unshelve -s sh:me</b></code>.
<h2>Workspace Backups</h2>
When writing code that will eventually be submitted to the Perforce
depot, it is often helpful to checkpoint the work as it progresses, so
you can revert the workspace back to that point, or even just grep
through it months or years later.
<h3>Creating a backup</h3>
<code><b>p5 backup [-ef] [-b <i>backup-name</i>] [-c <i>changeset</i>]
[-C <i>client</i>] [-d <i>description</i>] [<i>file</i>...]</b></code>
<p>
<code>p5 backup</code> creates a tarball of all currently open files,
and stores it in <b>~/p5.backup/<i>workspace</i>/<i>backup</i></b>,
where <i>workspace</i> is the name of the current Perforce client,
and <i>backup</i> is an automatically incrementing number. A diff
file—suitable for feeding to patch(1)—is also saved in that same
directory. It also prompts for a short description of the backup,
which is stored in a <code>comment.txt</code> file.
<p>
Here are the command line options in decreasing order of usefulness:
<ul>
<li> <code><b>-e</b></code> says rather than creating a new backup,
edit the comment file of an existing backup. On Non-Windows
machines, the default backup is the most recently created one.
(This makes it easy to edit the comment of the backup you just
created. Simply add <code><b>-e</b></code> to the command line.)
<li> <code><b>-f</b></code> says don't prompt for a description. You can
still create one later with <code><b>-e</b></code>.
<li> <code><b>-b <i>backup-name</i></b></code> says to use the indicated
backup-name instead of using the automatically incrementing number.
<li> <code><b>-c changeset</b></code> says to only backup files from
the indicated changeset.
<li> <code><b>-d <i>description</i></b></code> specifies the
description on the command line instead of prompting the user.
<li> <code><b>-C <i>client</i></b></code> says to backup the
indicated workspace, instead of the current one.
<li> <code><b><i>file</i>...</b></code> says only backup the indicated files.
</ul>
If you want your backups somewhere other
than <code>~/p5.backup/</code>, set the environment variable
P5_BACKUP_DIR to point to that directory.
<h3>Restoring from backup</h3>
<pre>
<code><b>p5 restore [-b <i>backup-name</i>] [-B <i>src-client</i>] [-c <i>changeset</i>] [-C <i>client</i>] [-n] [-p | <i>file</i>...]</b></code>
</pre>
p5 restore will return the files to the state they were in at the time
the backup was created. On Unix, the most recent backup is used by
default. So, e.g., if all your open files are in the default
changeset, this sequence will leave your workspace unchanged:
<pre>
$ p5 backup -f
$ p5 revert ...
$ p5 restore
</pre>
The command line options are the same as for <code>p5 backup</code>, with the following additions:
<ul>
<li><code><b>-b <i>backup-name</i></b></code> is the backup to
restore from. On Windows, this is required. On other platforms
it defaults to the most recently created backup for the workspace.
<li><code><b>-n</b></code> says don't actually do the restore. Just
show a preview of what would be done.
<li><code><b>-B</b></code> says restore from a backup belonging to a
different workspace. This is a safe and convenient way to move
changes from one workspace to another without checking them in. (If
they were checked in, you could/should use <code>p4 integrate</code>.)
<li><code><b>-p</b></code> says uses patch(1) instead of tar(1) to
restore the files' contents. This can be particularly useful when
restoring a backup that was created in a different workspace (<code>-B</code>) or
on an older revision of the files. As is always the case when using
patch(1), inspect the results carefully.
</ul>
Note: On Windows machines, <code><b>-b <i>backup-name</i></b></code>
is must be specified. On other systems, it defaults to the most
recently created one.
<h3>Examining a backup</h3>
<pre>
<code><b>p5 bdiff [-b <i>backup-name</i>] [-B <i>src-client</i>] [-d<flag>] <i>file</i>...</b></code>
<code><b>p5 bprint [-b <i>backup-name</i>] [-B <i>src-client</i>] [-q] [-r] <i>file</i>...</b></code>
</pre>
These two commands examine the contents of one or more files in a
backup. <code><b>p5 bdiff</b></code> compares the file to the version
in the current workspace.
Normally, <i>file</i>s refer to files in the current workspace
relative to the current directory. This is usually the right thing,
but may lead to surprising behavior for <code><b>p5 bprint
-B <i>src-client</i></b></code> if the current workspace has a
different directory layout than the backup did.
<p>
To address this, the <code><b>-r</b></code> flag says to treat
the <i>file</i>s as paths relative to the root of the backed up
workspace, without considering the current workspace at all.
Note: On Windows machines, <code><b>-b <i>backup-name</i></b></code>
is must be specified. On other systems, it defaults to the most
recently created one.
<h3>Listing all backups</h3>
<code><b>p5 backups [-l] [-b <i>backup-glob</i> | -m <i>max</i>] [-B <i>src-client</i>]</b></code>
<p>
<code>p5 backups</code> lists the backups for the current workspace,
along with their descriptions.
<ul>
<li><code><b>-b <i>backup-glob</i></b></code> says to only show those
backups with names matching the indicated pattern using shell-style
globbing. So, e.g., say
<pre> p5 backups -b '02?'
</pre>
to display backups 20-29.
<li><code><b>-m <i>max</i></b></code> says to only show that many
backups from the bottom of the list (which will be the most recent
ones, if you use automatic numbering).
<li><code><b>-l</b></code> prints a long listing, showing the
description and contents of each backup.
</ul>
<h2>Code review</h2>
<h3>Sending code out for review</h3>
<code><b>p5 share [-o] [-c <i>changeset</i>] [-d <i>flag</i>] [-s] [-t] [<i>file</i>...]</b></code>
<p>
This command prepares a diff of the specified files, suitable for code review.
Files associated with a changeset are also shelved in that changeset.
By default, the diff file is saved in your home-directory in a file
named <i>changeset</i><code>.share</code>. If you want to save it
somewhere else, put the pathname in the environment variable
P5_SHARE_FILE, putting "%s" where you want the changeset number to go.
For example, you might add this to your ~/.kshrc file:
<pre>
export P5_SHARE_FILE=$HOME/review/%s.desc
</pre>
If p5 share can't find a single changeset number--either because there
are multiple changesets pending, or because all the opened files are
in the default changeset--it will use the filename <code>p5.share</code>.
<ul>
<li> <code><b>-o</b></code> says don't create a diff file, and don't
shelve anything; just write the diff to the standard output.
<li> <code><b>-c</b></code> says only include files from the
indicated changeset.
<li>The other options are passed to <code>p4 diff</code>.
</ul>
<h3>Viewing changesets</h3>
<code><b>p5 desc [-d flag] [[-c] changeset] [-s]</b></code>
<p>
This is a DWIM command. It runs one of <code>p5
share</code>, <code>p5 describe</code> or
<code>p5 describe -S</code> depending on whether the changeset is in the local
workspace, submitted or shelved (respectively). And for changesets
that get renamed at submit-time, you can specify either the old or the
new changeset number.
<h2>Use with other Perforce utilities</h2>
Home-grown Perforce tools can also be wrapped by p5, so that they can
take advantage of the enhanced changeset syntax. Simply set the
environment variable P5_WRAPPED. For example, if your workgroup has
scripts named <code>p4validate</code> and <code>p4nits</code>, you
might set this in your environment:
<pre>
export P5_WRAPPED=grab=get_changeset:nits=p4nits
</pre>
Then:
<table border="1" style="width:500px">
<tr>
<th align="left"><code>p5 command</code></th>
<th align="left"><code>Might expand to</code></th></tr>
<tr>
<td><code>p5 nits -c su:me</code></td>
<td><code>p4nits -c 12345</code></td></tr>
<tr>
<td><code>p5 grab -c sh:suzanne</code></td>
<td><code>get_changeset -c 12399</code></td></tr>
</table>
<h2>Example</h2>
Putting it all together, your workflow might look like this:
<pre>
$ <b>p5 change</b>
Waiting for Emacs...
Change 445685 created with 1 open file(s).
$ <b>p5 backup</b>
Enter a description for this backup ('.' or EOF when done):
<i>Everything seems to be working. About to send it out for code review.</i>
Created backup at /home/adent/p5.backup/bypass-3/243 ]
$ <b>p5 share</b>
Change 445685 files shelved.
Wrote /home/adent/445685.share
</pre>
<i>Code reviewer points out that I forgot a change to the Makefile, but otherwise everything is okay...</i>
<pre>
$ <b>p5 open -cp Makefile</b>
$ <b>emacs Makefile</b>
$ <b>p5 submit -cp</b>
Submitting change 445685.
Locking 2 files ...
edit //depot/bypass/src/Makefile#314159
edit //depot/bypass/src/one/hoopy/frood.cpp#8
Change 445685 submitted.
</pre>
</body>
</html>
| # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #10 | 10925 | wmesard |
1. p5 share: strip "delete" lines from "p4 shelve" output. 2. Fix minor doc typo. |
||
| #9 | 10776 | wmesard |
1. The "p5 revert" clean up of abandoned files is best-effort. It shouldn't abort if an unlink fails. 2. "p4 shelve" is too verbose for "p5 share" to just echo unfiltered. But throwing it out isn't okay either, since it may contain a useful error message. Compromise: strip out the lines that we're expecting, and don't care about. |
||
| #8 | 10129 | wmesard |
"p5 revert". Like "p4 revert", but deletes abandoned files (files that were added, and then reverted). By default, prompts the user before doing this. With the "-f" flag, doesn't prompt; just does it. Motivation: If you leave abandoned files laying around, tools like Maven will happily keep compiling them...until they break months later causing the build to mysteriously fail. |
||
| #7 | 9969 | wmesard |
Tame the on-by-default echoing of the p4 commands being executed behind the scenes. No one is impressed (except for me, and I can still say "p5 -v CMD..." to see what's going on). |
||
| #6 | 9687 | wmesard |
New option to p5 backup: "-d description" passes a description for the backup rather than prompting the user (a la "p4 submit"). Note: this quietly obsoletes the old ill-considered "-d" flag (which overrode the diff format used in the patch file). |
||
| #5 | 9657 | wmesard |
1. New commands "p5 bdiff" and "p5 bprint" for examining files in a previously saved backup. 2. On a syntax error, only print the relevant line of the Usage message instead of the whole thing. 3. Be less chatty about what commands we're executing to get the job done ("p4 client" and "p4 opened" in particular). Anyone who really cares can say "p5 -v COMMAND". |
||
| #4 | 9610 | wmesard |
1. If "p5 share" sees files in the default changeset, it should print something that looks like a changeset description summary for those files. (It's too easy to have files in the default changeset unintentionally, so it makes sense to have p5 desc/p5 share scream about them.) 2. Add support for "-s" flag to "p5 share" and "p5 desc". (If the user says "p5 desc -s", they probably mean something like "p5 describe -s <all-changesets-including-default>". Thanks to (1), above, that now makes sense.) 3. Make "p5 resolve" honor P5_DIFF_FLAG. |
||
| #3 | 9604 | wmesard |
1. Make "p5 backup" store the depot version number for each file. This necessitated a new backup format. So add file format versioning, and a converter to read old files. 2. Make "p5 backups -l" print that version number. 3. "p4 diff -du" doesn't print the version number. It does print it for the other diff formats (and even for "-du3"). Since "p5 share" uses "p4 diff", add the version number in if necessary. 4. General code clean up. Make pylint happy. (Well...less unhappy.) New "File" class replaces the old list-munging code in Workspace class. |
||
| #2 | 9146 | wmesard |
Alternative implementations of Matt's p5 enhancements from @9100 and @9103: 1. "-u me" should honor P4USER. 2. Add a "p5 shelved" command, analogous to "p5 pending". # review @matt_attaway |
||
| #1 | 9083 | wmesard |
p5 is a drop-in replacement for p4. It provides some new commands, and enhances the behavior of some existing commands. |