PUTBACK(1)

NAME
putback - copy files from a child workspace to its parent workspace

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

DESCRIPTION

putback is the TeamWare command used to copy groups of files from a child workspace to a parent workspace. All TeamWare file transfer transactions are performed from the perspective of the child workspace; hence the putback command "puts back" files to the parent from the child workspace. A child workspace is typically created using the bringover(1) command.

The putback command attempts to make the parent and child workspaces identical with respect to the set of files specified for the putback transaction. The putback transaction is used after users make changes and test them in the child workspace. Putting the files back into the parent usually makes them accessible to other developers.

For example:

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

finds all changed files under directories dir1 and dir2 and copies them to ~/ws/mychild's parent workspace.

During a putback transaction putback may find that it cannot transfer files from the child to the parent workspace without endangering the consistency of the data in the parent. If this occurs, no files are transferred and the putback transaction is said to be blocked. Reasons that a putback transaction is blocked include:

•   A file in either workspace is currently checked out from SCCS

•   A file in the parent workspace contains changes not yet brought over into the child workspace

•   A file conflict in either workspace is currently unresolved

If any of the files designated for transfer cannot be copied, none of the files are copied.

If the putback transaction is blocked, the putback command displays the bringover command-line necessary to update the child workspace. If the -b option is specified, putback automatically invokes the appropriate bringover transaction.

The following table summarizes putback actions:

File in Parent	File in Child	Action by TeamWare

Exists	Does not exist	Block putback, notify user

Does not exist	Exists	Create the file in the parent

Unchanged	Unchanged	None

Unchanged	Changed	Update file in the parent.

Changed	Unchanged	Block putback, notify user

Changed	Changed	Block putback, notify user

Checked out*	Checked out*	Block putback, notify user

Unresolved 	Unresolved

conflict*	conflict*	Block putback, notify user

*Checked out or unresolved in either or both parent and child

OPTIONS

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

-b  If putback blocks, then execute the bringover command to update cws.

-c comment
    Provide a comment describing the putback. comment is written to pws's Codemgr_wsdata/history file. The history file contains information regarding file transfer transactions. If the -c option is not specified, putback prompts for a comment.

-f flp
    Execute the file list program, flp, to determine the list of files to process. flp writes a white-space separated list of filenames to stdout that putback processes as if there were specified on the command-line. More than one -f option may be specified. If an flp exits with a non-zero status, putback 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 to be used for that specific invocation of the putback command. pws 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 putback to print a message for all files, including those that don't need to be put back. 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.

    The parent workspace is taken from cws's Codemgr_wsdata/parent file or the command-line as specified by the -p option.

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 putback, 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, putback 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 putback. 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, putback changes to that directory and invokes the default FLP: def.dir.flp. The FLP writes a list of file names to stdout that putback 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 TeamWare User's Guide for more details regarding FLPs.

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

TeamWare checks the access_control file in the parent workspace to determine if the user running the command is allowed to do a putback into the workspace. The access_control file in the child workspace is also checked to see if the user is allowed to do a putback from that workspace.

putback displays status messages to stdout indicating if a file is new or updated. A copy of these messages is also written to pws's Codemgr_wsdata/history file.

putback 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
putback tries to ensure that pws is stable and consistent. Therefore, putback has some restrictions on the conditions under which it puts back files. If any files cannot be put back, then no files are put back.

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

•   The following files have changed in workspace pws and must be brought over:

    The listed files contain changes that have not yet been brought over into cws. To protect the consistency of pws, these changed files must be brought over and tested before the putback can complete.

•   The following files are new in workspace pws and must be brought over:

    The listed files exist in pws but not in cws. They must be brought over into cws before the putback can complete.

•   The following files have different file types in the workspaces:

    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.

•   The following files are currently checked out in workspace ws:

    The named files are currently checked out in ws and must be checked in before putback can complete.

•   The following files need to be resolved in workspace ws:

    The named files are currently in conflict in ws and must be resolved(1) before putback can complete.

Also, when a putback blocks and comments have been specified, the comments are written to the file cws/Codemgr_wsdata/putback.cmt and putback prints the message:

•   Your putback comments have been saved in file
    "cws/Codemgr_wsdata/putback.cmt"

ENVIRONMENT

The following variables are used by putback.

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 will automatically be 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 putback at execution time for use within FLPs.

CODEMGR_CMD
    Contains the name of the putback command.

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

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

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

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

CODEMGR_WS_ROOT
    The putback 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/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/putback.cmt
    when putback blocks, the comments are saved here

pws/Codemgr_wsdata/history
    log of the putback

pws/Codemgr_wsdata/locks
    locks file for pws

SEE ALSO
TeamWare User's Guide

bringover(1), def.dir.flp(1), resolve(1), sccs-get(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   putback was successful

1   putback failed due to an error condition

2   putback blocked, did not execute bringover

3   putback blocked, executed successful bringover

4   putback blocked, executed successful bringover that found files in conflict