Man Page putback.1
NAME
putback - copy files from a child workspace to its parent
workspace
SYNOPSIS
putback [ -b ] [ -B ] [ -c comment ] [ -m comment_file ]
[ -d ] [[ -f flp ] ... ] [ -g ] [ -n ] [ -M ir-list ]
[ -p pws ] [ -q ] [ -v ] [ -V ] [ -w cws ]
[ -i include_file] [ -x exclude_file ] [files or dirs ...]
DESCRIPTION
putback is the Sun WorkShop TeamWare command used to copy
groups of files from a child workspace to a parent
workspace. All Sun WorkShop TeamWare file transfer transac-
tions 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 speci-
fied 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:
o A file in either workspace is currently checked out from
SCCS
o A file in the parent workspace contains changes not yet
brought over into the child workspace
o 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 Sun WorkShop 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 com-
mand 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 one of the -m or
-c options is not specified, putback prompts for a
comment. 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.
-m comment_file
Specify a text file containing comments that
describe the putback. Contents of the file are
written to the child's Codemgr_wsdata/history
file. The history file contains information
regarding file transfer transactions. If one of
the -m or -c options is not specified, putback
prompts for a comment. If both -m and -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.
-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 writes a
white-space separated list of filenames to stdout
that putback processes as if they 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. 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 ir-list
Allows user to include a Integration Request
indentifier required by a putback validation pro-
gram. 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.
example% putback -w child -p parent -c comment -M
"4204563 4204564"
This example means that if validation is ON for
the workspace 'parent' then the validation program
will be invoked with arguments:
Arg Example Description
$1 <user> name of the user who runs putback
$2 <cwd>/parent name of the parent workspace
$3 <cwd>/child name of the child workspace
$4 4204563 4204564 list of Integration Request IDs
$5 /tmp/<temptfile> temp file containing the list of files
to be modified
-p pws
Names the parent workspace to be used for that specific
invocation of the putback command. pws is 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.
-V Display the version being run on standard output.
-i include_file
The include_file contains a list of files and direc-
tories that are put back to a parent workspace. The
names of files should be separated with line feed.
-x exclude_file
The exclude_file contains a list of files and direc-
tories that are excluded from the putback transaction.
The names of files should be separated with line feed.
-wcws
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:
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 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. 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 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.
o When a directory is specified as the argument to the com-
mand, 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 Sun WorkShop 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 WorkShop TeamWare User's Guide
for more details regarding FLPs.
Sun WorkShop 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.
Sun WorkShop TeamWare checks the access_control file in the
parent workspace to determine if the user running the com-
mand 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 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 direc-
tory where Sun WorkShop 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:
o The following files have been 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.
o 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.
o 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.
o 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.
o 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 speci-
fied, the comments are written to the file cws
Codemgr_wsdata/putback.cmt and putback prints the message:
o 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. Over-
rides the Sun WorkShop 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 will
automatically be used if -w option
is not specified to a command.
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 destina-
tion (to) workspace for this put-
back.
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
Sun WorkShop TeamWare User's Guide
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)
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
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.