ossp-pkg/svs/svs.pod
##
## OSSP svs -- Stupid/Silly/Simple Versioning System
## Copyright (c) 2003-2009 Ralf S. Engelschall <rse@engelschall.com>
## Copyright (c) 2003-2009 The OSSP Project <http://www.ossp.org/>
##
## This file is part of OSSP svs, a stupid/silly/simple versioning
## system which can found at http://www.ossp.org/pkg/tool/svs/
##
## Permission to use, copy, modify, and distribute this software for
## any purpose with or without fee is hereby granted, provided that
## the above copyright notice and this permission notice appear in all
## copies.
##
## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
## SUCH DAMAGE.
##
## svs.pod: manual page (language: POD)
##
=pod
=head1 NAME
B<svs> - B<Stupid/Silly/Simple Versioning System>
=head1 VERSION
B<OSSP svs> SVS_VERSION_STR
=head1 SYNOPSIS
=over 0
=item B<svs> vi I<file> [...]
=item B<svs> diff [I<file>|I<dir> [...]]
=item B<svs> backout [I<file>|I<dir> [...]]
=item B<svs> status [I<file>|I<dir> [...]]
=back
=head1 DESCRIPTION
B<OSSP svs> is a simple frontend to diff(1) and patch(1). It provides a
convenient way for working with changes on textual files if no history
tracking and version control is necessary. This is especially the
case when having to patch pristine vendor sources for portability or
bugfixing reasons.
B<svs> solves the following primary issues:
=over 4
=item Writable and preserved files
It is often the case that one enters the editor for editing a file, just
to have to recognized that it is not writable ("C<chmod u+w >I<file>)
or the original content was not (or not correctly) preserved before
("C<cp> I<file> I<file>C<.orig>"). Simply running "C<svs vi>" instead
of "C<vi>" and not having to remember those subtle problems is both
convenient and leads to consistent results.
=item Re-editing of files
Usually the patching of vendor sources is an iterative process where one
has to both re-edit files and even perform the whole edit/diff/patch
cycle multiple times. Here it is important that no already applied
changes are lost (overwritten C<*.orig> files, etc) and that the changes
can be correctly backed out again.
=item Index style
For portability and consistency reasons it is good if all patches use
the same style. This means that all hunks should be preceded by an
C<Index> header and that the change is represented with the concise
I<unified diff> format with at least 3 lines of context.
=item New or removed files
While patch files for changed vendor files are harmless, added or
removed vendor files are special cases both for the patch application
and removal. B<svs diff> and C<svs backout> correctly handle those
special cases.
=back
=head2 COMMANDS
The following commands are provided:
=over 4
=item B<svs> vi I<file> [...]
This potentially edits I<file> by preserving the original contents in
I<file>C<.orig> (if still not existing) and running the C<$EDITOR> (or
"C<vi>") on I<file>. On leaving the editor, the original and current
contents is compared. If there is no difference the I<file>C<.orig> is
removed again, else it is kept.
=item B<svs> diff [I<file>|I<dir> [...]]
This generates a "patch file" summarizing all changes made to files
where an I<file>C<.orig> exists.
=item B<svs> backout [I<file>|I<dir> [...]]
This backouts all changes made to files where an I<file>C<.orig> exists.
The I<file>C<.orig> files are removed, too.
=item B<svs> status [I<file>|I<dir> [...]]
This shows a short status of files I<file> where an I<file>C<.orig> or I<file>C<.rej> file exists.
A prefix of "C<M>" indicates a modification (a I<file>C<.orig> exists).
A prefix of "C<C>" indicates a conflict (a I<file>C<.rej> exists).
=back
=head1 HISTORY
The B<svs> tool was implemented in 2003 by Ralf S. Engelschall
E<lt>rse@engelschall.comE<gt>. It was prompted by the need for a
frontend to diff(1) and patch(1) to generate patches in the B<OpenPKG>
E<lt>http://www.openpkg.org/E<gt> project.
=cut
