vcreate(1)

Name

vcreate - Create a new package in the Vesta repository

Synopsis

vcreate [-q] [-Q] [-v] [-a | -A] [-f] [-o old-version | -O] [-m message | -M] [-h hints] [-R repos] package

In the most common usage, only the package argument is given.

Contents

Description

See the vesta-intro man page's Terminology section for definitions of terms, and its Name Interpretation section for an explanation of how names are looked up.

The vcreate command creates a new package in the Vesta repository. The package initially is not checked out; use vcheckout(1) to check it out and begin creating version 1.

By default, the new package initially contains version 0 as an empty directory. If an old version is specified with the -o flag, it is copied into the new package as version 0.

In more detail, vcreate:

vcreate figure

If the name package or old-version is unqualified (does not have "/", ".", or ".." as its first arc), it is interpreted relative to the site's default directory of packages, DefaultPackageParent.

You must have write access to the directory in which package is to be placed. The newly created package is owned by you, but has access permissions inherited from its parent directory.

In the presence of replication, package creation cannot always be carried out entirely in the local repository. In particular, the local repository may contain no replica of one of the needed objects, or it may contain a non-master replica where the master replica is needed. Also, the -a/-A flags control which repository vcreate will give mastership of the created package. (See vrepl(1) and vmaster(1) for more information about replication and mastership.) The exact steps are slightly different depending on which repository has the master copy of the parent directory of package and whether the local repository is to have the master copy of the created package (controlled by the -a/-A flags).

If the parent directory of package is mastered locally, vcreate creates the package in the local repository (and the -a/-A flags have no effect). However, if old-version was specified and does not exist locally, vcreate searches for a copy and replicates it to the local repository before creating the package.

If the parent directory of package is not mastered locally, vcreate may give mastership of package to the local repository, if either the -a flag is specified or [UserInterface]vcreate_acquires is set to true. If old-version was specified and does not exist locally, vcreate searches for a copy and replicates it to the local repository. vcreate then creates the package remotely in the master copy (except for inserting old-version), replicates it to the local repository, transfers mastership, and finally inserts old-version.

If the -A flag is specified or [UserInterface]vcreate_acquires is set to false and the parent directory of package is mastered remotely, vcreate will leave mastership of package with the master repository of its parent directory. In this case, if old-version was specified and does not exist in the remote master repository, vcreate searches for a copy and replicates it to that repository. vcreate then creates the package remotely in the master copy (including inserting old-version), and replicates it to the local repository.

vcreate returns status 0 for success, 1 for parameter syntax errors, or 2 for more serious errors. (Note that if any of the trigger commands fail, vcreate returns status 2.)

Flags

-q
Quiet; suppress printing out what is being done.
-Q
Query; print out what the command would do, but don't do it.
-o old-version
Specifies the initial content (version 0) for the new package. Must be an immutable directory, typically a version of some other package. By default, version 0 is an empty directory. Hint: if you are using this flag, you might want to consider using vbranch(1) instead. Perhaps you are really creating a branch of an existing package, not a completely new package.
-O
Create version 0 as an empty directory in the new package (default).
-m message
Specify the package descriptive message. If the message argument is "-", the user will be prompted to enter a message. (See the "Message Entry" section below.) If message is any other text, it will be used as the package descriptive message without prompting the user. If neither the -m flag nor the -M flag is used, the default is "-m -" (although this can be changed with the [UserInterface]vcreate_message configuration setting).
-M
Omit the package descriptive message.
-h hints
If vcreate fails to find the master copy of a directory it needs to modify (or fails to find any copy of the old version) in either the local repository or any of those repositories listed in [UserInterface]DefaultHints, you can suggest additional repositories for it to look in using this option. The hints argument is a comma- or space-separated list of repositories, specified by host name and TCP port number in the format host:port. The :port portion may be omitted; it defaults to [Repository]VestaSourceSRPC_port.
-R repos
Create the package in repos instead of the default local repository. The repository is specified by host name and TCP port number in the format host:port. The :port portion may be omitted; it defaults to [Repository]VestaSourceSRPC_port.
-a or -A
Do (-a) or do not (-A) acquire mastership of the created package when the local repository doesn't have mastership of the parent directory. The default is controlled by the [UserInterface]vcreate_acquires configuration setting. (Note that if the parent directory of package is mastered in the local repository, these flags have no effect.)
-f
Force; omit sanity checking. If the -f flag is not given, the new package's parent directory must be of type "package-parent" (that is, its type attribute must include this value). To create a new directory that can hold packages, use mkdir(1), then use vattrib(1) to add the necessary attribute, or use vmkdir(1) with it's -p flag.
-v
Displays extra information about triggers. Before executing any trigger commands, the environment variables used to provide information to them are printed. Also, each trigger setting is printed before the command is executed. This can be used to help debug trigger problems. When used with the query flag (-Q), the triggers are displayed in their sorted order without actually running them.

Message Entry

vcreate's default behavior is to prompt the user for a package descriptive message. If the EDITOR environment variable is set, the external editor program it specifies is invoked to edit the message. Otherwise, the message is read from standard input. A prompt is printed if the standard input is a terminal: 

Enter package description, terminated with ^D or . on a line by itself
:
If the standard input is not a terminal (e.g. it was redirected to a file or a pipe), no prompt will be printed, but the standard input will still be used as the package descriptive message. (Note that when EDITOR is set, the external editor is invoked even if the standard input is not a terminal.)

When using an external editor, the initial text will be "<enter package description here>". If the initial text is left unedited or the user enters an empty message, they will be asked for confirmation before completing the operation: 

Empty package description.  Continue (y/n)?
This is the only chance to abort when EDITOR is set. (So if you change your mind and are using an external editor, exit the editor either with the message unedited or with an empty message.)

The -m flag can be used to specify the package descriptive message on the command line. The -M flag can be used to omit the package descriptive message. In either of these cases, no external editor will be invoked, and the standard input will not be read.

The default of prompting for a package descriptive message can be disabled with the [UserInterface]vcreate_message configuration setting. However, this can be overridden on the command line with "-m -", which will always cause vcreate to prompt for a package descriptive message.

Configuration

The following values are obtained from the [UserInterface] section of the Vesta configuration file (vesta.cfg).

AppendableRootName
The filename under which the global root directory of Vesta repositories is mounted. Ordinarily set to /vesta.
MutableRootName
The filename under which the local tree of mutable directories provided by Vesta is mounted. Ordinarily set to /vesta-work.
DefaultPackageParent
The default directory to put new packages in. Ordinarily a subdirectory of the appendable root, named with an Internet domain name belonging to the local site.
DefaultWorkParent
The default parent directory for mutable working directory trees belonging to individual users. Ordinarily the same as the mutable root.
realm
Global user names are formed by appending @realm to the local name. This setting is optional. If it is not set, [Repository]realm is used.
TimeFormat
A format string for strftime(3) to produce time strings for Vesta attributes. A common setting is "%a %b %e %T %Z %Y".
vcreate_acquires
Sets the default policy for which repository should have mastership of the created package when the master repository of the parent directory is remote. If it is equal (witout regard to case) to "yes", "on", or "true", or can be parsed as an integer that is non-zero, the local repository will acquire mastership (as if the -a flag had been given). If it is equal (witout regard to case) to "no", "off", or "false", or can be parsed as an integer that is zero, the master repository of the parent directory will retain mastership of the created package (as if the -A flag had been given). If not set, defaults to "false".
DefaultHints
A comma- or space-separated list of additional repositories to search for the master copy of an object and for a copy of old-version. Each repository is specified by host name and TCP port number in the format host:port. The :port portion may be omitted; it defaults to [Repository]VestaSourceSRPC_port. This setting is optional.
vcreate_message
A boolean configuration setting. Determines whether vcreate will prompt the user for a descriptive message. If it is equal (without regard to case) to "yes", "on", or "true", or can be parsed as an integer that is non-zero, vcreate will ask the user to enter a message (as if "-m -" had been given on the command line). If it is equal (without regard to case) to "no", "off", or "false", or can be parsed as an integer that is zero, vcreate will not prompt for a message (as if the -M flag had been given). If not set, defaults to "true".

The following values are obtained from the [Repository] section of the Vesta configuration file.

VestaSourceSRPC_host
The host name of the default (local) repository.
VestaSourceSRPC_port
The default TCP port number for repositories.
realm
Global user names are formed by appending @realm to the local name. This setting is only used if [UserInterface]realm is not set.

Settings in the [vcreate pre trigger] and [vcreate post trigger] sections of the configuration file are used as commands to be run before and after the repository is modified. See the next section.

Triggers

Users can configure commands in the Vesta configuration file (vesta.cfg) to be executed before and after vcreate modifies the repository. Each setting in the [vcreate pre trigger] section specifies a command to be run before any action is taken, and each setting in the [vcreate post trigger] section specifies a command to be run after all actions are complete.

The value of each setting specifies a command to run. The names of the settings define the order in which these commands are run. The setting names are sorted as strings, but comparing embedded sequences of digits as decimal integers. (So, for example "foo_10_bar" will sort after "foo_2_bar".) The suggested naming convention for trigger settings is to start with an integer, follow with a descriptive name, and follow that with any other text. (This is based on the convention used for System V style init script links typically stored in /etc/rcN.d.)

Here's a simple example of how we suggest naming trigger settings, and how they are ordered for execution: 

[vcreate pre trigger]
100world = echo World!
9tada    = echo Tada:
50hello  = echo Hello,
Because these all start with numbers, they will be executed in the order "9tada", "50hello", "100world". The output will look like this: 
% vcreate /vesta/example.com/...
Tada:
Hello,
World!
Creating package /vesta/example.com/...
Trigger commands are executed with system(3). On most operating systems this means "/bin/sh -c command", so simple in-line shell scripts can be used. (Note that each is executed in its own shell process, so environment variables set during one trigger command will not propagate to subsequent ones.)

If any of the commands in the [vcreate pre trigger] section exit with error (non-zero) status or are terminated by a signal (e.g. segmentation fault, abort), vcreate will exit without creating a package.

The commands in the [vcreate post trigger] section will only be executed if a new package is successfully created. If vcreate fails with an error, the commands in the [vcreate post trigger] section will not be executed.

Note that all the trigger commands (both pre and post) are executed sequentially. Once a trigger command is started, nothing else happens until it completes. If any of the pre trigger commands runs forever, vcreate will not create a package. If any of the post trigger commands runs forever, vcreate will not complete. (In other words, a trigger command that hangs will cause vcreate to hang.) If any of the pre or post trigger commands exit with error status or are terminated by a signal, vcreate will exit without running any more commands from those sections. (In other words, a trigger command that fails will prevent further trigger commands from being run.)

If the the query flag (-Q) is given, the trigger commands will not actually be run.

Information about what vcreate is going to do or has just done is provided to the trigger commands through the following environment variables:

VESTA_TOOL
The name of the Vesta tool the trigger command has been invoked from. (For vcreate, this will always be "vcreate".)
VESTA_REPOS
The local repository (host:port) vcreate communicates with (either the default from the configuration file or the one specified with the -R flag.
VESTA_MASTER_HINTS
Additional repositories which may have been consulted in order to find the master copy of the parent directory of the package. This is the combination of the argument to the -h flag (if it was used) and the hints from the [UserInterface]DefaultHints configuration setting (if set in the configuration file).
VESTA_MASTER_REMOTE
Set to 1 if the parent directory of the package created by vcreate is mastered in a remote repository, set to 0 otherwise. If this is set to 1, the package will be created in the remote master ($VESTA_MASTER_REPOS) and replicated to the local repository ($VESTA_REPOS).
VESTA_MASTER_REPOS
The repository (host:port) with mastership of the parent directory of the package created by vcreate. If this is different from $VESTA_REPOS, $VESTA_MASTER_REMOTE will be set to 1 and the package is created at the remote master repository.
VESTA_PACKAGE
The package created by vcreate.
VESTA_OLD_VERSION
The path to the version the package will be based upon (specified with the -o flag). This will become version 0 within the created package.
VESTA_OMIT_OLD_VERSION
Set to 1 if there is no old version (which is the default unless the -o flag is given), set to 0 otherwise.
VESTA_OLD_VERSION_REMOTE
Set to 1 if the old version was not found in the master repository of the package parent ($VESTA_MASTER_REPOS), set to 0 otherwise. If set to 1, the old version will be replicated from the repository where it was found ($VESTA_OLD_VERSION_REPOS) to the master repository of the package parent directory before creating the package.
VESTA_OLD_VERSION_REPOS
The repository (host:port) where a replica of the old version was found. If this is different from $VESTA_MASTER_REPOS, $VESTA_OLD_VERSION_REMOTE will be 1. If there is no old version, this will be set to the empty string.
VESTA_ACQUIRE_MASTERSHIP
Set to 1 if vcreate is creating a package at a remote master repository and acquiring mastership of it in the local repository, set to 0 otherwise. (If $VESTA_REPOS is the same as $VESTA_MASTER_REPOS this will be 0.) See the description of the -a/-A flags above.
VESTA_MESSAGE
The package description message, or the empty string if there is no description message.
VESTA_OMIT_MESSAGE
Set to 1 if there is no package description message (if the -M flag was given or [UserInterface]vcreate_message was used to disable package messages), set to 0 otherwise.
VESTA_QUIET
Set to 1 if the quiet flag (-q) was given, set to 0 otherwise.
VESTA_FORCE
Set to 1 if the force flag (-f) was given, set to 0 otherwise.

(Note that the environment variables are the same for both the pre and post trigger commands.)

Here are some examples using these environment variables: 

[vcreate pre trigger]
// If the enclosing directory has a non-empty "obsolete" attribute,
// prevent new packages from being created there.
50no_obsolete = parent=`dirname $VESTA_PACKAGE` if vattrib -q -G obsolete $parent > /dev/null; then echo "Error: $parent is marked obsolete"; exit 1; fi

[vcreate post trigger]
// Replicate all new packages to known peer repositories
50repl = for r in $VESTA_MASTER_HINTS; do vrepl -s $VESTA_REPOS -d $r -e+ $VESTA_PACKAGE; done
If the verbose trigger flag (-v) is given, these environment variables will be printed, and each trigger command will be printed before executing it. This can be useful for debugging trigger problems. If both verbose trigger flag and the the query flag (-Q) are given, the triggers are displayed in their sorted order without actually running them. This can be used to find out what trigger commands are configured without actually running them.

Limitations

vcreate is atomic if it modifies only the local repository. If a remote repository must be modified, however, the action performed at each repository is individually atomic, but vcreate can die between the actions on the remote and local repositories. To make this problem less likely to occur, vcreate ignores SIGINT (the ^C interrupt) during the critical section.

Environment Variables

VESTACONFIG
If set, specifies the Vesta configuration file to be used. See vesta.cfg(5).
EDITOR
If set, specifies the editor to use for editing the package descriptive message.

See Also

vesta-intro(1), repos-ui(1), vesta.cfg(5)

Author

Tim Mann

This page was generated automatically by mtex software.