Re: [randy@qualcomm.com: Corrections for ' repository - Using the Perl repository ']

Message-Id: <p05100301b773e9751c04@[129.46.176.61]>

p4raw-id: //depot/perl@11338

1 files changed, 44 insertions, 16 deletions

diff --git a/Porting/repository.pod b/Porting/repository.pod
index bbe537a7ba..54960bff29 100644
--- a/Porting/repository.pod
+++ b/Porting/repository.pod
@@ -191,20 +191,28 @@ the section above on the B<-L 1666:127.0.0.1:1666> option to ssh.
 =item P4CLIENT
 
 The value of this is the name by which Perforce knows your
-host's workspace. You need to pick a name (for example, your
-hostname unless that clashes with someone else's client name)
+host's workspace. You need to pick a name (normally, your
+Perforce username, a dash, and your hostname)
 when you first start using the perl repository and then
-stick with it. If you connect from multiple hosts (with
-different workspaces) then maybe you could have multiple
-clients. There is a licence limit on the number of perforce
-clients which can be created. Although we have been told that
-Perforce will raise our licence limits within reason, it's
-probably best not to use additional clients unless needed.
-
-Note that perforce only needs the client name so that it can
-find the directory under which your client files are stored.
+stick with it.
+
+Perforce keeps track of the files you have on your machine.  It
+does this through your client. When you first sync a version of a
+file, the file comes from the server to your machine.  If you sync
+the same file again the server does nothing because it
+knows you already have the file.
+
+You should NOT use the same client on different machines.  If you do
+you probably won't get the files you expect, and may end up with
+nasty corruption.  Perforce allows you to have as many clients as
+you want. For example, sally-home, sally-openbsd, sally-laptop.
+
+Also, never change the client's root and view at the same time.
+See C<http://www.perforce.com/perforce/doc.002/manuals/p4guide/04_details.html#1048341>
+
 If you have multiple hosts sharing the same directory structure
-via NFS then only one client name is necessary.
+via NFS then you may be able to get away with only one client name,
+but be careful.
 
 The C<p4 clients> command lists all currently known clients.
 
@@ -213,10 +221,28 @@ The C<p4 clients> command lists all currently known clients.
 This is the username by which perforce knows you. Use your
 username if you have a well known or obvious one or else pick
 a new one which other perl5-porters will recognise. There is
-a licence limit on the number of these usernames. Perforce
-doesn't enforce security between usernames. If you set P4USER
-to be somebody else's username then perforce will believe you
-completely with regard to access control, logging and so on.
+a licence limit on the number of these usernames, so be sure not
+to use more than one.
+
+It is very important to set a password for your Perforce username,
+or else anyone can impersonate you.  Use the C<p4 passwd> command
+to do this.  Once a password is set for your account, you'll need
+to tell Perforce what it is. You can do this by setting the
+environment variable P4PASSWD, or you can use the C<-P> flag
+with the C<p4> command.
+
+There are a few techniques you can use to avoid having to either
+set an environment variable or type the password on every command.
+One is to create a shell alias, for example, in bash, add something like
+    alias p4='p4 -P secret'
+to your F<.bash_profile> file.  Another way is to create a small shell
+script, for example
+    #!/bin/bash
+    p4 -P secret $@
+And use this instead of running C<p4> directly.
+
+With either of these, be sure the file containing your password
+(the F<.bash_profile> or shell script file) is only readable by you.
 
 The C<p4 users> command lists all currently known users.
 
@@ -377,6 +403,8 @@ Slightly updated by Simon Cozens, simon@brecon.co.uk, 3 July 2000.
 
 More updates by Jarkko Hietaniemi, jhi@iki.fi, 28 June 2001.
 
+Perforce clarifications by Randall Gellens, rcg@users.sourceforge.net, 12 July 2001.
+
 =cut