p4prompt.pod #2

=head1 NAME

p4prompt - Munge tcsh $prompt values to include client name

=head1 SYNOPSIS

B<p4prompt> [B<-c>] [B<-e>] [B<-p>] [B<-->] I<prompt-value>

B<p4prompt> [B<-v>]

See L</"EXAMPLES"> for more useful incantations.

=head1 DESCRIPTION

Replaces substrings of the form B<%@>[B<0>[I<n>]] in I<prompt-value> with
a string representing the current directory.
The replacement is similar to that of "%c" (and its variants) in the
tcsh(1) C<$prompt> variable, except that if the current directory
appears to be in a Perforce client workspace, then the root of the
client workspace is represented by "@I<client>".

Client substitution has precedence over tilde substitution.
If C<$PWD> does not appear to belong to a client, then the "%@" is
simply replaced with a "%c" for tcsh(1) to expand (unless B<-c> is specified;
see below).

Unless B<-p> is specified, the client is determined by searching for a file
with the name specified by the value of the C<$P4CONFIG> environment variable,
first in C<$PWD>, and then in the directories obtained by stripping off
its trailing path components successively.
If such a file is found, then it is assumed to reside within the client root
directory, and the client name is determined from the
line beginning "P4CLIENT=" in the file.

I<p4prompt> is allegedly intelligent about replacing "%@" around other
formatting sequences.
For example, "%%@" and "%{%@%}" pass through unmunged
(unless B<-c> is specified).

=head1 OPTIONS

=over 4

=item B<-c>

Run in csh(1)-friendly mode.
"%@" is always expanded, even if we don't appear to be in a
client workspace, because "%c" is meaningless in plain csh(1).
The current user's home directory is replaced with "~" whenever it
prefixes $PWD.
Furthermore, the "%%" string is resolved to a single "%", so that you can
put a literal "%@" in the prompt string using "%%@".

=item B<-e>

Missing directory components are replaced with "..." rather than "<I<n>>".
This emulates the behavior when C<$ellipsis> is set in tcsh(1), since
I<p4prompt> can't access C<$ellipsis> directly.

=item B<-p>

If I<p4prompt> is compiled with the Perforce API linked-in, then this option
causes the current client and client root to be determined through B<p4 info>.
This is more trustworthy, but it might block if the connection to the server
is mal-functional, and therefore it is not recommended by default.
The output of B<p4prompt -v> will include the string "-p enabled" if and
only if I<p4prompt> was compiled with this option available.

=item B<-v>

Print the version number and exit.

=item B<-->

Denotes the end of options.
Useful when I<prompt-value> begins with "-".

=back

=head1 EXAMPLES

This is what I recommend for a general F<.cshrc> file:

	if ( $?tcsh ) then
		alias cwdcmd \
		 'set prompt="`p4prompt '\''%@02 %h%# '\''`"'
		cwdcmd
	else
		alias cwdcmd \
		 'set prompt="`p4prompt -c '\''%@02 \\\!% '\''`"'
		alias cd 'cd \!:*; cwdcmd'
		alias pushd 'pushd \!:*; cwdcmd'
		alias popd 'popd \!:*; cwdcmd'
		cwdcmd
	endif

It's actually safer if you specify an absolute path to I<p4prompt> (wherever
it's installed on your system), and check that it's available before
relying on it, like this:

	if ( -x /usr/local/bin/p4prompt ) then
		alias cwdcmd \
	 'set prompt="`/usr/local/bin/p4prompt '\''%@02 %h%# '\''`"'
		cwdcmd
	else
		set prompt='%c02 %h%# '
	endif

=head1 BUGS

=over 2

=item *

I<p4prompt> assumes that every client has a C<$P4CONFIG> file at the
client root which sets C<P4CLIENT>, and that no other C<$P4CONFIG>
files exist within clients, which is a good discipline to follow anyway.
Use the B<-p> option if these assumptions are known to be invalid.

=item *

I<p4prompt> trusts C<$PWD> and C<$HOME>.

=item *

As with "%c" and friends in tcsh(1), symbolic links in C<$PWD> are treated
as real directories.
In particular, if you B<cd>'ed to the current client workspace via a
symbolic link from outside the client, then your prompt will not indicate
the current client.

=item *

I<p4prompt> is written in C because performance is important.
That makes it somewhat difficult to maintain.

=item *

I<p4prompt> is not portable to non-UNIX systems, mostly due to assumptions
regarding the format of file path names.
This is believed not to be important, because tcsh(1) and csh(1) are
not in widespread use under other systems anyway.

=item *

I<p4prompt> is aggressive about recovering from errors, since failing
generally causes the prompt to go away, which is unfriendly.

=back

=head1 SEE ALSO

p4(1), tcsh(1), csh(1)

=head1 AUTHOR

Anders Johnson <F<anders@ieee.org>>