BRINGOVER(1)

NAME
bringover - copy files from a parent workspace to a child workspace

SYNOPSIS
bringover [ -B ] [ -c comment ] [ -C ] [[ -f flp ] ... ]
[ -g ] [ -n ] [ -p pws ] [ -q ] [ -v ] [ -w cws ]
[files or dirs ...]

DESCRIPTION

bringover is the TeamWare command used to copy one or more files from a parent workspace to a child workspace. TeamWare was formerly known as CodeManager. All file transfer transactions are performed from the perspective of the child workspace; hence the bringover command "brings over" files to the child from the parent workspace. If the child workspace does not exist bringover creates it. After users make changes to files and test them in the child, the putback(1) command can be used to copy those files back to the parent.

  Creating a New Child Workspace

To create the child workspace as part of the bringover transaction, both the -w and -p options must be specified. The -p option names the parent workspace, which must exist, and the -w option names the child workspace which must not exist. For example,

    example% bringover -w ~/ws/mychild -p /ws/project dir1 dir2

creates workspace ~/ws/mychild as a child of /ws/project and populates it with the files under directories dir1 and dir2.

  Updating an Existing Child Workspace

bringover is used to update an existing child workspace with changes made to files in the parent; it attempts to make the parent and child workspaces identical with respect to the set of files specified for the bringover transaction.

If a file has changed in both the parent and child workspaces, the file is said to be in conflict. The resolve(1) command is used to resolve conflicts by displaying the files in filemerge(1), a graphical three-way differences program.

The -p option need not be specified when updating an existing workspace. When bringover creates a workspace, it records the parent name in the workspace Codemgr_wsdata directory (Codemgr_wsdata/parent). Used without the -p option, bringover fetches the parent's name from this directory. For example,

    example% bringover -w ~/ws/mychild dir1 dir2

copies changed files under directories dir1 and dir2 from the parent, /ws/project, to the child, ~/ws/mychild.

Note that if the -p option is specified when updating an existing workspace, bringover uses that parent for the duration of the transaction, rather than the one named in the Codemgr_wsdata/parent file. To permanently change the workspace's parent, use the workspace parent command.

The following table summarizes bringover actions:

File in Parent	File in Child	Action by TeamWare

Exists	Does not exist	Create file in child

Does not exist	Exists	None

Unchanged	Unchanged	None

Unchanged	Changed	None

Changed	Unchanged	Update file in the child

Changed	Changed	Merge SCCS history files in the child

		create conflict and notify user

OPTIONS

-B  Do not backup files in the child workspace before changing them. While reducing the disk space occupied by the child workspace and improving file transfer performance, it removes the option of later "undoing" the bringover with the ws_undo command.

-c comment
    Provide a comment describing the bringover. The comment is written to cws's Codemgr_wsdata/history file which records information about the transfer of files.

-C  Force all updates to be conflicts.

-f flp
    Execute the file list program, flp, to determine the list of files to process. flp is a program that writes a white-space separated list of file names to stdout. bringover processes these file names as if they were specified on the command-line. More than one -f option may be specified. If flp exits with a non-zero status, bringover displays a message and exits.

-g  Don't do SCCS gets after transferring files. Normally g-files are extracted after they are brought over. This option improves file transfer performance although it shifts the responsibility to the user to do the appropriate gets at a later time.

-n  Show what would be done without actually doing anything.

-p pws
    Names the parent workspace. This option is required when creating a child workspace. If specified with an existing workspace, pws is used as the parent workspace for the duration of the command.

-q  Quiet option. By default, a message is displayed for each created, updated, or conflicting file. The -q option suppresses these messages. If both the -q option and the -v option are specified, the last one takes precedence.

-v  Verbose option. By default, a message is displayed for each created, updated, or conflicting file. The -v option causes bringover to print a message for all files, including those that are not brought over. If both the -v option and the -q option are specified, the last one takes precedence.

-w cws
    Names the child workspace. If the -w option is not specified, then the value of the shell environment variable CODEMGR_WS is used. If CODEMGR_WS is not set and the current directory is contained within a workspace, the containing workspace is used.

    If the cws workspace exists, then the parent workspace is determined by reading cws's Codemgr_wsdata/parent file. If the cws workspace does not exist, then the -p option must be specified.

Some notes about the file and dir arguments:

•   The "." directory may be used to specify that the entire workspace be copied.

•   To save users the trouble of specifying file and directory arguments every time the bringover and putback commands are used, the arguments are cached in the cws/Codemgr_wsdata/args file. If file or dir arguments are not specified to subsequent invocations of bringover, the arguments are taken from the args file as if they were specified on the command-line.

    The args file is maintained by the bringover and putback commands; they update the file whenever new arguments are specified that cause additional files to be copied.

    Note that if no arguments are specified, and the Codemgr_wsdata/args file does not exist, bringover will report an error.

    Users can edit the args file at any time to change its contents.

•   Any valid file name that does not contain whitespace characters or a pound sign (#) may be specified as an argument to bringover. A relative file name specified on the command-line, as output of a file list program (FLP), or as an argument to the -f option is interpreted as being relative to the top-level (root) directory of the parent and child workspaces. If an absolute file name does not refer to a file under one of the workspaces, it will also be interpreted as being relative to the workspace root directory.

•   When a directory is specified as the argument to the command, bringover changes to that directory and invokes the default FLP: def.dir.flp. The FLP writes a list of file names to stdout that bringover processes as if they were specified as command-line arguments. The default version of def.dir.flp as shipped with teamware recursively lists all files under SCCS control beneath the specified directory. Note that other FLPs including ones written by users, may be specified via the -f option. Refer to the Sun TeamWare User's Guide and the Sun TeamWare Solutions Guide for more details regarding FLPs.

teamware uses a multi-reader/single-writer locking mechanism and bringover obtains a read-lock in pws and a write-lock in cws. If these locks can not be obtained, bringover displays a message and exits.

teamware checks the access_control file in the parent workspace to determine if the user is permitted to do a bringover from the workspace. If the child workspace already exists, it's access_control file is also checked to see if the user is allowed to do a bringover into it.

bringover displays status messages to stdout indicating whether a file is new, updated or in conflict. A copy of these messages is also written to cws's Codemgr_wsdata/history file.

bringover executes other TeamWare commands, such as sccsmerge, and expects to find them in the user's PATH. Therefore, the user's PATH variable must include the directory where teamware is installed.

MESSAGES
If bringover is unable to transfer files it will display one of the following messages:

•   Bringover warning: file name file not brought over because
        it is a type in workspace pws
        and a type in workspace cws

    A file name has a different file type (regular file vs. directory vs. symbolic link) in pws and cws. The user must take whatever action is appropriate to make the listed files the same type or change one of the names.

•   Bringover warning: file not brought over because it is
        checked out in workspace pws

    The file is currently checked out in pws. It must be checked in, or unchecked out, before it can be brought over.

•   Bringover warning: file not brought over because it is
        unresolved in workspace pws

    The file is currently unresolved (in conflict) in pws. It must be resolved before it can be brought over.

ENVIRONMENT

The following variables are used by bringover.

CODEMGR_DIR_FLP
    Contains the name of the file list program (FLP) to use in workspaces if one is not explicitly specified by means of the -f option. Overrides the teamware default FLP def.dir.flp(1).

CODEMGR_PATH_ONLY
    TeamWare commands first search for other TeamWare binaries relative to where their own binary is located in the file system, they then search in the directories specified in the PATH environment variable. Setting this variable causes TeamWare commands to search for other TeamWare binaries only in PATH.

CODEMGR_WS
    Contains the name of a user's default workspace. The workspace specified by CODEMGR_WS is automatically used if -w option is not specified to a command.

CODEMGR_WSPATH Specifies a list of workspace directories to be automatically loaded into the workspace pane upon tool startup.

    The CODEMGR_WSPATH variable can be to set to one or more directories that contain workspace directories. For example, to set this variable to the directories /export/home/ws and ~/projects/ws, use the following command:

    example% setenv CODEMGR_WSPATH "/export/home/ws ~/projects/ws"

The following variables are set by bringover at execution time for use within FLPs.

CODEMGR_CMD
    Contains the name of the bringover command.

CODEMGR_WS_CHILD
    Contains the name of the child workspace for this bringover.

CODEMGR_WS_DEST
    Contains the name of the destination (to) workspace for this bringover.

CODEMGR_WS_PARENT
    Contains the name of the parent workspace for this bringover.

CODEMGR_WS_SRC
    Contains the name of the source (from) workspace for this bringover.

CODEMGR_WS_ROOT
    The bringover command executes FLPs in both the parent and child workspaces. This variable contains the name of the workspace in which the FLP is currently executing.

FILES

def.dir.flp
    default FLP for directories

cws/Codemgr_wsdata/conflicts
    contains the names of files in conflict

cws/Codemgr_wsdata/parent
    contains the name of the parent workspace

cws/Codemgr_wsdata/locks
    locks file for cws

cws/Codemgr_wsdata/args
    definition of all of cws

cws/Codemgr_wsdata/history
    log of the bringover

pws/Codemgr_wsdata/locks
    locks file for pws

SEE ALSO
Sun TeamWare User's Guide

def.dir.flp(1), putback(1), resolve(1), sccs-get(1), sccs-admin(1), teamware(1), twmerge(1), ws_undo(1), workspace(1), access_control(4), args(4), children(4), conflicts(4), history(4), locks(4), nametable(4), notification(4), parent(4)

EXIT CODES

0   bringover was successful, no files in conflict

1   bringover failed due to an error condition

4   bringover was successful, files in conflict