." ." Copyright (c) 1998 by Sun Microsystems, Inc. ." ." @(#)putback.1 1.44 92/07/29 SMI ." .TH PUTBACK 1 "00/03/28 Sun WorkShop 6" .ds ]W .SH NAME putback \- copy files from a child workspace to its parent workspace .SH SYNOPSIS .B putback .RB [ " \-b " ] .RB [ " \-B " ] .RB [ " \-c " .IR comment " ]" .RB [ " \-m " .IR comment_file " ]" .if n .br .RB [ " \-d " ] .RB [[ " \-f " .IR flp " ] ... ]" .RB [ " \-g " ] .RB [ " \-n " ] .RB [ " \-M " .IR ir-list " ] .if n .br .RB [ " \-p " .IR pws " ]" .RB [ " \-q " ] .RB [ " \-v " ] .RB [ " \-V " ] .RB [ " \-w " .IR cws " ]" .if n .br .RI [ "files or dirs" \&.\|.\|.] .SH DESCRIPTION .IX "CodeManager" "TeamWare" "putback" "" "\fBputback\fP" .LP .B 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 .B putback command "puts back" files to the parent from the child workspace. A child workspace is typically created using the .BR bringover (1) command. .LP The .B 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. .LP For example: .sp .in +3 \fBexample% putback -w ~/ws/mychild dir1 dir2\fP .in -3 .sp finds all changed files under directories .B dir1 and .B dir2 and copies them to .BR ~/ws/mychild 's parent workspace. .LP During a putback transaction .B 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 \fIblocked\fP. Reasons that a putback transaction is blocked include: .TP 3 \(bu A file in either workspace is currently checked out from .SM SCCS .TP \(bu A file in the parent workspace contains changes not yet brought over into the child workspace .TP \(bu A file conflict in either workspace is currently unresolved .LP If any of the files designated for transfer cannot be copied, none of the files are copied. .LP If the putback transaction is blocked, the .B putback command displays the .B bringover command-line necessary to update the child workspace. If the \fB\-b\fP option is specified, .B putback automatically invokes the appropriate bringover transaction. .LP The following table summarizes .B putback actions: .LP .nf .ta 1.75i 3.5i \f3File in Parent File in Child Action by TeamWare\f1 .sp 1 Exists Does not exist Block putback, notify user .sp 0 Does not exist Exists Create the file in the parent .sp 0 Unchanged Unchanged None .sp 0 Unchanged Changed Update file in the parent. .sp 0 Changed Unchanged Block putback, notify user .sp 0 Changed Changed Block putback, notify user .sp 0 Checked out* Checked out* Block putback, notify user .sp 0 Unresolved Unresolved .sp 0 conflict* conflict* Block putback, notify user .fi .sp *Checked out or unresolved in either or both parent and child .sp .SH OPTIONS .TP 10 .B \-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 .BR putback with the .BR ws_undo command. .TP .B \-b If .B putback blocks, then execute the .B bringover command to update .IR cws . .TP .BI \-c " comment" Provide a .I comment describing the .BR putback . .I comment is written to .IR pws 's .B Codemgr_wsdata/history file. The .B history file contains information regarding file transfer transactions. The history file contains information regarding file transfer transactions. If one of the .B -m or .B -c options is not specified, putback prompts for a comment. 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 .BI \-m " comment_file" Specify a text file containing comments that describe the putback. Contents of the file are written to the .IR pws's .B Codemgr_wsdata/history file. The .B history file contains information regarding file transfer transactions. If one of the .B -m or .B -c options is not specified, putback prompts for a comment. 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 \-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 writes a white-space separated list of filenames to .B stdout that .B putback processes as if there were specified on the command-line. More than one .B \-f option may be specified. If an .I flp exits with a non-zero status, .B putback 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 .B \-M ir-list Allows user to include a Integration Request indentifier required by a putback validation program. If putback validation has been switched on, you must supply one or more Integration Request (IR) numbers for the putback. When specifying more than one IR number on the command line, ir-list takes the form of a quoted, space-separated list. If the validation program returns a non-zero exit status, the putback is blocked. .IP \fBexample% putback -w child -p parent -c comment -M "4204563 4204564"\fP .IP This example means that if validation is ON for the workspace 'parent' then the validation program will be invoked with arguments: .LP .nf .ta 1i 1.4i 3.1i \f3 Arg Example Description\f1 .sp 1 $1 name of the user who runs putback .sp 0 $2 /parent name of the parent workspace .sp 0 $3 /child name of the child workspace .sp 0 $4 4204563 4204564 list of Integration Request IDs .sp 0 $5 /tmp/ temp file containing the list of files to be modified .fi .sp .TP .BI \-p " pws" Names the parent workspace to be used for that specific invocation of the .B putback command. .IR pws is 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 putback to print a message for all files, including those that don't need to be put back. If both the .B \-v option and the .B \-q option are specified, the last one takes precedence. .TP .BI \-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 The parent workspace is taken from .IR cws 's .B Codemgr_wsdata/parent file or the command-line as specified by the \fB\-p\fP option. .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 putback , 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 putback 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 putback . 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 putback 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 putback 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 \fITeamWare User's Guide\fP for more details regarding .SM FLPs. .LP TeamWare uses a multi-reader/single-writer locking mechanism and .B putback obtains a read-lock in .I cws and a write-lock in .IR pws . If these locks cannot be obtained, .B putback displays a message and exits. .LP TeamWare checks the .B access_control file in the parent workspace to determine if the user running the command is allowed to do a putback .I into the workspace. The .B access_control file in the child workspace is also checked to see if the user is allowed to do a putback .I from that workspace. .LP .B putback displays status messages to \fBstdout\fP indicating if a file is new or updated. A copy of these messages is also written to .IR pws 's .B Codemgr_wsdata/history file. .LP .B putback 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 .B putback tries to ensure that .I pws is stable and consistent. Therefore, .B 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. .LP If .B putback is unable to transfer files it will display one of the following messages: .TP 3 \(bu \fBThe following files have changed in workspace .I pws \fBand must be brought over:\fP .IP The listed files contain changes that have not yet been brought over into .IR cws . To protect the consistency of .IR pws , these changed files must be brought over and tested before the .B putback can complete. .TP \(bu \fBThe following files are new in workspace .I pws \fBand must be brought over: .IP The listed files exist in .I pws but not in .IR cws . They must be brought over into .I cws before the .B putback can complete. .TP \(bu \fBThe following files have different file types in the workspaces:\fP .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 \fBThe following files are currently checked out in workspace .IR ws : .IP The named files are currently checked out in .I ws and must be checked in before .B putback can complete. .TP \(bu \fBThe following files need to be resolved in workspace .IR ws : .IP The named files are currently in conflict in .I ws and must be .BR resolve d(1) before .B putback can complete. .LP Also, when a .B putback blocks and comments have been specified, the comments are written to the file .IB cws /Codemgr_wsdata/putback.cmt and .B putback prints the message: .TP 3 \(bu \fBYour putback comments have been saved in file .br "\fIcws\fB/Codemgr_wsdata/putback.cmt"\fP .SH "ENVIRONMENT" .LP The following variables are used by .BR putback . .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 will automatically be used if \fB-w\fP option is not specified to a command. .LP .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 putback at execution time for use within .SM FLPs. .TP 25 .SM CODEMGR_CMD Contains the name of the .B putback command. .TP .SM CODEMGR_WS_CHILD Contains the name of the child workspace for this .BR putback . .TP .SM CODEMGR_WS_DEST Contains the name of the destination (to) workspace for this .BR putback . .TP .SM CODEMGR_WS_PARENT Contains the name of the parent workspace for this .BR putback . .TP .SM CODEMGR_WS_SRC Contains the name of the source (from) workspace for this .BR putback . .TP .SM CODEMGR_WS_ROOT The .B putback 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 FLP for directories .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/putback.cmt when .B putback blocks, the comments are saved here .TP .IB pws /Codemgr_wsdata/history log of the \fIputback\fP .TP .IB pws /Codemgr_wsdata/locks locks file for \fIpws\fP .SH "SEE ALSO" .IR "Sun WorkShop TeamWare User's Guide" .LP .sp .nf bringover(1), codemgr(1), def.dir.flp(1), dmake(1), freezept(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) .fi .SH "EXIT CODES" .TP 10 0 \fBputback\fP was successful .TP 1 \fBputback\fP failed due to an error condition .TP 2 \fBputback\fP blocked, did not execute \fBbringover\fP .TP 3 \fBputback\fP blocked, executed successful \fBbringover\fP .TP 4 \fBputback\fP blocked, executed successful \fBbringover\fP that found 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.