'\" t
.\" aegis - project change supervisor
.\" Copyright (C) 1991-1994, 1996-1999, 2001, 2002, 2004-2010, 2012 Peter Miller
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
.\" General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
.\"
.so lib/en/man1/z_name.so
.TH "\*(n) \-CoPy_file" 1 \*(N) "Reference Manual"
.SH NAME
aegis  copy file \- copy a file into a change
.XX "aecp(1)" "copy a file into a change"
.SH SYNOPSIS
.B \*(n)
.B \-CoPy_file
[
.IR option ...
]
.IR filename ...
.br
.B \*(n)
.B \-CoPy_file
.B \-INDependent
[
.IR option ...
]
.IR filename ...
.br
.B \*(n)
.B \-CoPy_file
.B \-List
[
.IR option ...
]
.br
.B \*(n)
.B \-CoPy_file
.B \-Help
.SH DESCRIPTION
The
.I \*(n)
.I \-CoPy_file
command is used to
copy a file into a change.
The named files will be copied from the baseline into
the development directory,
and added to the list of files in the change.
The version of files copied from the baseline is remembered.
.PP
This command may be used to copy tests into a change,
not just source files.
Tests are treated just like any other source file,
and are subject to the same process.
.PP
Warning:
If there are files in the development directory of the same name
they will be overwritten by this command.
.PP
You may also name directories.
All of the source files in the directories named,
and all directories below them,
will be copied from the baseline into the development directory,
and added to the list of files in the change.
.PP
When copying files explicitly,
it is an error if the file is already part of the change.
When you name a directory,
all of the source files in the project below that directory are copied,
except any which are already in the change.
It is an error if none of the files implicitly named
by the directory can be used.
.PP
If you want to change a copied source file to be executable (shell
scripts, for example) then you simply use the normal \fIchmod\fP(1)
command; the reverse to make it not executable.  If any of the file's
executable bits are set at \fIaede\fP(1) time the file is remembered as
executable and all execute bits (minus the project's umask) will be set
by subsequent \fIaecp\fP(1) commands.
.so lib/en/man1/z_intuit.so
.SS Process Side Effects
This command will cancel any build or test registrations,
because adding another file logically invalidates them.
If the project
configuration
file was added,
any diff registration will also be canceled.
.PP
When the change files are listed
(\fI\*(n) \-List Change_Files \-TERse\fP)
the copied files will appear in the listing.
When the project files are listed with an explicit change number
(\fI\*(n) \-List Project_Files \-TERse \-Change\fP \f(CWN\fP)
none of the change's files,
including the copied files,
will appear in the terse listing.
These two features are very helpful when calling \*(n) from within
a DMT to generate the list of source files.
.so lib/en/man1/z_bl_lock.so
.so lib/en/man1/z_test_corr.so
.SS Notification
The \fIcopy_file_command\fP in the project \fIconfig\fP file is run,
if set.  The \fIproject_\%file_\%command\fP is also run, if set, and
if there has been an integration recently.  See \fIaepconf\fP(5) for
more information.
.so lib/en/man1/z_promotion.so
.SH OPTIONS
The following options are understood:
.so lib/en/man1/o_as_needed.so
.so lib/en/man1/o_baserel.so
.so lib/en/man1/o_branch.so
.so lib/en/man1/o_change.so
.so lib/en/man1/o_delta.so
.so lib/en/man1/o_help.so
.TP 8n
.B \-INDependent
This option is used to specify that the copy is to be run independent
of any particular change.
The files will be copied relative to the current directory
(but see the \-Output\[hy]Directory\fP option).
.so lib/en/man1/o_keep.so
.so lib/en/man1/o_list.so
.so lib/en/man1/o_nolog.so
.TP 8n
\fB\-Output\fP \fIfilename\fP
.br
This option may be used to specify an output file
of a file being copied from the baseline.
Only one baseline file may be named when this option is used.
The file name "\-" is understood to mean the standard output.
This option does not add the file to the set of change files.
.I "No locks"
are taken when this option is used,
not even the baseline read lock.
.TP 8n
\fB\-Output\[hy]Directory\fP \f[I]path\fP
This option may only be used with the \fB\-INDependent\fP option, to specify
the output directory for the copied files, rather than the current directory.
The directory will be created if it does not exist already.
.so lib/en/man1/o_overw.so
.so lib/en/man1/o_project.so
.TP 8n
.B \-Read_Only
This option may be used to specify that the file is to be used to
insulate the change from the baseline.  The user does not intend to edit
the file.  These files must be uncopied before development may end.
.TP 8n
.B \-REScind
This option may be used to rescind (roll back) a completed change.
The change to rescind (roll back) is specified in the usual way, with
one of the \-delta options.
.so lib/en/man1/o_terse.so
.so lib/en/man1/o_trunk.so
.so lib/en/man1/o_verbose.so
.so lib/en/man1/o_wait.so
.so lib/en/man1/o__rules.so
.SH RECOMMENDED ALIAS
The recommended alias for this command is
.nf
.ta 8n 16n
csh%    alias aecp '\*(n) \-cp \e!* \-v'
sh$     aecp(){\*(n) \-cp "$@" \-v}
.fi
.SH ERRORS
It is an error if
the change is not in the
.I "being developed"
state.
.br
It is an error if
the change is not assigned to the current user.
.br
It is an error if
the file is already in the change and the
.B \-OverWrite
option is not specified.
.so lib/en/man1/z_exit.so
.br
.ne 1i
.SH EXAMPLES
Here are some simple examples.
Remember that most commands are relative to the current directory, even
though these examples assume you are at the base of the development
directory tree.
.SS Copy Whole Project
To copy the whole project into your change, use the command
.RS
aecp .
.RE
The trailing dot is part of the command, it means "the currect directory
and everything below it".  This works for any directory in your project source
tree, if you want to be more seledctive.
.SS Prroduce Earlier Project Version
You you wish to exactly reproduces the sources for an earlier version
of your project, you need to know the edelta number (use \fIael
proj\[hy]history\fP to find it).  Then use this command:
.RS
aecp \-delta \fIn\fP .
.RE
where \fIn\fP is the delta number from the project history.
Again, the trailing dot is part of the command.
By using the \fI$version\fP substitution (see \fIaesub\fP(5) for more
information) you can embed this delta number into your program before
distributing it.
.PP
It is also possible to give a previous change number, instead,
using this command:
.RS
aecp \-delta\[hy]from\[hy]change \fIn\fP .
.RE
where \fIn\fP is the change number of interest.
Again, the trailing dot is part of the command.
.SS Rescind a Change
When you need to rescind (back out) a completed change, it will probably
have been some time ago, so you need to know the delta number or change
number.
Use this command:
.RS
aecp \-delta \fIn\fP \-rescind .
.RE
where \fIn\fP is the delta number of interest.
All of the other \-delta variantrs also work, so if you know the change
number, you can be more selective about which files to copy:
.RS
aecp \-delta\[hy]from\[hy]change \fIn\fP `aegis \-l cf \-ter \-c \fIn\fP`
.RE
where \fIn\fP is the change number of interest.
This only copies the files which were in the offending change.
.br
.ne 1i
.SH SEE ALSO
.TP 8n
.IR aeb (1)
build also takes a baseline read lock (non\[hy]exclusive)
.TP 8n
.IR aecpu (1)
reverse action of aecp
.TP 8n
.IR aedb (1)
begin development of a change
.TP 8n
.IR aedn (1)
assign a name to a delta
.TP 8n
.IR aeipass (1)
integrate pass takes a baseline write lock (exclusive)
.TP 8n
.IR aemv (1)
rename a file as part of a change
.TP 8n
.IR aenf (1)
add a new file to a change
.TP 8n
.IR aerm (1)
add files to be deleted to a change
.TP 8n
.IR aeuconf (5)
user configuration file format
.so lib/en/man1/z_cr.so
.\" vim: set ts=8 sw=4 et :