vupdate(1)

Name

vupdate - update the imports of a Vesta model

Synopsis

vupdate [ options ] [ model ]

Contents

Description

vupdate updates the imports of the named model so that all imports are to the latest package versions. Only those imports of models outside the local directory are updated. If no model is specified, it defaults to ".main.ves".

Ordinarily, vupdate replaces the existing model with the updated version. If -no-action is specified, if the updated model is identical to the existing one, or if errors occur, the existing model (and its parent directory) are left untouched.

To prevent the import of a model from being considered for updating, precede the model's pathname by a /**noupdate**/ or /**NOUPDATE**/ pragma.

When the import being updated is to a model in a checkout session, the import is updated to point to the latest main version within the package (or branch) if such a version exists, or to the latest version in the checkout session otherwise. This behavior can be overridden using to -to-checkout switch below. Also see the -advance-checkout switch if you would like checkout sessions to be advanced.

For more complicated version histories (e.g. divergent lines of development that later re-converge), vupdate can follow continuations with the -follow-continuations switch.

The model argument is resolved according to the rules for import clauses as specified in The Vesta-2 Software Description Language. In particular, if model is not an absolute path, it is interpreted relative to the current working directory. If model names a directory, the string "/build.ves" is appended to it; otherwise, if it does not end in ".ves", that extension is appened to it.

vupdate returns status:

Options

vupdate accepts the following command-line options:

-no-action or -n
No action. Do not rewrite model, but print out what imports would be updated. Do not advance any checkout sessions. A warning is printed at the end of the output indicating that no action was taken. This option is mutually exclusive with the -query and -silent options.

-query or -q
Query mode. You will be queried on each potential update. To accept the update, type "y" and hit <ENTER>. If any other input is supplied, the import is not updated. This option is mutually exclusive with the -no-action and -silent options.

-silent or -s
Silent mode. By default, the name of each model requiring changes and the old and new versions of all updated imports are printed. This option supresses that output. This option is mutually exclusive with the -no-action, -query, and -verbose options.

-update-local or -r
Update local models recursively. By default, vupdate revises only the named model. If -update-local is specified, then any local models imported directly or indirectly by model are updated recursively. An imported model is considered to be local if it is specified by a relative pathname.

-advance-checkout or -a
Advance your imported checkout sessions. If -advance-checkout is specified, then whenever the model imports from a checkout session that belongs to you (including new checkout imports created by the -to-checkout option), vupdate will invoke vadvance(1) to attempt to advance the session before searching for the session's highest version.

-update-checkout or -c
Update models in your imported checkout sessions recursively. If -update-checkout is specified, then any models imported directly or indirectly from checkout sessions that belong to you are updated recursively (including new checkout imports created by the -to-checkout option). The sessions are then advanced as with the -advance-checkout option.

-update-all or -u
Sets both the -update-local and -update-checkout options.

-verbose or -v
Verbose mode. By default, if a model would not require any changes, its name is not printed. If -verbose is specified, the names of all processed models are printed. This option is mutually exclusive with the -silent option.

-limit name or -l name
Limit which imports will be updated. Only imports with a full pathname containing name will be updated. If multiple -limit clauses are specified, only those pathnames containing all specified names are updated. (For example, combining -limit src.dec.com with -limit repos would cause only imports containing both src.dec.com and repos to be updated.)

-limit-checkout or -L
Only update imports for checkout sessions. Equivalent to -limit /checkout/.

-to-checkout or -t
Allow imports to be updated to point to models in new checkout sessions. This both allows checked in versions to be updated to checked out versions, and allows old checkout session references to be updated to refer to new checkout sessions. This option is mutually exclusive with the -attr option.

When combined with the -follow-continuations option, vupdate will not update into a new exclusive checkout until after following continuations. For example, if an import points into branch A which is continued in branch B vupdate may update into an active checkout in branch B but will not update into an active checkout in branch A. See "Continuations" below for more information.

-only-mine or -m
Limit updating involving checkout sessions belonging to other users. Don't modify an import to point into a checkout session belonging to another user. Don't modify an import if it currently points into a checkout session belonging to another user. An import may still be updated within a checkout session owned by the user running vupdate. An import may still be updated from an exclusive checkout session owned by the user running vupdate to a newer checked in version (even a newer version created by a different user). An import may be modified to point into an exclusive checkout session belonging to the user running vupdate when using the -to-checkout option.

When combined with the -follow-continuations option, vupdate will not follow continuations into or through checkout sessions belonging to other users.

-attr attr-spec or -A attr-spec
Selective update. By default, vupdate updates each import to the latest relevant version. If -attr is specified, each import is updated to the latest version whose attributes match attr-spec. This option is mutually exclusive with the -to-checkout option.

The attr-spec should be a string according to the following grammar: 

attr-spec  ::= attr-name [ val-select val-list ]
attr-name  ::= String
val-select ::= `:' | `^'
val-list   ::= String | String `,' val-list
There are three cases:

  1. When attr-spec is simply an attr-name, a given package version matches the spec if it simply defines the attribute named attr-name.

  2. If attr-spec takes the form attr-name:attr-list, then a given package version matches the spec if it binds the attribute attr-name to a set of values at least one of which is named in attr-list.

  3. If attr-spec takes the form attr-name^attr-list, then a given package version matches the spec if it does not define the attribute attr-name, or if it binds the attribute attr-name to a set of values none of which is named in attr-list.

-parse-errors-stop or -e
Any trouble understanding the version imported or choosing a new version will be treated as a fatal error, causing vupdate to stop and leaving model unmodified. vupdate can always understand simple integer versions which are the norm, but can have difficulty with non-integer versions. Without this option, vupdate will issue a warning about each import it can't understand and leave it unmodified in model, proceeding on to update subsequent imports.

-follow-continuations or -f
When updating an import, if the enclosing directory (a session directory, a branch, or a package) has a "continued-in" attribute indicating that it is logically continued in a different directory, attempt to follow the continuation. See "Continuations" below.

Note that the -only-mine option will prevent following continuations into or through checkout sessions belonging to other users.

Note that updating into a new exclusive checkout enabled by the -to-checkout option happens after following continuations. For example, if an import points into branch A which is continued in branch B vupdate may update into an active checkout in branch B but will not update into an active checkout in branch A.

Restrictions

vupdate assumes that packages and models are structured in certain ways. Most of these restrictions are enforced by the repository tools. In addition to the obvious requirement that the models are syntactically legal according to the Vesta-2 Software Description Language, vupdate also makes the following assumptions:

Continuations

By default, vupdate assumes that the development of versions forms a strict tree as is typical when using the repository tools. Versions in a package proceed in a numerically linear fashion, taking brief side trips into the session directories of exclusive checkouts. Branches and non-exclusive checkouts form divergences. Once an import points into such a diverged line of development, vupdate by default won't move it back to the main trunk of the package versions.

Real development involves parallel work with lines of development diverging and re-converging. It's desirable to have vupdate follow the user's mental model of the logical progression of development even when that progression isn't strictly linear.

Continuations are an optional feature which allows vupdate to change imports more freely. They allow the user to inform vupdate about the logical progression of development. When setting a continuation, the user is saying "When you run out of versions here, update to there." To put it another way, continuations change vupdate's treatment of version history from a tree to a more general directed acyclic graph.

To use continuations, users must add "continued-in" attributes and run vupdate with the -follow-continuations option. The "continued-in" attribute must be placed on an appendable directory that contains versions, such as a session directory, a branch, or a package. The value of the "continued-in" attribute can be either a specific version or an appendable directory which contains versions. If the value of the "continued-in" attribute is a specific version, vupdate will update an import to that version or higher in the enclosing directory. (If the version that the attribute points to is not present, vupdate will not follow the continuation.) If the value of the "continued-in" attribute is an appendable directory which contains versions (e.g. a session directory or a branch), vupdate will update an import to the highest numbered version in that directory, even if that's version 0.

The "Examples" section below includes some detailed examples of how continuations work in practice.

Examples

One typical use is to test what imports would be updated using the -n option, like this: 

$ vupdate -n -r -v
/vesta-work/heydon/vimports/.main.ves
     /vesta/src.dec.com/common/std_env/42/build.ves
  -> /vesta/src.dec.com/common/std_env/49/build.ves

/vesta-work/heydon/vimports/build.ves
/vesta-work/heydon/vimports/src/progs.ves
/vesta-work/heydon/vimports/src/docs.ves
/vesta-work/heydon/vimports/src/lib.ves
WARNING: Nothing updated at your request!
The package can then be updated normally: 
$ vupdate
/vesta-work/heydon/vimports/.main.ves
     /vesta/src.dec.com/common/std_env/42/build.ves
  -> /vesta/src.dec.com/common/std_env/49/build.ves
Query mode can be used to selectively update a model's imports: 
$ vupdate -q
/vesta-work/heydon/release/.main.ves
     /vesta/src.dec.com/common/cxx/checkout/14/82/build.ves
  -> /vesta/src.dec.com/common/cxx/checkout/14/83/build.ves
  Update this import (y/n)? y

     /vesta/src.dec.com/common/std_env/48/build.ves
  -> /vesta/src.dec.com/common/std_env/49/build.ves
  Update this import (y/n)? n
The following example shows a case where a checkout session has been updated to refer to a checked-in version of the package: 
$ vupdate
/vesta-work/heydon/basics/.main.ves
     /vesta/src.dec.com/c/libc/checkout/4/1/build.ves
  -> /vesta/src.dec.com/c/libc/7/build.ves
By adding the -to-checkout option, a checked in version can be updated to a current checkout session: 
$ vupdate -to-checkout
/vesta-work/schalk/std_env/.main.ves
     /vesta/shr.dec.com/common/cxx/4/build.ves
  -> /vesta/shr.dec.com/common/cxx/checkout/5/6/build.ves
The following example will update imports only to package versions that define an "approved" attribute: 
$ vupdate -attr approved
The following example will update imports only to package versions that define a "status" attribute to have a value of either "passed" or "released": 
$ vupdate -attr status:passed,released
The following example will update imports only to package versions that do not define a "status" attribute whose value is "buggy": 
$ vupdate -attr status^buggy
A few examples of how continuations can be used in practice follow.

Suppose a user started a non-exclusive checkout for a change, perhaps because they didn't want to hold up other users who might be making changes to the same package. Now they're preparing to check in their changes and have moved their work to a later exclusive checkout. To allow vupdate to follow the development into the main line, they add a "continued-in" attribute to their non-exclusive session directory using vattrib: 

% vattrib -a continued-in /vesta/example.com/foo/pkg/checkout/15 \
  /vesta/example.com/foo/pkg/checkout/12.jsmith_example.com.1
Now when anyone uses vupdate with the -follow-continuations option on a model with an import pointing into the old non-exclusive session, it will be followed into the new exclusive session: 
% vupdate -follow-continuations foo.ves
     /vesta/example.com/foo/pkg/checkout/12.jsmith_example.com.1/31/build.ves
  -> /vesta/example.com/foo/pkg/checkout/15/3/build.ves
If the exclusive session had since been checked in and newer versions had been checked in after it, vupdate will continue to move forward to those newer versions just as it would if the import had originally pointed into the exclusive checkout session: 
% vupdate -follow-continuations foo.ves
     /vesta/example.com/foo/pkg/checkout/12.jsmith_example.com.1/31/build.ves
  -> /vesta/example.com/foo/pkg/17/build.ves
Suppose instead of moving right to an exclusive checkout, the user chose to use a newer non-exclusive session (perhaps because they knew it would take some time to reconcile their changes with intervening main-line changes). They could add a continuation from their first non-exclusive session to their second: 
% vattrib -a continued-in \
  /vesta/example.com/foo/pkg/checkout/15.jsmith_example.com.1 \
  /vesta/example.com/foo/pkg/checkout/12.jsmith_example.com.1
When they later move their work into an exclusive checkout, they could then add a second continuation: 
% vattrib -a continued-in \
  /vesta/example.com/foo/pkg/checkout/17 \
  /vesta/example.com/foo/pkg/checkout/15.jsmith_example.com.1
vupdate would then be able to follow the continuations from the first non-exclusive session through the second and into the exclusive checkout: 
% vupdate -follow-continuations foo.ves
     /vesta/example.com/foo/pkg/checkout/12.jsmith_example.com.1/31/build.ves
  -> /vesta/example.com/foo/pkg/checkout/17/2/build.ves
And even to checked in versions past the exclusive session: 
% vupdate -follow-continuations foo.ves
     /vesta/example.com/foo/pkg/checkout/12.jsmith_example.com.1/31/build.ves
  -> /vesta/example.com/foo/pkg/17/build.ves
If you find that continuations are a little too hard to understand, adding -verbose will make vupdate print additional messages to help you understand continuations: 
% vupdate -follow-continuations -verbose foo.ves
/vesta-work/jsmith/bar/foo.ves

  /vesta/example.com/foo/pkg/checkout/12.jsmith_example.com.1
  ...continued in /vesta/example.com/foo/pkg/checkout/15.jsmith_example.com.1
  ...continued in /vesta/example.com/foo/pkg/checkout/17

     /vesta/example.com/foo/pkg/checkout/12.jsmith_example.com.1/31/build.ves
  -> /vesta/example.com/foo/pkg/17/build.ves
Suppose a user has been working on a change in a branch (instead of non-exclusive sessions). They have just finished that work and integrated their changes into a new main-line version. They can add a "continued-in" attribute to the branch indicating the version that incorporates the changes: 
% vattrib -a continued-in \
  /vesta/example.com/foo/pkg/17 \
  /vesta/example.com/foo/pkg/12.bar
Then vupdate would follow the continuation from the branch to the specific main-line version and then on to any higher numbered versions: 
% vupdate -follow-continuations foo.ves
     /vesta/example.com/foo/pkg/12.bar/5/build.ves
  -> /vesta/example.com/foo/pkg/18/build.ves
Just as with session directories, another options is adding a continuation from one branch to another: 
% vattrib -a continued-in \
  /vesta/example.com/foo/pkg/17.bar \
  /vesta/example.com/foo/pkg/12.bar
Allowing vupdate to move from one branch to another: 
% vupdate -follow-continuations foo.ves
     /vesta/example.com/foo/pkg/12.bar/5/build.ves
  -> /vesta/example.com/foo/pkg/17.bar/2/build.ves
Or even into the latest snapshot in an active checkout in the current branch (by adding the -to-checkout option): 
% vupdate -follow-continuations -to-checkout foo.ves
     /vesta/example.com/foo/pkg/12.bar/5/build.ves
  -> /vesta/example.com/foo/pkg/17.bar/checkout/3/7/build.ves

Configuration

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

TempDir
Name of a Vesta mutable directory that can be used for temporary file storage. Ordinarily set to /vesta-work/.tmp.

Bugs

See Also

repos-ui(1), vimports(1), vlatest(1), vattrib(1)

Author

Allan Heydon (heydon@src.dec.com) 

Created on Tue Jul 15 17:01:30 PDT 1997 by heydon
This page was generated automatically by mtex software.