Ubuntu Manpage: save - save revision of a file

NAME

       save - save revision of a file

SYNOPSIS

       save [ version binding options ] [ options ] files ..
       Save [ version binding options ] [ options ] files ..

       Options: [ -?fglq ] [ -help ] [ -a (or -alias) version alias ] [ -delta ] [ -force ]
                [ -fix generation | alias | date ] [ -newgen ] [ -lock ]
                [ -m (or -logmsg) message ] [ -n (or -setvnum) version number ] [ -nodelta ]
                [ -quiet ] [ -setattrs filename ] [ -stdin ] [ -version ]

DESCRIPTION

save takes a snapshot of the current state of the specified files, stores them into
corresponding archive files and assigns unique version numbers to the created versions.
The original files will by default be removed and unlocked in order to support a
cooperative style of teamwork. Versions of files can be restored as regular files with the
retrv command. Versions in archives are inalterable.

An archive will be created the first time a file is saved in a subdirectory named AtFS.
The AtFS subdirectory must be present. When an archive is created, save asks for a short
description of the saved documents purpose. If a subsequent version is saved, the user is
prompted for a comment describing the modifications. The save command requires that the
version history of a file that shall be saved is locked by the user issuing the command.
This is to prevent different developers from applying concurrent updates to the same file
and thereby invalidating the other developers' modifications. The only exception from this
rule is the first time a file is saved, which means that an archive has yet to be created.
For more details on locking, see the ShapeTools Tutorial, retrv(1), and vadm(1).

The save program assigns unique version ids to each evolving revision of a file. The
version id is a pair of integers separated by a dot, identifying the major and minor
revision (<generation>.<revision>) of a version. Subsequent invocations of save increase
the minor revision number, starting with version 1.0. The generation number is increased
by invocations of Save (see below). There is no support for explicit branching. The
version control toolkit rather encourages a linear model of version evolution. Instead of
branching, save allows to insert new versions into old generations (see description of
-fix). This allows, for example, to fix bugs in major revision N (version numbers N.x)
which may be the currently operational release while development proceeds in generation
N+1 (or N+n if you like).

Before a file is saved it will be checked whether it has actually changed with respect to
the previously saved version. If the file hasn't changed, the user will be asked if it
should be saved anyway. The command line option -f (or -force) overrides the prompting.

The version control system supports a built-in basic status model for versions. The
version status is intended to express different levels of quality, and aims at providing
basic project management functionality. State attributes of software objects can help to
describe an object's current meaning in the development process (e.g. tested,
incompletely implemented, submitted for evaluation, or shipped to customer).

A newly created version will by default be assigned the state saved. This status marks the
lowest level of quality, suggesting that the version is just saved for possible later
retrieval but may be inconsistent. Versions that meet higher quality standards (or are
part of a release) should be marked by appropriate status (see vadm -promote, sbmt, or
publ).

If the program is invoked as Save (that is with capital-S) a new major revision
(generation) of the document history is created - provided the programmer issuing the
command has the permission to do this. This option is intended to support a development
model where maintenance of an operational release can be performed parallel to the
development of the next release (see -fix).

OPTIONS

For version selection, any version binding option, as described on the vbind(1) manual
page, may be given. Version bind directives in brackets added to the filename are
interpreted different to vbind(1). A version number following the name will be treated as
if the -n (-setvnum) option was given with this version number as argument. Any other
string in brackets will be taken as alias name (see -alias option).

-?, -help
print short information about usage of this command.

-a, -alias version alias
assign a version alias (a symbolic name) to the new version. In more detail, an
attribute __SymbolicName__ is set to the value specified in version alias. The
specified alias name must not be assigned to any other version within the same
version history. Alternatively to the -a option, the version alias may be given in
brackets following the name of the file to be saved. Check the description of the
-n option for an example of this notation.

-delta Create delta for internal storage. This is the default.

-f, -force
force a revision deposit (i.e. without asking), even if the busy version hasn't
changed since the last time it was saved.

-fix generation | alias | date
append a new version after the most recent version within the referenced major
revision level. The major revision level (called ``generation'') is either
referenced explicitly, by specifying a number, or implicitly, by specifying a
version alias (e.g. a release name) or a date. The latter form is particularly
useful for saving a fix that extends over more than one object.

This option is intended to support maintenance of older releases while development
proceeds at the logical end of the version chain. In order to insert a (fixed)
version into an old generation, one must have a lock on the most recent version of
that generation (generation lock). This lock must be set with the vadm command. The
-fix option is incompatible with -setvnum, -newgen and the Save command option.

-g, -newgen
create a major revision of the document. Major revisions are indicated by the first
number in the version-id (generation). Only the archive administrator is allowed
to create major revisions. The archive administrator is the user who owns the AtFS
subdirectory where the version archives reside. Use of this switch is identical to
calling the program as Save.

-l, -lock
Keep the lock on the version history. The saved files will not be removed.

-m, -logmsg message
set message as descriptive note for all document versions that result from the
invocation of save. When message starts with an at sign (@), it is interpreted as
filename and the text contained in the file is set as descriptive note for all
document versions that result from the invocation of save.

-n, -setvnum version number
set the version number of the newly created revision to version. The version must
be given in the format <generation>.<revision> where generation and revision are
integers. Example:
save -setvnum 4.3 mkattr.c
The specified version must be greater than the highest previously assigned version
number in a given object history. Only the archive administrator may set version
numbers directly. The archive administrator is the user who owns the AtFS
subdirectory where the version archives reside. -setvnum is useful for keeping
consistent version numbering across related, physically different object
repositories, or for converting archive formats of other revision control systems
to this toolkit (see: rcs2atfs). Alternatively to the -n option, the version number
may be given in brackets following the name of the file to be saved. The command
save mkattr.c[4.3]
is interpreted the same way as the example above.

-nodelta
Suppress delta generation

-q, -quiet
quiet operation. No messages are printed on standard output. If the busy version
is unchanged, it will not be saved unless -f is set. The user will not be prompted
for a descriptive note. If no message or note is supplied with the command line
(see options -m and -t) the log will remain empty. This option is useful for batch
operation.

-setattrs filename
read names and values of user defined attributes from the file filename. The
entries in the attribute file must have either of the formats NAME=VALUE or
NAME+=VALUE. NAME must be an alphanumeric string (no spaces) immediately followed
by the assignment operator. The value may be an arbitrary ASCII string with the
exception of control-A and newline characters. There is exactly one attribute
definition per line. The file's last character must be a newline character.

If the first format (single equal symbol) is used, previously assigned values of
user defined attributes are reset with the values defined in the attribute file.
The second format (``plus equal'') allows to append additional values to an already
existing attribute. If no attribute of a given name exists, it will be created.

This way to attach attributes was introduced to allow quick automatic attachment of
a large number of attributes to version objects. This interface to the attribute
setting facility is mainly intended for tools that invoke save.

If the -setattrs option is omitted, save searches the environment for a variable
SVATTRS. If this variable is absent, no user defined attributes will be assigned to
the evolving versions.

-stdin force save to read a descriptive note from stdin instead of forking an editor. A
previously set intent-message is printed.

-version
print the version of the program itself.

FILES

       All revisions of documents are stored in archive files in the subdirectory AtFS.

BUGS

       With the -g (-newgen) option given and an unchanged busy version, save ignores  the  users
       answer  to  the  question, if the busy version should be saved anyway. It always assumes a
       positive answer  and  goes  on  with  its  saving  procedure.  You  can  avoid  saving  by
       interrupting  (Ctrl-C)  save  during the next question if the unmodified version should be
       commented anyway.

AUTHOR

       Axel.Mahler@cs.tu-berlin.de and Andreas.Lampen@cs.tu-berlin.de