p5: a set of tools for use with Perforce.

Enhanced commands

• p5 describe is an enhanced version of p4 describe. It will print the contents of added files, instead of merely showing a diff of modified files.
• p4 submit insists that you manually delete shelved files before it will let you submit a changeset. p5 submit automatically deletes the shelf.
• p4 revert 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 compiles every Java source it can get its hands on. p5 revert notices the abandoned files and asks if they should be deleted. With the -f option, it doesn't ask, it just deletes them.
• The default p4 diff format is usually not what one wants. If the environment variable P5_DIFF_FLAG is set (e.g., export P5_DIFF_FLAG=-du, export P5_DIFF_FLAG=-dc10, etc.), that will be used by default. This applies to all the p5 commands that generate diffs. (This is similar to P4DIFF, but some people find P5_DIFF_FLAG more convenient to use.)
• p5 changes has several shortcuts for common command line options:
  • -u me is shorthand for -u your-user-id. (It's also fun to say out loud.) This shortcut works for the other commands that take -u as well (p5 branches, p5 clients, p5 labels, p5 opened).
  • The status argument can be abbreviated:
    

    p5 command	Expands to
    p5 changes -s p	p4 changes -s pending
    p5 changes -s sh	p4 changes -s shelved
    p5 changes -s su	p4 changes -s submitted

    
    
  • If that's still too much typing for you, there's p5 pending and p5 shelved which take all the same arguments as p5 changes, but default to -u me and the appropriate value for -s.
  • Finally, here can be specified for the optional client argument, as a shortcut for the current workspace.
• To summarize by example:
  

  p5 command	Might expand to
  p5 shelved	p4 changes -u adent -s shelved
  p5 changes -c here	p4 changes -c bypass3
  p5 pending -c here	p4 changes -u adent -s pending -c bypass3

• For people who can't remember that p4 describe and p4 change do not take the -c option, the p5 versions of these commands allow it.
• Similarly, the lower-case -c option to p4 changes is inconsistent with the other commands, so p5 changes accepts upper-case -C as well.

Enhanced changeset syntax

    -c (p|su|sh)[:userid][:nth]

For example, you can type -cp and p5 will replace that "p" 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:

• p5 share -cp
• p5 change -cp
• p5 submit -cp

-c sh and -c su do the same for the most recently shelved and submitted changesets.

If you specify an optional userid, p5 will show the most recent changeset for that user, instead of for the current workspace. So, for example, p5 describe -csu:suzanne will show Suzanne's most recently submitted changeset. The me shortcut works here, too. So p5 describe -S -c sh:me will show your most recently shelved changeset in any workspace.

Finally, an optional nth specifier allows you to select the nth most recent changeset. For example, p5 describe -c su:2 will show the penultimate submission from the current workspace. p5 describe -c su:me:2 will show your penultimate submission across all workspaces.

Enhanced changeset specifications also work with p5 unshelve -s. For example, if you just shelved something in one workspace, you can unshelve it in another by saying p5 unshelve -s sh:me.

Workspace Backups

Creating a backup

p5 backup creates a tarball of all currently open files, and stores it in ~/p5.backup/workspace/backup, where workspace is the name of the current Perforce client, and backup 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 comment.txt file.

Here are the command line options in decreasing order of usefulness:

• -e 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 -e to the command line.)
• -f says don't prompt for a description. You can still create one later with -e.
• -b backup-name says to use the indicated backup-name instead of using the automatically incrementing number.
• -c changeset says to only backup files from the indicated changeset.
• -d description specifies the description on the command line instead of prompting the user.
• -C client says to backup the indicated workspace, instead of the current one.
• file... says only backup the indicated files.

Restoring from backup

    p5 restore [-b backup-name] [-B src-client] [-c changeset] [-C client] [-n] [-p | file...]

    $ p5 backup -f
    $ p5 revert ...
    $ p5 restore

• -b backup-name 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.
• -n says don't actually do the restore. Just show a preview of what would be done.
• -B 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 p4 integrate.)
• -p 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 (-B) or on an older revision of the files. As is always the case when using patch(1), inspect the results carefully.

Examining a backup

    p5 bdiff  [-b backup-name] [-B src-client] [-d] file...
    p5 bprint [-b backup-name] [-B src-client] [-q] [-r] file...

To address this, the -r flag says to treat the files as paths relative to the root of the backed up workspace, without considering the current workspace at all. Note: On Windows machines, -b backup-name is must be specified. On other systems, it defaults to the most recently created one.

Listing all backups

p5 backups lists the backups for the current workspace, along with their descriptions.

• -b backup-glob says to only show those backups with names matching the indicated pattern using shell-style globbing. So, e.g., say

       p5 backups -b '02?'
  

  to display backups 20-29.
• -m max 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).
• -l prints a long listing, showing the description and contents of each backup.

Code review

Sending code out for review

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 changeset.share. 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:

    export P5_SHARE_FILE=$HOME/review/%s.desc 

• -o says don't create a diff file, and don't shelve anything; just write the diff to the standard output.
• -c says only include files from the indicated changeset.
• The other options are passed to p4 diff.

Viewing changesets

This is a DWIM command. It runs one of p5 share, p5 describe or p5 describe -S 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.

Use with other Perforce utilities

  export P5_WRAPPED=grab=get_changeset:nits=p4nits

Example

    $ p5 change
    Waiting for Emacs...
    Change 445685 created with 1 open file(s).
    $ p5 backup
    Enter a description for this backup ('.' or EOF when done):
      Everything seems to be working. About to send it out for code review.
    Created backup at /home/adent/p5.backup/bypass-3/243 ]
    $ p5 share
    Shelving changes: @=445685
    Wrote /home/adent/445685.share
    

    $ p5 open -cp Makefile
    $ emacs Makefile
    $ p5 submit -cp
    Submitting change 445685.
    Locking 2 files ...
    edit //depot/bypass/src/Makefile#314159
    edit //depot/bypass/src/one/hoopy/frood.cpp#8
    Change 445685 submitted.