readme.txt #1

P4 Shelve/Unshelve Utility

Last Revision: 11/26/2005
Author: Chris Stoy

Send bugs/revisions to Chris Stoy (cstoy@nc.rr.com)


INTRODUCTION

These scripts provide a means for "shelving" an active changelist, 
allowing you to work on an unrelated change, then "unshelve" your
previous changelist and continue working from there.


REQUIREMENTS

p4_shelve requires:
    * Python 2.4 (www.python.org)
    * P4Python (public.perforce.com/guest/robert_cowham/perforce/API/python/index.html)
    
to build stand-alone executables, you will also need:
    * py2exe (www.py2exe.org)
    

HOW IT WORKS

p4_shelve works by creating a branch in your depot and moving the files
in the shelved changelist into that branch.  It then reverts the files
from your changelist.  Files that are marked for add in your changelist
are added to the branch, those marked for delete are deleted. This allows
us to maintain a revision history for the files in the shelf.  

p4_unshelve works by doing a reverse integration from the branch spec
created by p4_shelve.  The integrated files are put into the default changelist.


USAGE

python p4_shelve.py [options]
python p4_unshelve.py [options] <shelve branch spec>

For both p4_shelve and p4_unshelve, specify the "-h" or "--help" option
to see a detailed list of options for each command.

Before you can use p4_shelve, you need a place to put the shelves in your
depot.  By default, this is //depot/shelves, though you should specify where
you want it using the "-s <depot-path>" command line option.

p4_shelve creates a new branch spec every time it is run and maps the files
from the change list through that branch spec.  The name of the branch spec
follows the format:

    shelve_<user name>_<date>_<time>
    
So, an example branch spec would be:

    shelve_Chris_Stoy_20051121_1531
    
    
To shelve your default changelist using all defaults:
    
    python p4_shelve.py
    
If you wish to place the shelves in //depot-shelves/, you would use:

    python p4_shelve.py -s//depot-shelves
    
To shelve changelist 256 to //depot/shelves/chriss, you would use:

    python p4_shelve.py -e256 -s//depot/shelves/chriss
    
    
BE SURE that the depot path you specify is mapped in the client view
the changelist exists in.  That is, if you want to use //depot/shelves/chriss
to store your shelves, then that needs mapped in your client spec. If the
path is not mapped, then your files are placed in a new change list and
the command will fail.

Unshelving works by taking the name of the branch spec created by p4_shelve.

For example,
    
    python p4_unshelve.py shelve_Chris_Stoy_20051121_1531
    
The files are integrated into the default changelist on your client.


USING WITH P4V

P4V provides a means for integrating external commands such as p4_shelve.
This allows you to shelve/unshelve directly from P4V.

For example, to install p4_shelve in P4V, open the Tools->Custom Tools menu.
From the dialog, select "Add Tool...".  Name the tool "Shelve". Be sure to
check "Add to applicable conext menus".  This allows you to right click on a
changelist and shelve from there.  For the application, select your install of
Python (pythonw.exe on Windows.)  In arguments, first enter the path for
'p4_shelve.py'.  You want to add the command line arguments for the port, user,
workspace, shelve depot path, and the pending changelist.  For example:

C:\p4_shelve\p4_shelve.py -p$p -c$c -u$u -s//depot/shelves -e%p

Finally, check "Refresh P4V upon completion".  Close the dialog and you will find
the "Shelve" command in the Tools menu and also in the pop-up menu when you right-
click on a pending changelist.