NAME
s4 - Wrapper for subversion program
SYNOPSIS
s4 help
s4 <any svn command>
i.e.: s4 add <file>
s4 delete <file>
s4 diff <file>DESCRIPTION
S4 provides a wrapper to subversion that extends several of the commands. It understands all svn commands; you may simply use "s4" whereever you would normally type "svn".
In many cases, S4 simply runs "svn" with the same arguments as you passed to s4. If you want s4 to run a particular version of svn, you can either set the environment variable S4_SVN to the name of the subversion binary, or use --svn=SVN_BINARY to override the default.
COMMANDS
Any command not listed here is passed directly to subversion.
add
Perform normal subversion add, then do a "s4 fixprop" on all of the new files.
With --raw, just run the normal svn add, do not fixprop.
checkout
s4 checkout behaves exactly the same way as svn checkout, unless the top directory that you check out contains a file called Project.viewspec. If Project.viewspec is present, s4 does the following steps instead.
1. Check out/update the top directory with --non-recursive, so that subdirectories are not fetched.
2. Parse the Project.viewspec file to see how the working area should be laid out. Project.viewspec specifies which directories in your working area should be mapped to which URLs in the repository. If any problems are found during viewspec parsing, s4 ends with an error.
3. Do a series of "svn switch" commands to build the working area. In normal svn, you cannot switch a directory unless it is already in the working copy, and checked in. S4 works around this (see SVN::S4::ViewSpec.pm if you must know), so the viewspec can put any directory at any location.
fixprop
Processes all files and directories passed as arguments. Any .cvsignore or .gitignore files will be read and set their directory's svn:ignore property. Any file which contains a CVS metacomment, and which do not have a svn:keyword property will have the svn:keyword property added.
With -N or --non-recursive, don't recurse across directories.
With --personal, only change files the current user has added, or was the last author of.
help subcommand
Invokes subversion help. With a subcommand modified or specific to s4, also prints s4 help on that command.
help-summary
Prints a summary of all Subversion and S4 commands.
info-switches path
Prints a non-recursive "svn info" at the path specified, plus every switch point under the path.
quick-commit|qci PATH
s4 quick-commit, or "qci" for short, performs a commit of the current tree. Unlike the normal commit command, qci will not create lock files, and so may be significantly faster on large trees. It is semantically equivelent to doing a svn status, then only commiting the files listed as changing rather then committing the entire tree.
scrub [--revision REV] [--url URL] PATH
s4 scrub turns a "used" source tree into a pristine one, as efficiently as it can.
WARNING: That means that it will permanently throw away all the changes you've made in your working copy. Is that really what you want? If not, stop right here.
It first does a "svn status" to look for any files that aren't checked in, anything that has been added but not checked in, etc. and erases/reverts them all. Then it updates the tree to the specified revision. When it's done, your tree should look exactly like a clean checkout. (If not it's a bug.)
You probably ask, why not just do "svn revert -R" or "svn update -r". Those commands tend to leave some junk behind, or sometimes they get jammed (e.g. object of the same name already exists). Also svn is understandably very conservative about erasing a file or directory that it is not SURE is checked in already. But this command is not; it's happy to blow away the changes in your working copy...in fact that's its primary job.
snapshot
s4 snapshot generates a compact patch file that describes how to reproduce a svn working copy exactly, including: - modified files (text or binary) - files and dirs that are not yet checked in - inconsistent svn revision numbers throughout the tree - property changes on files and dirs - svn switched files and directories - svn externals
The output of the s4 snapshot command is Bourne shell script that contains commands to create a new working copy or modify an existing one, run some svn commands, and apply all your changes. It is sort of like a "super-patch." When the script is done, the new working should match the original in every respect. If anything prevents such a patch from being created, it will die with an error. For example, if your working copy has deleted files or directories, or other unhealthy things, the snapshot code may not know how to recreate it so it will refuse to make a patch.
Snapshots can be useful for backing up your work (without having to check in), for bug reporting, or any time you want to "save your state" so that you can recreate your area later, or in another place.
Changes in text files appear in svn diff format. Changes in binary files are TARred, base64 encoded, and the encoded text appears in the patch file. I keep calling the output file a "patch" because in fact it can be used with the patch program. But it's also a shell script that recreates the svn state as well.
Example of making a snapshot and restoring: s4 checkout -r22100 http://svn.collab.net/repos/svn/trunk/www svnwebsite cd svnwebsite # add some files, modify some files, svn update to other revisions s4 rm images cp index.html myindex.html s4 add myindex.html echo Finish my new favorite feature >> roadmap.html echo as soon as possible >> roadmap.html s4 snap > /tmp/snapshot # The snapshot is a script to recreate these changes. # Let's run it. s4 revert -R . ; rm -f myindex.html # make it clean again bash /tmp/snapshot
update
s4 checkout behaves exactly the same way as svn checkout, unless the top directory that you update contains a file called Project.viewspec. If Project.viewspec is present, s4 does the steps described in the "checkout" section above.
In most updates, the viewspec file has not changed drastically, so there is no need to redo the svn switches, and s4 will do svn update. But if the tree structure changes, s4 will redo the switch commands.
ARGUMENTS
FILES
- .cvsignore, .gitignore
-
Used by the fixprop command to specify the contents for the svn:ignore property.
BUGS
- S4 relys on some obscure features of Subversion, in that s4 needs to to modify the .svn directory to create empty directories and svn externals that switch to them. This has only been tested on Subversion 1.1 and 1.2, newer versions will probably break.
DISTRIBUTION
The latest version is available from CPAN and from http://www.veripool.org/.
Copyright 2005-2008 by Bryce Denney and Wilson Snyder. This package is free software; you can redistribute it and/or modify it under the terms of either the GNU Lesser General Public License or the Perl Artistic License.
AUTHORS
Bryce Denney <bryce.denney@sicortex.com> and Wilson Snyder <wsnyder@wsnyder.org>