README #1

		p4 - a wrapper for the Perforce p4 command.

		Rick Richardson <rickr@mn.rr.com>
			

INTRODUCTION
------------
This is a wrapper for the Perforce "p4" command.  It extends "p4" by
adding CVS-style commands like import, commit, update, and annotate to
the regular set of Perforce commands.  In addition, the Perforce "p4
submit" command was missing fundamental features, so this wrapper
augments that command as well.

All regular Perforce commands are available thru this wrapper, so
there is no reason not to wrap the p4 command as no functionality will
be lost.

As of 07/19/2001, this is a work in progress.  Some of the lesser used
CVS options are being added as time permits, and of course there will
be bugs that won't show up until more people use the wrapper.

INSTALLATION
------------

Assuming that Perforce's "p4" command is in /usr/bin, and your usual
search $PATH puts /usr/local/bin before /usr/bin, then just type "make
install" (as root, if necessary).  Another way is to move your p4
binary to "p4.orig", then edit the script and change the P4 variable to
point to p4.orig, then copy the script to any convenient directory in
your $PATH.

EXTENDED COMMANDS
-----------------
Most extended subcommands take file and/or directory arguments,
recursing on the directories.  The Perforce "/..." syntax is not
required in order to recurse on directories. If no arguments are
supplied to such a command, it will recurse on the current directory
(inclusive) by default.  This is the surprise-free behavior CVS users
are used to, rather than the Peforce behavior where the whole tree is
actioned on regardless of where your are in the tree.

So far, the extended list of commands is:

p4 annotate [options] file|dir ...
	Generate an annotated listing of each "file", showing who to
	blame for each changed each line.  The underlying engine for
	this command is Bob Sidebotham's p4pr.perl script.

	Options:

	-R		Process directories recursively (default).
	-l		Local directory only (not recursive).
	-r rev		Annotate the revision specified by "rev", which
			may be a revision number, a label, or any of the
			Perforce style "#"/"@" revision specifiers.

	-D date		Get the version which was current as of date.
			Date is not restricted to the weak Perforce syntax;
			it can be in any of the allowable date(1) formats.

p4 checkout dir ...
	Currently, checks out all source code under the listed
	directories.

p4 commit [options] [file|dir] ...
	A lot like the CVS commit command.  Submit files which have been
	changed, issuing "p4 edit" commands as needed.  Best used when you
	like to operate with the "allwrite" option on your workspace.
	But certainly a savior if you made changes to files and manually
	overrode the readonly file permission (who hasn't?).

	Options:

	-R		Process directories recursively (default).
	-l		Local directory only (not recursive).
	-f		Force the file to be committed; disables recursion.
	-F msgfile	Read the log message from msgfile.
	-m msg		The -m msg option is use to specify the log message,
			in which case the operation is non-interactive.

p4 import
	Add all files in current directory and below to the depot.
	CVS style repository vendortag releasetag options are not
	currently handled.

p4 log [file|dir] ...
	Produce a long listing of the file(s) revision history.

p4 rename from to
	Rename the file "from" to name "to".
	N.B. it is currently NOT SAFE to do this:
		p4 rename xxx yyy
		p4 rename yyy xxx
	If you decide you want to rename something back to its original
	name, then you must rename it three times:
		p4 rename xxx yyy
		p4 rename yyy zzz
		p4 rename zzz xxx
	This appears to be a problem within Perforce and has been mentioned
	on the Perforce mailing lists, but Perforce has not offered a
	solution as far as I can tell.

p4 stat [file|dir] ...
	Short and sweet status summary.  Stuff you need to get, and stuff
	you need to commit.

p4 submit [p4options] [-m logmsg] [p4filespec] ...
	Augmented version of p4 submit that allows more than one P4-style
	file specification.  It also allows the changelog description to be
	specified with -m logmsg.

	The limitation of one p4filespec with the Perforce version of this
	command is a glaring weakness in Perforce that they have not
	addressed despite repeated requests from users going back to 1999.
	For this reason, the augmented version of p4 submit is supplied,
	even though I prefer to use the p4 commit variation.

p4 update [options] [file|dir] ...
	Get the latest versions of files from the repository (sync).
	Then resolve any conflicts.

	Options:

	-C		Overwrite locally modified files with clean depot
			copies.

	-r rev		Get the revision specified by "rev", which may
			be a revision number, a label, or any of the
			Perforce style "#"/"@" revision specifiers.
			Unlike CVS, this option is NOT STICKY.

	-D date		Get the version which was current as of date.
			Date is not restricted to the weak Perforce syntax;
			it can be in any of the allowable date(1) formats.
			Unlike CVS, this option is NOT STICKY.

p4 ws <wsname> [server:port [user [passwd]]]
	Create a new workspace named "<wsname>" in the current directory.
	The default server:port is perforce:1666, but may be overridden.

	You do not need to set any environment variables in order to use
	this command.  It is recommended, however, that you eventually
	set P4CONFIG=.p4config in your .profile.  This is so that the
	unadorned Perforce p4 command will work properly in case you stop
	using this wrapper.

QUICKER START
-------------

Make a workspace to hold (potentially all of) the company wide source tree...

	mkdir work
	cd work
	p4 ws my-work-tree

Populate the tree with everything that other people committed (optional)...

	# current dir is now, say, $HOME/work
	p4 update

Add your project...

	mkdir myjunk
	cd myjunk
	# current dir is now, say, $HOME/work/myjunk
	echo foo > xxx.c
	echo bar > yyy.c
	p4 add *.c
	p4 commit

Or add it this way...
	mkdir myjunk
	cd myjunk
	# current dir is now, say, $HOME/work/myjunk
	echo foo > xxx.c
	echo bar > yyy.c
	p4 import

Make some changes...
	echo foobar > xxx.c
	echo barfoo > yyy.c
	p4 commit