.\" .\" aegis - project change supervisor .\" Copyright (C) 1991-1995, 1998, 2001 Peter Miller; .\" All rights reserved. .\" .\" 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 2 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, write to the Free Software .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA. .\" .\" MANIFEST: User Guide, The History Tool, Using RCS .\" .bp .nh 2 "Using RCS" .LP The entries for the commands are listed below. RCS uses a slightly different model than aegis wants, so some maneuvering is required. The command strings in this section assume that the RCS commands .I ci and .I co and .I rcs and .I rlog are in the command search PATH, but you may like to hard-wire the paths, or set PATH at the start of each. You should also note that the strings are always handed to the Bourne shell to be executed, and are set to exit with an error immediately a sub-command fails. .LP In these commands, the RCS file is kept unlocked, since only the owner will be checking changes in. The RCS functionality for coordinating shared access is not required. .LP One advantage of using RCS version 5.6 or later is that binary files are supported, should you want to have binary files in the baseline. .nh 3 "history_create_command" .LP This command is used to create a new file history. This command is always executed as the project owner. .LP The following substitutions are available: .IP ${Input} absolute path of the source file .IP ${History} absolute path of the history file .LP The entry in the .I "config" file looks like this: .E( history_create_command = "ci -u -d -M -m$c -t/dev/null \e $i $h,v; rcs -U $h,v"; .E) .LP .\" The "\f(CWci -f\fP" option is used to specify that .\" a copy is to be checked-in even if there are no changes. The "\f(CWci -u\fP" option is used to specify that an unlocked copy will remain in the baseline. The "\f(CWci -d\fP" option is used to specify that the file time rather than the current time is to be used for the new revision. The "\f(CWci -M\fP" option is used to specify that the mode date on the original file is not to be altered. The "\f(CWci -t\fP" option is used to specify that there is to be no description text for the new RCS file. The "\f(CWci -m\fP" option is used to specify that the change number is to be stored in the file log if this is actually an update (typically from .I aenf after .I aerm on the same file name). The "\f(CWrcs -U\fP" option is used to specify that the new RCS file is to have unstrict locking. .LP It is essential that the \fIhistory_\%create_\%command\fP and the \fIhistory_\%put_\%command\fP are identical. It is a historical accident that there are two separate commands: before Aegis supported branches, this was not a requirement. .nh 3 "history_get_command" .LP This command is used to get a specific edit back from history. This command is always executed as the project owner. .LP The following substitutions are available: .IP ${History} absolute path of the history file .IP ${Edit} edit number, as given by history_\%query_\%command .IP ${Output} absolute path of the destination file .LP The entry in the .I "config" file looks like this: .E( history_get_command = "co -r'$e' -p $h,v > $o"; .E) .LP The "\f(CWco -r\fP option is used to specify the edit to be retrieved. The "\f(CWco -p\fP option is used to specify that the results be printed on the standard output; this is because the destination filename will .I never look anything like the history source filename. .nh 3 "history_put_command" .LP This command is used to add a new "top-most" entry to the history file. This command is always executed as the project owner. .LP The following substitutions are available: .IP ${Input} absolute path of source file .IP ${History} absolute path of history file .LP The entry in the .I "config" file looks like this: .E( history_put_command = "ci -u -d -M -m$c -t/dev/null \e $i $h,v; rcs -U $h,v"; .E) .LP Uses ci to deposit a new revision, using -d and -M as described for history_create_command. The -m flag stores the change number in the file log, which allows \fIrlog\fP(1) to be used to find the Aegis change numbers to which each revision of the file corresponds. .LP .\" The "\f(CWci -f\fP" option is used to specify that .\" a copy is to be checked-in even if there are no changes. The "\f(CWci -u\fP" option is used to specify that an unlocked copy will remain in the baseline. The "\f(CWci -d\fP" option is used to specify that the file time rather than the current time is to be used for the new revision. The "\f(CWci -M\fP" option is used to specify that the mode date on the original file is not to be altered. The "\f(CWci -m\fP" option is used to specify that the change number is to be stored in the file log, which allows .I rlog to be used to find the change numbers to which each revision of the file corresponds. .LP It is essential that the \fIhistory_\%create_\%command\fP and the \fIhistory_\%put_\%command\fP are identical. It is a historical accident that there are two separate commands: before Aegis supported branches, this was not a requirement. .nh 3 "history_query_command" .LP This command is used to query what the history mechanism calls the top-most edit of a history file. The result may be any arbitrary string, it need not be anything like a number, just so long as it uniquely identifies the edit for use by the .I history_get_command at a later date. The edit number is to be printed on the standard output. This command is always executed as the project owner. .LP The following substitutions are available: .IP ${History} absolute path of the history file .LP The entry in the .I "config" file looks like this: .E( history_query_command = "rlog -r $h,v | \e awk '/^head:/ {print $$2}'"; .E) .nh 3 "merge_command" .LP RCS also provides a .I merge program, which can be used to provide a three-way merge. .LP All of the command substitutions described in .I aesub (5) are available. In addition, the following substitutions are also available: .IP ${ORiginal} The absolute path name of a file containing the version originally copied. Usually in a temporary file. .IP ${Most_Recent} The absolute path name of a file containing the most recent version. Usually in the baseline. .IP ${Input} The absolute path name of the edited version of the file. Usually in the development directory. Aegis usually moves the original source file aside, so that the output may have the source file's name. .IP ${Output} The absolute path name of the file in which to write the difference listing. Usually in the development directory, usually the name of a change source file. .LP The entry in the .I "config" file looks like this: .E( merge_command = "set +e; \e merge -p -L baseline -L C$c \e $mr $orig $in > $out; \e test $? -le 1"; .E) .PP The "\f(CWmerge -L\fP" options are used to specify labels for the baseline and the development directory, respectively, when conflict lines are inserted into the result. The "\f(CWmerge -p\fP" options is used to specify that the results are to be printed on the standard output. .PP It is important that this command does not move its input and output files around, otherwise this contradicts the warnings Aegis may issue to the user. (In previous versions of Aegis, this was necessary, however this is no longer the case.) .LP \fBWarning:\fP The version of \fIdiff3\fP(1) available to RCS \fImerge\fP(1) has a huge impact on its performance and utility. You need to grab and install GNU diff to get the best results. \fIUnfortunately\fP the diff tool used by RCS \fImerge\fP(1) is determined at compile time. This means that you need to build and install GNU diff package \fIbefore\fP you build and install GNU RCS package. .nh 3 "Referential Integrity" Many history tools (including RCS) can modify the contents of the file when it is committed. While there are usually options to turn this off, they are seldom used. The problem is: if the commit changes the file, the source in the repository now no longer matches the object file in the repository - \fIi.e.\fP the history tool has compromised the referential integrity of the repository. .E( history_put_trashes_file = warn; .E) If you use RCS keyword substitution, you will need this line. (The default is to report a fatal error.) .LP Another reason for this option is that it tells Aegis it needs to recalculate the file's fingerprint after a checkin. .nh 3 "Templates" .LP The .I lib/config.example/rcs file in the Aegis distribution contains all of the above commands, so that you may readily insert them into your project .I config file. .LP Also, there are some subtleties to writing the commands, which are not present in the above examples. In particular, being able to support file names which contain characters which are special to the shell requires the use of the ${quote} substitution around all of the files names in the commands. .LP In addition, it is possible to have a much more useful description for the \fB\-m\fP option. For example: ``\f[CW]-m${quote ($version) ${change description}}\fP'' inserts the version number and the brief description into the file's log. This means that using the \fIrlog\fP(1) command will provide quite useful summaries. .nh 3 "Binary Files" RCS (version 5.6 and later) is able to cope with binary files. It does so by saving a whole copy of the file at each check-in. .PP If you want Aegis to transparently encode all such files, simply leave the \fIhistory_\%content_\%limitation\fP field unset. .PP If you want to check-in binary files, add the \f[CW]\-kb\fP option to each of the \f[CW]rcs -U\fP commands in the fields above, and also set .E( history_content_limitation = binary_capable; .E) so that Aegis knows that no encoding is desired. .nh 3 "history_put_trashes_files" If you use RCS keywords, such as $\f[CW]id\fP$ or $\f[CW]log\fP$, this will result in the file in the baseline being changed by RCS at integrate pass. This is \fIafter\fP the build. The result is that the source files no longer match the object files. Oops. .LP While such mechanism are essential when using only a simple history tool, far more information may be obtained using the file history report (\f[CW]aer file_history\fP \fIfilename\fP), rendering such crude methods unnecessary. .LP In addition to expected expansions in file header comments, this can also be very destructive if, for example, such a string appeared in a uuencoded or MIME base 64 encoded file. .LP If you wish to prevent RCS from performing keyword expansion, used the \f[CW]rcs -kb\fP option. .LP If, however, you wish to keep using keyword expansion, set .E( history_tool_trashes_file = warning; .E) to cause Aegis to warn you, rather than fail.