.\" C4 -- CVS like front end to the Perforce p4 SCM tool.
.\"
.\" Copyright (c) 1997, Neil Russell. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by Neil Russell.
.\" 4. The name Neil Russell may be used to endorse or promote products
.\" derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY NEIL RUSSELL ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED. IN NO EVENT SHALL NEIL RUSSELL BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.TH C4 1
.SH NAME
c4 \- CVS like front end to the Perforce SCM system
.SH SYNOPSIS
.B c4
.IR p4\-command " .\|.\|."
.br
.B c4
.B update|scan|import
[
.B \-adnvx
]
.SH DESCRIPTION
.B C4
provides a CVS like
.I feel
to Perforce's SCM system
.BR p4 .
.B C4
is not a substitute for CVS, in that it does not try to mimic
CVS's command set.
.LP
Like CVS, every file in a user's work-space
.RI ( client )
is writable, and can be modified on an adhoc basis.
.B C4
provides commands that search a client, looking for files that have
been changed, and runs a "\fIp4 edit\fP" command on them.
Any files that are currently opened for edit, and are no longer
different than their repository (\fIdepot\fP) version,
a "\fIp4 revert\fP" command is run on them.
Files that are missing from the client are refreshed ("\fIp4 refresh\fP").
Files that exist in the client that have no matching depot version
are reported, to remind the user to add them, and can optionally be
added automatically.
Files that are out of date with respect to the depot are updated
("\fIp4 get\fP").
.LP
.B C4
also provides support for clients without the use of
environment variables.
Each time
.B c4
is executed, it searches for a "\fB.c4\fP" file,
and incorporates its contents into the environment of any \fIp4\fP
command that it invokes.
The "\fB.c4\fP" file is usually kept in the root directory of a client.
.LP
.B C4
should be used with Perforce version 97.3 or later.
.B C4
will work with older versions, but files will not remain writable,
reducing the usefulness of \fBc4\fP.
.SH "CLIENT CREATION"
Making a new client for use with
.B c4
is slightly different than when using
.B p4
directly.
Here are the steps that should be followed:
.IP 1. 0.3i
Create a client directory.
.IP 2.
Create a file called "\fB.c4\fP" in the client directory with
the following contents:
.RS
.RS
P4PORT=\fI<p4 server port address>\fP
.br
P4CLIENT=\fI<client name>\fP
.RE
.RE
.IP 3.
Change directory to the client directory, and
run the command "\fBc4 client\fP" to create the \fBp4\fP client.
Set up the client as usual.
Modify the "\fBOptions\fP" line to enable "\fBclobber\fP"
and add the option
.nh
"\fBallwrite\fP".
.hy
For example:
.RS
.RS
Options: nomodtime clobber allwrite
.RE
.RE
.IP 4.
Populate the client with the command "\fBc4 update\fP".
Note that "\fBc4 update\fP" should be used in preference to "\fBc4 get\fP";
with the \fIclobber\fP flag set, a modified file may be overwritten,
destroying any changes made to it locally.
.SH COMMANDS
If \fBc4\fP doesn't recognise a command, it just passes the command
and the remaining arguments to \fBp4\fP,
after incorporating the contents of the "\fB.c4\fP" file into the environment.
If \fBc4\fP recognises the command, it is execute locally,
usually invoking several \fBp4\fP commands.
.B C4
adds three new commands:
.TP 0.3i
\fBc4 update\fP
"\fBc4 update\fP" resembles the CVS update command.
It preforms the following actions:
.RS
.IP 1. 0.3i
Recursively scan the current directory and any sub-directories,
gathering information about files, including whether the file has been
modified with respect to its depot version.
.IP 2.
Report any files that are unknown, to remind the user that they
should be added.
This step can be omitted with the \fB\-x\fP option.
Files which are \fIignored\fP are not reported
(see the section
.nh
"IGNORING FILES"
.hy
below).
.IP 3.
Files that are not opened and are different than their respective
depot versions are opened with a "\fBp4 edit\fP" command.
Files that are opened and are now the same as their respective depot
version are reverted with a "\fBp4 revert\fP" command.
Files that are missing from the client are refreshed with a
"\fBp4 refresh\fP" command.
.IP 4.
Files that are out of date with respect to the depot are retrieved
with the command "\fBp4 get\fP".
.RE
.IP
Note that a "\fBc4 udpate\fP" can never overwrite a file because a
modified file is always opened for edit with a "\fBp4 edit\fP"
command before it is retrieved with a "\fBp4 get\fP" command.
If a modified file is out of date, then the user will need to
resolve the differences with a "\fBc4 resolve\fP" command before
submitting.
.TP
\fBc4 scan\fP
"\fBc4 scan\fP" is the same as a "\fBc4 update\fP,
but it does not update out of date files ("\fBp4 get\fP").
.TP
\fBc4 import\fP
"\fBc4 import\fP" adds files that it considers elegible using a
"\fBp4 add\fP" command; these are the same files that were reported
in step 2 of a "\fBc4 update\fP".
Typical usage is to modify the ignored files
(see the section "IGNORING FILES" below), and
run "\fBc4 update\fP"s until those files that are reported are
only those that should be added, then run a "\fBc4 import\fP".
.SH ".C4 FILE FORMAT"
Each time
.B c4
is executed, it searches for a "\fB.c4\fP" file,
and incorporates its contents into the environment of any \fIp4\fP
command that it invokes.
The "\fB.c4\fP" file is usually kept in the root directory of a client.
If a "\fB.c4\fP" file is not found, then the correct \fBp4\fP
environment variables must be set (usually \fBP4PORT\fP and \fBP4CLIENT\fP).
.LP
Every line that begins with an alphabetic character
(`A' \- `Z' or `a' \- `z'),
and contains an `\fB=\fP' is added to the environment.
Every line that begins with a `\fB:\fP' is used as an ignore specification
(see the section
.nh
"IGNORING FILES"
.hy
below).
Every line that starts with a `\fB#\fP' character,
is empty,
or contains only spaces is ignored.
All other lines are currently ignored, but may not be in
future versions of \fBc4\fP.
.SH "IGNORING FILES"
While scanning, if files are found that are not known to the depot,
they are examined to see if they should be ignored.
This is done by matching the
basename (the last name component) of the file to the ignore list for
the current directory and the global ignore list.
The ignore list for each directory is stored in a file called
"\fB.c4ignore\fP" in that directory.
The global ignore list is compiled into
.BR c4 ,
and can be modified or replaced by entries in the \fB.c4\fP file.
Directories are matched with ignore lists also allowing whole
directories to be ignored.
.LP
Lines beginning with `\fB:\fP' in the \fB.c4\fP file are considered
ignore specifications.
An ignore specification is a globbing string as used by the shell;
a file will be ignored if it matches any entry in an ignore list.
A `\fB:\fP' on a line by itself
will cause the entire ignore list to be deleted;
this is generally used to clear the global list and replace it
with new entries.
.LP
The default compiled in global ignore list contains the following:
.RS
*.o, *.a, *.Z, *.gz, .c4, tags, TAGS, core.
.RE
.SH "PERFORCE SUPPORT"
.B C4
uses two as yet undocumented features included in 97.3 and later
releases of
.BR p4 :
.IP allwrite 0.3i
The \fIallwrite\fP client option always creates files that are writable
in the client.
While
.B c4
does not rely on this, much of its usefulness is diminished without it.
.IP "diff -sc"
"\fBc4 diff -sc\fP" combines the effect of "\fBc4 diff -sa\fP"
and "\fBc4 diff -se\fP", to improve the performance of scanning
for changed files.
.B C4
will only use this feature on versions 97.3 and later.
.SH INSTALLATION
.B C4
is a single executable that is usually stored in the same place as
the \fBp4\fP client executable.
.B C4
may be configured as a replacement front end for \fBp4\fP
by creating a shell script called \fBp4\fP, which contains the following:
.RS
#!/bin/sh
.br
export P4COMMAND=\fI<name of real p4 command>\fP
.br
c4 "$@"
.RE
.SH OPTIONS
When one of the local
.B c4
commands is invoked, the following options may be used to modify
its behavior:
.IP \-a 0.3i
Force automatic add.
When used with "\fBc4 update\fP" or "\fBc4 scan\fP"
unknown files will be added rather than reported.
.IP \-d
When given,
.B c4
prints diagnostic messages about what is going on
(used for debugging \fBc4\fP).
Multiple \-d options can be given to get more details.
.IP \-n
Any commands that cause changes will not be executed.
When \fBc4\fP is invoked with the \-n and \-d options,
the user can see what will be executed for a given circumstance.
.IP \-v
Verbose.
Print more messages about what is happening.
This is useful when running \fBc4\fP at the root of a large
client directory structure; it will print the name of each
directory as it is scanned.
.IP \-x
Messages about unknown files usually reported by
"\fBc4 update\fP" and "\fBc4 scan\fP"
are supressed.
.SH "SEE ALSO"
p4(1), "Perforce User Manual".
.SH BUGS
If you modify a file locally that has been changed in the depot,
then when you do a "\fBc4 update\fP", you will get a merge conflict.
.B C4
runs a "\fBp4 edit\fP" command followed by a "\fBp4 get\fP" command
on the file, which will result in messages that may confuse some users;
.B c4
does the right thing though.
You will have to run a "\fBc4 resolve\fP" to deal with the merge issues
before you can submit the file.
Do not run "\fBc4 sync\fP" or "\fBc4 get\fP" as the messages suggest.
.LP
With both "\fBclobber\fP" and "\fBallwrite\fP" options set on the client
(as they should be when using \fBc4\fP),
you should not use "\fBc4 get\fP" to update files from the depot if
you have made local changes \(em your changes will be overwritten.
Use "\fBc4 update\fP".
.LP
If you run \fBc4\fP in a directory that is empty in the depot,
such as a directory with only new files in it, you may see
messages like ".\|.\|. \- no such file(s)".
Don't worry about them.