Man Page bringover.1




NAME

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


SYNOPSIS

     bringover [ -B ] [ -c comment ] [ -m comment_file ] [ -C ]
     [ -d ] [[ -f flp ] ... ] [ -g ] [ -n ] [ -p pws ] [ -q ]
     [ -v ] [ -V ] [ -w cws ]
     [ -i include_file] [ -x  exclude_file] [files or dirs ...]


DESCRIPTION

     bringover is the Sun WorkShop TeamWare command used to  copy
     one  or  more  files  from  a  parent  workspace  to a child
     workspace.  Sun WorkShop  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 tran-
     saction,  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  display-
     ing the files in filemerge(1), a graphical three-way differ-
     ences program.

     The -p option need not be specified when updating an  exist-
     ing  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 dura-
     tion 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 Sun WorkShop 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. If both -m and -c options are specified,
               the content of both comments are added to the his-
               tory  file  in  the  order  that  the options were
               specified on the command line.

     -C        Force all updates to be conflicts.

     -d        Adds delta comments to transaction output  and  e-
               mail  notification,  including delta number, owner
               and comments.

     -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.  Nor-
               mally g-files are extracted after they are brought
               over.  This option improves file transfer  perfor-
               mance although it shifts the responsibility to the
               user to do the appropriate gets at a later time.

     -n        Shows what will be done without executing the com-
               mand.

     -m comment_file
               Specify  a  text  file  containing  comments  that
               describe  the  bringover. Contents of the file are
               written to the child'sCodemgr_wsdata/history file,
               which  records  information regarding the transfer
               of files. If both -m and -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.

     -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 conflict-
               ing 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 pre-
               cedence.

     -V        Display the version being run on standard output.

     -i include_file
               The include_file contains  a  list  of  files  and
               directories  that  are to be copied from the child
               workspace. The names of files should be  separated
               with line feed.

     -x exclude_file
               The exclude_file contains  a  list  of  files  and
               directories  that  are excluded from the bringover
               transaction.  The  names  of   files   should   be
               separated with line feed.

     -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 speci-
               fied.

     Some notes about the file and dir arguments:

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

     o  To save users the trouble of specifying file  and  direc-
        tory  arguments every time the bringover and putback com-
        mands are used, the arguments are cached in  the  child's
        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. It is recommended to use codemgrtool(1) to edit
        args file.

     o  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.

     o  When a directory is specified as the argument to the com-
        mand, 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 direc-
        tory.  Note  that  other  FLPs  including ones written by
        users, may be specified via the -f option.  Refer to  the
        Sun  WorkShop  TeamWare User's Guide and the Sun WorkShop
        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  Sun  WorkShop  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:

     o  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.

     o  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.

     o  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.  Over-
                              rides  the  teamware  default   FLP
                              def.dir.flp(1).

     CODEMGR_PATH_ONLY        Sun  WorkShop   TeamWare   commands
                              first search for other Sun WorkShop
                              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 Sun WorkShop
                              TeamWare  commands  to  search  for
                              other    Sun    WorkShop   TeamWare
                              binaries only in PATH.

     CODEMGR_WS               Contains  the  name  of  a   user's
                              default  workspace.   The workspace
                              specified by CODEMGR_WS is automat-
                              ically  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 follow-
                              ing 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  destina-
                              tion (to) workspace for this bring-
                              over.

     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 bring-
                              over.

     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 con-
                              flict

     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 WorkShop TeamWare User's Guide


     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)


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


WARNINGS

  Sun WorkShop TeamWare SCCS Restrictions
     o    Avoid using the sccs subcommands cdc,  comb,  fix,  and
          rmdel in Sun WorkShop TeamWare workspaces.  Using these
          commands can alter SCCS history  files  in  ways  which
          will  make them impossible for Sun WorkShop 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:

     cdc  Can cause  unnecessary  branching  and  confusing  his-
          tories.

     comb Completely rebuilds the SCCS history file.

     fix  A front-end for rmdel.

     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.