."
." Copyright (c) 1998 by Sun Microsystems, Inc.
."
." @(#)bringover.1	1.70	00/03/28 SMI
."
.TH BRINGOVER 1 "00/03/28 Sun WorkShop 6"
.ds ]W
.SH NAME
bringover \- copy files from a parent workspace to a child workspace
.SH SYNOPSIS
.B bringover
.RB [ " \-B " ]
.RB [ " \-c "
.IR comment " ]"
.RB [ " \-m "
.IR comment_file " ]"
.RB [ " \-C " ]
.if n .br
.RB [ " \-d " ]
.RB [[ " \-f "
.IR flp " ] ... ]"
.RB [ " \-g " ]
.RB [ " \-n " ]
.RB [ " \-p  "
.IR pws " ]"
.RB [ " \-q " ]
.if n .br
.RB [ " \-v " ]
." .if n \0\0\0
.RB [ " \-V " ]
.RB [ " \-w "
.IR cws " ]"
.RI [ "files or dirs" 
\&.\|.\|.]
.SH DESCRIPTION
.IX "CodeManager" "TeamWare" "bringover" "" "\fBbringover\fP"
.LP
.B 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 
.B bringover
command "brings over" files to the child from the parent workspace.  If the 
child workspace does not exist 
.B bringover
creates it.  After users make changes to files and test them in the child, the 
.BR putback (1)
command can be used to copy those files back to the parent.
.SS Creating a New Child Workspace
.LP
To create the child workspace as part of the bringover transaction, both the
\fB\-w\fP and \fB\-p\fP options must be specified.  The \fB\-p\fP option names
the parent workspace, which must exist, and the \fB\-w\fP option names the
child workspace which must 
.I not 
exist.  For example,
.IP
\fBexample% bringover -w ~/ws/mychild -p /ws/project dir1 dir2\fP
.LP
creates workspace 
.B ~/ws/mychild 
as a child of 
.B /ws/project
and populates it with the files under directories 
.B dir1
and
.BR dir2.
.SS Updating an Existing Child Workspace
.LP
.B 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.
.LP
If a file has changed in both the parent and child workspaces,
the file is said to be in conflict.
The 
.BR resolve (1)
command is used to resolve conflicts by displaying the files in 
.BR filemerge (1),
a graphical three-way differences program.
.LP
The \fB\-p\fP option need not be specified when updating an existing
workspace.
When
.B bringover 
creates a workspace, it records the parent name in the workspace
.B Codemgr_wsdata
directory (\fBCodemgr_wsdata/parent\fP). 
Used without the \fB\-p\fP option, 
.B bringover
fetches the parent's name from this directory.
For example, 
.IP
\fBexample% bringover -w ~/ws/mychild dir1 dir2\fP
.LP
copies changed files under directories 
.B dir1 
and 
.B dir2
from the parent, 
.BR /ws/project ,
to the child,
.BR ~/ws/mychild .
.LP
Note that if the \fB\-p\fP option is specified when updating an existing
workspace, 
.B bringover
uses that parent for the duration of the transaction,
rather than the one named in the
.B Codemgr_wsdata/parent
file. To permanently change the workspace's parent, use the
.B workspace parent
command.
.LP
The following table summarizes 
.B bringover
actions:
.LP
.nf
.ta 1.75i 3.5i
\f3File in Parent	File in Child	Action by TeamWare\f1
.sp 1
Exists	Does not exist	Create file in child
.sp 0
Does not exist	Exists	None
.sp 0
Unchanged	Unchanged	None
.sp 0
Unchanged	Changed	None
.sp 0
Changed	Unchanged	Update file in the child
.sp 0
Changed	Changed	Merge SCCS history files in the child
.sp 0
		create conflict and notify user
.fi
.sp
.SH OPTIONS
.TP 10
.B \-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
.BR
bringover
with the
.BR ws_undo
command.
.TP
.BI \-c " comment"
Provide a
.I comment
describing the
.BR bringover .
The
.I comment
is written to
.IR cws 's
.B Codemgr_wsdata/history
file ,which records information about the transfer of files. 
If both
.B -m 
and 
.B -c 
options are specified, the content of both comments are added to the history file in the order that the options were specified on the command line.
.TP
.B \-C
Force all updates to be conflicts.
.TP
.B \-d
Adds delta comments to transaction output and e-mail notification, including delta number, owner and comments.
.TP
.BI \-f " flp"
Execute the file list program, 
.IR flp ,
to determine the list of files to process.
.I flp
is a program that
writes a white-space separated list of file names to \fBstdout\fP.
.B bringover
processes these file names as if they were specified on the command-line.
More than one 
.B \-f 
option may be specified.
If
.I flp
exits with a non-zero status, 
.B bringover
displays a message and exits.
.TP
.B \-g
Don't do 
.SM SCCS 
.BR get s
after transferring files.  Normally \fBg-\fPfiles 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
.BR get s
at a later time.
.TP
.BI \-m " comment_file"
Specify a text file containing comments that describe the bringover. 
Contents of the file are written to the 
.IR cws's Codemgr_wsdata/history 
file, which records information regarding the transfer of files. 
If both
.B -m 
and 
.B -c 
options are specified, the contents of both comments are added to the history file in the order that the options were specified on the command line..TP
.B \-n
Show what would be done without actually doing anything.
.TP
.BI \-p " pws"
Names the parent workspace.
This option is required when creating a child
workspace.  If specified with an existing workspace, 
.IR pws
is used as the parent workspace for the duration of the command.
.TP
.B \-q
Quiet option.
By default, a message is displayed for each created, updated, or 
conflicting file.
The
.B \-q
option suppresses these messages.
If both the
.B \-q
option and the
.B \-v
option are specified, the last one takes precedence.
.TP
.B \-v
Verbose option.
By default, a message is displayed for each created, updated, or
conflicting file.
The
.B \-v
option causes
.B bringover
to print a message for all files, including those that are not brought over.
If both the
.B \-v
option and the
.B \-q
option are specified, the last one takes precedence.
.TP
.B \-V
Display the version being run on standard output.
.TP
.BI \-w " cws"
Names the child workspace.  
If the
.B \-w
option is not specified, then the value of the shell environment
variable 
.SM CODEMGR_WS 
is used.
If
.SM CODEMGR_WS
is not set and the current directory is contained within a
workspace, the containing workspace is used.
.IP
If the 
.I cws
workspace exists, then the parent workspace
is determined by reading 
.IR cws 's
.B Codemgr_wsdata/parent
file.
If the
.I cws
workspace does not exist, then the 
.B \-p 
option must be specified.
.LP
Some notes about the 
.I file
and
.I dir
arguments: 
.TP 3
\(bu
The "." directory may be used to specify 
that the entire workspace be copied.  
.TP
\(bu
To save users the trouble of specifying file and directory arguments every time
the 
.B bringover 
and 
.B putback 
commands are used, the arguments are
cached in the 
.IB cws /Codemgr_wsdata/args
file. If 
.I file
or 
.I dir
arguments are not specified to subsequent invocations of
.BR bringover ,
the arguments are taken from the 
.B args
file as if they were specified
on the command-line.  
.IP
The 
.B args
file is maintained by the 
.B bringover
and
.B putback
commands; they update the file whenever new arguments are specified that
cause additional files to be copied.
.IP
Note that if no arguments are
specified, and the
.B Codemgr_wsdata/args 
file does not exist,
.B bringover 
will report an error.
.IP
Users can edit the
.B args
file at any time to change its contents.
.TP
\(bu
Any valid file name that does not contain whitespace characters or a pound sign
(#) may be specified as an argument to
.BR bringover .
A relative file name specified on the command-line, as output of a
file list program 
.SM (FLP), 
or as an argument to the 
.B \-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.
.TP
\(bu
When a directory is specified as the argument to the command, 
.B bringover 
changes to that directory and invokes the default 
.SM FLP: 
.BR def.dir.flp .  
The 
.SM FLP 
writes a list of file names to 
.B stdout 
that 
.B bringover 
processes 
as if they were specified as command-line arguments.  The default version 
of 
.B def.dir.flp 
as shipped with teamware recursively lists all files 
under 
.SM SCCS 
control beneath the specified directory. Note that other 
.SM FLPs
including ones written by users, may be specified via the 
.B \-f
option.  Refer to the \fISun TeamWare User's Guide\fP and the \fISun TeamWare Solutions Guide\fP for more details regarding
.SM FLPs.
.LP
Teamware uses a multi-reader/single-writer locking mechanism and
.B bringover 
obtains a read-lock in 
.I pws
and a write-lock in 
.IR cws .
If these locks can not be obtained,
.B bringover
displays a message and exits.
.LP
Teamware checks the
.B access_control
file in the parent workspace to determine if the user is permitted to do a bringover \fIfrom\fP the workspace.  If the child workspace
already exists, it's
.B access_control
file is also checked to see if the user is allowed to do a bringover \fIinto\fP it. 
.LP
.B Bringover
displays status messages to \fBstdout\fP indicating whether a file is new,
updated or in conflict.
A copy of these messages is also written to
.IR cws 's
.B Codemgr_wsdata/history
file.
.LP
.B Bringover
executes other TeamWare commands, such as 
.BR sccsmerge ,
and expects to find them in the user's 
.SM PATH. 
Therefore, the
user's 
.SM PATH 
variable must include the directory where
teamware is installed.
.SH MESSAGES
If
.B bringover
is unable to transfer files it will display one of the following messages:
.TP 3
\(bu
\fBBringover warning: file name
.IR file  
\fBnot brought over because
    it is a 
.I type 
\fBin workspace 
.I pws
    \fBand a 
.I type 
\fBin workspace 
.I cws
.IP
A file name has a different file type (regular file vs. directory vs.
symbolic link) in 
.I pws 
and
.IR cws .
The user must take whatever action is appropriate to make the
listed files the same type or change one of the names.
.TP
\(bu
\fBBringover warning: 
.I file
\fBnot brought over because it is
    checked out in workspace 
.I pws
.IP
The file is currently checked out in 
.IR pws .
It must be checked in, or unchecked out, before it can be
brought over.
.TP
\(bu
\fBBringover warning: 
.I file
\fBnot brought over because it is
    unresolved in workspace
.I pws
.IP  
The file is currently unresolved (in conflict) in 
.I pws.
It must be resolved before it can be brought over.
.SH "ENVIRONMENT"
.LP
The following variables are used by
.BR bringover .
.TP 25
.SM CODEMGR_DIR_FLP
Contains the name of the file list program 
.SM (FLP)
to use in workspaces if one is not explicitly specified by means of the 
\fB-f\fP option.  Overrides the teamware default 
.SM FLP 
.BR def.dir.flp (1).
.TP
.SM 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
.SM PATH
environment variable.  Setting this variable causes TeamWare commands to
search for other TeamWare binaries only in
.SM PATH.
.TP
.SM CODEMGR_WS
Contains the name of a user's default workspace.  The workspace specified by 
.SM CODEMGR_WS 
is automatically used if \fB-w\fP option is not specified to a command.
.TP
.SM CODEMGR_WSPATH
Specifies a list of workspace directories to
be automatically loaded into the workspace pane 
upon tool startup.
.IP
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 
.B /export/home/ws
and
.BR ~/projects/ws ,
use the following command:
.IP
\fBexample% setenv CODEMGR_WSPATH "/export/home/ws ~/projects/ws"\fP
.LP
The following variables are set by 
.B bringover
at execution time for use within
.SM FLPs.
.TP 25
.SM CODEMGR_CMD
Contains the name of the
.B bringover
command.
.TP
.SM CODEMGR_WS_CHILD
Contains the name of the child workspace for this 
.BR bringover .
.TP
.SM CODEMGR_WS_DEST
Contains the name of the destination (to) workspace for this 
.BR bringover .
.TP
.SM CODEMGR_WS_PARENT
Contains the name of the parent workspace for this 
.BR bringover .
.TP
.SM CODEMGR_WS_SRC
Contains the name of the source (from) workspace for this 
.BR bringover .
.TP
.SM CODEMGR_WS_ROOT
The
.B bringover
command executes
.SM FLPs
in both the parent and child workspaces.
This variable contains the name of the workspace in which the
.SM FLP
is currently executing.
.SH FILES
.TP 25
.B def.dir.flp
default 
.SM FLP
for directories
.TP
.IB cws /Codemgr_wsdata/conflicts
contains the names of files in conflict 
.TP
.IB cws /Codemgr_wsdata/parent
contains the name of the parent workspace 
.TP
.IB cws /Codemgr_wsdata/locks
locks file for \fIcws\fP
.TP
.IB cws /Codemgr_wsdata/args
definition of all of \fIcws\fP
.TP
.IB cws /Codemgr_wsdata/history
log of the \fBbringover\fP
.TP
.IB pws /Codemgr_wsdata/locks
locks file for \fIpws\fP
.SH "SEE ALSO"
.I "Sun WorkShop TeamWare User's Guide"
.LP
.sp 
.nf
codemgr(1), def.dir.flp(1), dmake(1), freezept(1), putback(1), 
rcs2ws(1), resolve(1), teamware(1), twbuild(1), twfreeze(1), 
twmerge(1), twversion(1), workspace(1), ws_undo(1), 
access_control(4), args(4), children(4), conflicts(4), 
description(4), freezepointfile(4), history(4), locks(4), 
nametable(4), notification(4), parent(4), putback.cmt(4)
.LP

.SH "EXIT CODES"
.TP 10
0
\fBbringover\fP was successful, no files in conflict
.TP
1
\fBbringover\fP failed due to an error condition
.TP
4
\fBbringover\fP was successful, files in conflict
.SH WARNINGS
.SS TeamWare SCCS Restrictions
.LP
.TP 
\(bu
Avoid using the sccs subcommands cdc, comb, fix, and rmdel in TeamWare workspaces.
Using these commands can alter SCCS history files in ways which will make them impossible for TeamWare to track.  These commands also have undesirable side effects when used on files that exist in multiple workspaces that eventually may be merged. The problems with these commands are:
.TP 5
.B cdc
Can cause unnecessary branching and confusing histories.
.TP
.B comb
Completely rebuilds the SCCS history file.
.TP
.B fix
A front-end for rmdel.
.TP
.B rmdel
SCCS restricts the use of the rmdel command to remove only the most recent (leaf) delta on a branch.  If you remove a delta that also exists in another workspace, it is possible that another user will add a delta in the other workspace.  The delta that was removed in your workspace will no longer be a leaf delta when the files are merged.