Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
S4(1)		      User Contributed Perl Documentation		 S4(1)

       s4 - Wrapper for	subversion program

	   s4	     help

	   s4 <any svn command>
	      i.e.:  s4	add <file>
		     s4	delete <file>
		     s4	diff <file>

       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.

       Any command not listed here is passed directly to subversion.

       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

       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.

       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 if you must	know), so the viewspec can put any
       directory at any	location.

       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.

       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.

       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	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.

       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
	  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

   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.

	   Displays this message and program version and exits.

	   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

	   Displays program version and	exits.

       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

       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
	   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.

       .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.

	   S4 workprop*	commands store the work	area properties	in a workprops
	   file	in the highest .svn directory.	This file is in	YAML format.

	   S4 configuration file, also used by Subversion.

	   S4 configuration file, also used by Subversion.

       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-

       [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.

	   Set by this script to 1.  See "rsvn"	for details.

	   Filename of additional configuration	options.  Processed fourth, in
	   order of /etc/subversion/config, S4_CONFIG_SITE,
	   ~/.subversion/config, and S4_CONFIG files.

	   Filename of additional site configuration options.  Processed
	   second, in order of /etc/subversion/config, S4_CONFIG_SITE,
	   ~/.subversion/config, and S4_CONFIG files.

	   Name	of svn executable, or "svn" if not specified.

       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.

       The latest version is available from CPAN and from

       Copyright 2005-2016 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.

       Bryce Denney <>	and Wilson Snyder

       svn, SVN::S4,

       rsvn package, which provides rs4	to run s4 on NFS servers.

perl v5.32.1			  2016-12-03				 S4(1)


Want to link to this manual page? Use this URL:

home | help