repository - Using the Perl repository
-This document describes what a Perl Porter needs to do
-to start using the Perl repository.
+=head1 Synopsis
+
+First, we assume here that you have already decided that you will
+need B<write> access to the repository. If all you need is B<read>
+access, there are much better ways to access the most current state of
+the perl repository, or explore individual files and patches therein.
+See L<perlhack> for details.
+
+This document describes what a Perl Porter needs to do to start using
+the Perl repository.
=head1 Prerequisites
ordinary commands on the repository. When you want to start a
session using the repository, use the command
- ssh -l perlrep -f -q -x -L 1666:127.0.0.1:1666 sickle.activestate.com
-foo
+ ssh -l perlrep -f -q -x -L 1666:127.0.0.1:1666 sickle.activestate.com foo
If you are not using the default filename of F<~/.ssh/identity>
to hold your perl repository private key then you'll need to add
=over 4
-=item B<-l perl>
+=item B<-l perlrep>
-Use a remote username of perl. The account on the repository which
-provides the end-point of the ssh tunnel is named "perl".
+Use a remote username of perlrep. (The account on the repository which
+provides the end-point of the ssh tunnel is named "perlrep".)
=item B<-f>
=item sickle.activestate.com
-This is the canonical IP name of the host on which the perl
-repository runs. Its IP number is 199.60.48.20.
+This is the canonical name of the host on which the perl repository
+resides.
=item foo
=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 host's short name)
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.
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.
Once these three environment variables are set, you can use the
perforce p4 client exactly as described in its documentation.
After setting these variables and connecting to the repository
-for the first time, you should use the C<p4 user> and
-C<p4 client> commands to tell perforce the details of your
-new username and your new client workspace specifications.
+for the first time, you should use the C<p4 user> command to
+set a valid email address for yourself. Also use the C<p4 client>
+command to specify your workspace specifications for each
+individual client from which you will interact with the repository.
=head1 Ending a Repository Session
Generating a patch for change#42 is done as follows:
- % p4 describe -du 42 | p4desc | p4d2p > change-42.patch
+ % p4genpatch 42 > change-42.patch
-F<p4desc> and F<>p4d2p> are to be found in //depot/perl/Porting/.
+F<p4genpatch> is to be found in //depot/perl/Porting/.
The usual routine to apply a patch is
% p4 describe -du 12345 # show change 12345
Note: the output of "p4 describe" is not in proper diff format, use
-the F<Porting/p4d2p> to convert.
+the F<Porting/p4genpatch> to get a diff-compatible format.
+(Note that it may be easier to get one already prepared: grep
+L<perlhack> for APC, and append eg "/diffs/12345.gz" to one of the
+URLs to get a usable patch.)
% p4 diff -se ./... # have I modified something but forgotten
# to "p4 edit", easy faux pas with autogenerated
More updates by Jarkko Hietaniemi, jhi@iki.fi, 28 June 2001.
-=cut
-
+Perforce clarifications by Randall Gellens, rcg@users.sourceforge.net, 12 July 2001.
+=cut
projects / p5sagit/p5-mst-13.2.git / blobdiff