S4(1) User Contributed Perl Documentation S4(1)NAMEs4 - Wrapper for subversion program
SYNOPSISs4 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 if the add-fixprop configuration
option is set, do a "s4 fixprop" on all of the new files.
With --no-fixprop, ignore the config setting and run the normal svn
add, do not fixprop. With --fixprop, ignore the config setting and
fixprop.
cat-or-mods
Perform a "svn cat HEAD" if the file has no modifications, else show
the local file with modifications. This is a convient way of editing
what would otherwise need to be a global file. If the file is
unchanged you'll get HEAD (basically a global file), but you can also
edit it locally to make changes.
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.
* Unless --no-ignores is used, any .cvsignore or .gitignore files will
be read and set their directory's svn:ignore property. (See below for
the format of .cvsignore or .gitignore).
* Unless --no-keywords is used, any non-binary file which contains a
CVS metacomment, and which do not have a svn:keyword property will have
the svn:keyword property added.
* Unless --no-autoprops is used, any tsvn:autoprops property on a
parent directory will be applied to all files that have no property of
the same name already set.
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.
commit [-unsafe]
s4 commit generally behaves exactly the same way as svn checkout,
unless the following optional configurations are set:
If commit-block-non-top configuration file option is 'yes', commits
will fail if no path is specified and the current directory is not at
the top of the checkout tree, for example "s4:%Error: Blocked unsafe
commit as not committing from top of tree. Use commit --unsafe to
override." To override this check use "s4 ci ." so a specific path is
specified, or use --unsafe. This message is suppressed if the
directory's URL is trunk/branches/tags, as it is common to have
multiple working areas under a single view, and wish to commit only one
of them.
If commit-block-unversioned configuration file option is 'yes', commits
will fail if unversioned (?) or conflict (C) files are present, for
example "s4: %Error: Blocked unsafe commit as unversioned files
present. Add, repair svn:ignore, or use commit --unsafe to override."
Ideally the unversioned file should be either added or added to a
svn:ignore list so it is no longer unversioned, or alternatively to
override this check use "s4 ci --unsafe".
info-switches path
Given a working file path, prints a non-recursive "svn info" at the
path specified, plus every switch point under the path. Given an URL
prints the info on any views underneath that URL.
merge
s4 merge behaves exactly the same way as svn merge, unless the top
directory that you update contains a file called Project.viewspec. If
Project.viewspec is present, s4 will print an error message. Merging
is not supported in s4 views, as SVN creates many extranious
svn:mergeinfo properties. Instead you should checkout a non-viewed
area, and merge there.
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.
status [--top]
With --top, update the highest subversion directory found at or above
the current directory, rather than the current directory itself.
Otherwise s4 status behaves exactly the same way as svn status.
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 [--top]
s4 update 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.
With --top, update the highest subversion directory found at or above
the current directory, rather than the current directory itself.
workpropdel propname
s4 workpropdel deletes a work-area property of the given name, if it
exists.
workpropget propname
s4 workpropget returns a work-area property of the given name, if it
exists, otherwise "".
workproplist [--xml]
s4 workproplist lists all work area properties, with their values.
workpropset propname propvalue
s4 workpropset sets a work-area property of the given name to the given
value. Work area properties are associated and unique to a given work
area, and stored in the top level .svn directory.
ARGUMENTS--help
Displays this message and program version and exits.
--orig
Pass all commands through to the original version of svn. Useful
when svn has been aliased to a different command.
--svn name
Name of svn executable, or "svn" if not specified. See also
S4_SVN.
--version
Displays program version and exits.
VIEWSPEC FILES
A viewspec file is a text file containing a series of one-line
commands. Anything after a # character is considered a comment.
Whitespace and blank lines are ignored. The commands must be one of:
set VAR VALUE
Set environment variable VAR to VALUE. This is useful for making
abbreviations to be used within the viewspec file, for frequently
typed things such as the name of the svn repository.
include FILE
Read another file that contains viewspec commands. If the filename
does not begin with a slash, it is considered to be relative to the
directory containing the Project.viewspec.
include URL
Read a file out of the SVN repository that contains viewspec
commands.
view URL DIR
Directory DIR will be svn switched to URL.
view URL/(.*) DIR$1
Directory DIR will be svn switched to URL. URL may contain a
parenthesized regexp, which indicates the repository should be
searched for matching files/subdirectories with the matching name.
If found, $1 will be substituted into DIR. The URL parenthesis
must follow all /s, that is they can only match against the final
path component, not a mid-level part of the path.
view URL DIR rev REVNUM
Directory DIR will be svn switched to URL at revision REVNUM. Note
that this is not "sticky" the way CVS was. Svn updates will
override the revision number, while s4 update will not.
REVNUM can also be a date in normal subversion format, as listed
here:
http://svnbook.red-bean.com/nightly/en/svn-book.html#svn.tour.revs.dates
Example: view URL DIR rev {2006-07-01}
view URL@REVNUM DIR
Alternative form of revision pegging. This form must have a
numeric revision.
unview DIR
Ignore any view/unview commands that came above, for directories
that begin with DIR, which may be a Perl regular expression. (The
regexp must match everything from the beginning up through the end
of the directory name.) This may be useful if you have included a
viewspec and want to override some of its view commands.
FILES
.cvsignore, .gitignore
Used by the fixprop command to specify the contents for the
svn:ignore property.
The contents "[recursive]" indicates that everything following that
tag until the end of the file should be applied to all directories
underneath this one.
.svn/workprops
S4 workprop* commands store the work area properties in a workprops
file in the highest .svn directory. This file is in YAML format.
/etc/subversion/config
S4 configuration file, also used by Subversion.
~/.subversion/config
S4 configuration file, also used by Subversion.
CONFIG FILES
The following svn config file options are added by s4.
[s4] add-fixprop = yes
If yes, an "add" command will also do a fixprop. Note this
defaulted to true prior to version 1.041.
[s4] co-under-co = yes
If yes, a "checkout" command will be allowed when inside an
existing checkout. Defaults no.
[s4] commit-block-ignores = *.new *.old *.tmp
List of glob-style regexps of files to ignore for commit-block-
unversioned.
[s4] commit-block-non-top = yes
If yes, a "commit" command will fail when no path is specified and
not in the top of the checkout tree. Defaults no.
[s4] commit-block-unversioned = yes
If yes, a "commit" command will fail when unversioned (?) or
conflicted (C) files are present. Defaults no.
[s4] merge-under-view = yes
If yes, a "merge" command will be allowed when inside a viewed
directory. Defaults no.
ENVIRONMENT
RSVN_CALLING_SSH
Set by this script to 1. See "rsvn" for details.
S4_CONFIG
Filename of additional configuration options. Processed fourth, in
order of /etc/subversion/config, S4_CONFIG_SITE,
~/.subversion/config, and S4_CONFIG files.
S4_CONFIG_SITE
Filename of additional site configuration options. Processed
second, in order of /etc/subversion/config, S4_CONFIG_SITE,
~/.subversion/config, and S4_CONFIG files.
S4_SVN
Name of svn executable, or "svn" if not specified.
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, 1.2,
and 1.6.6, newer versions will probably break.
DISTRIBUTION
The latest version is available from CPAN and from
<http://www.veripool.org/>.
Copyright 2005-2015 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 Version 3 or the Perl
Artistic License Version 2.0.
AUTHORS
Bryce Denney <bryce.denney@sicortex.com> and Wilson Snyder
<wsnyder@wsnyder.org>
SEE ALSO
svn, SVN::S4,
rsvn package, which provides rs4 to run s4 on NFS servers.
perl v5.20.2 2015-01-13 S4(1)
