table of contents
fhist(1) | General Commands Manual | fhist(1) |
NAME¶
fhist - file historySYNOPSIS¶
fhist filename... option...DESCRIPTION¶
The fhist program is used to keep track of the successive versions of a file. Using this program, you can remember all of your changes to a file, and get back any one of the old versions. The uses of this ability are:- 1.
- You can make a series of tentative edits to the file, and if necessary back up to the last "good" edit.
- 2.
- You can delete old subroutines and code from your file which are obsolete, but still be able to get them back in the future in case a need for them arises.
- 3.
- You can compare two versions of the file to see how you fixed some old problem, so that you can check up on the correctness of the fix at a later date.
- 4.
- You get a record of your remarks for each version, so that you can quickly know what bugs were fixed, and what features were implemented.
- 5.
- The date the file was last edited can be automatically stored in the file.
Keyword Substitution¶
It is possible to have information about the state of the file inserted into the file. See the -Modify and -No‐Keywords options, below, for more infromation.OPTIONS¶
The following options are understood:- -Path pathname
-
Modules are stored in a directory, called the
module storage directory. The default directory is FHIST, and therefore
is located relative to your current directory. This is convenient when you are
in a directory containing many modules, and you want a local storage directory
to contain just those modules. If you use the -p option, then you can
locate the storage directory anywhere you choose. This is useful if you choose
to have a common storage directory for all of your files, independent of where
they actually are used.
The files inside of the storage directory should not be changed by you. Doing so
will probably corrupt your edit history, causing errors when you extract old
revisions. For your information, though, each module is stored as two files in
the directory. The one with the .s suffix is a copy of the newest
version of the module, with one extra line at the beginning. The one with the
.e suffix is the edit history of the module, and contains the
information needed to extract previous revisions of the module. Thus if the
edit history is ever corrupted, you will at least have the most recent version
of the module.
- -MaKe_Path
- This option may be used to request that the path directory be created automatically if it does not yet exist. This works for both the directory specified by the -Path option, and for the default. Intermediate directories will also be created if necessary.
- -BINary
- This option may be used to specify that the file is binary, that it may contain NUL characters. It is essential that you have consistent presence or absence of the -BINary option for each file when combined with the -CReate, -Update, -Conditional_Update and -Extract options. Failure to do so will produce inconsistent results. Note: this is different behaviour to the fcomp(1) option of the same name. Note: the -BINary option does not imply the -No‐Keywords option.
- -CReate
-
To use the fhist program for the first
time, you need to create your storage directory. Therefore, cd to the
directory where you want it to be, which is probably the directory containing
the modules you want to save the revisions of. Then create the directory
FHIST (or some other name if you don't want to use the default name).
To start using a module under fhist, you must first use the
-CReate option. This creates the initial edit for that module in the
storage directory, with the contents of the specified module as the initial
edit. Thus, if you have a source file prog.c, then the command:
creates the initial edit of the module. As part of this process, you are asked
to provide remarks about the file. These remarks can be seen later using the
-List option (described below). After the remarks have been typed, the
contents of the file are then saved. You can then delete the file
prog.c if desired, and fhist would be able to recreate it later.
Or you can leave it there as the working copy of the module.
The -CReate option may be combined with the -Update or
-Conditional_Update options to create the file if required.
fhist prog.c -create
- -Update
-
To save another revision of the module, you
use the -Update option. This updates the files in the storage directory
to include the latest changes. Remarks are again asked for so that you can
document why you made this edit. Thus, to continue the example, after editing
prog.c, the command:
will save the changes as a new edit. This command compares the newest version of
the module to the previous version, saves the differences in the .e
file, and copies the new source to the .s file. At this point, you can
once again delete the prog.c file if desired, and later get back either
of the two versions of the program.
The fhist program handles quota or disk full problems during a create or
update operation without damage occurring to the edit history files. If an
edit cannot be completed because of such problems, the edit is backed out
completely, and you will get an error message about the disk problem. There is
no need for any error recovery in this case, other than retrying the update
when more disk space is available. The fhist program also disables
signals during the critical file operations, so you do not have to worry about
damaging the edit history files because of attempts to quit out of the
program.
The -CReate option may be combined with the -Update or
-Conditional_Update options to create the file if required.
fhist prog.c -u
- -Input filename
-
In either the -CReate or -Update
options, the file containing the new version of the module defaults to the
same name as the module. In the example, the module prog.c was created
and updated from the data in the file prog.c. When you wish the data to
come from some other file, you can use the -Input option, which
specifies the input file to use for the data. For example, if you wanted to
update prog.c, but from a filename called newprog.c, then the
command:
would save a new revision of module prog.c, but with the data that was in
the file newprog.c. In this case, the file prog.c does not have
to exist, and isn't referenced even if it did exist. Again, once the update is
complete, you could delete the newprog.c file if desired and then later
you can retrieve its contents.
fhist prog.c -u -i newprog.c
- -Remarks
-
Remarks can be read from a file instead of
from the terminal. The -Remarks option can be used to specify a file
name containing the remarks. If there is no file name following the
-Remarks option, then no remarks at all are used. The command:
would create a new revision of prog.c without asking for or saving any
remarks about the edit.
fhist prog.c -u -r
- -Remark_String text
- It is also possible to specify the remarks directly on the command line. You may only use this option once.
- -Extract [ edit ]
-
To retrieve a previous revision of a module,
you specify the name of the module and use the -Extract option to
specify the edit number you want retrieved. Edit numbers are assigned
sequentially starting with 1. Thus the initial version of the module has edit
number 1, the first revision has edit number 2, and so on until the latest
revision. If the -Extract option is not used, or if no edit number is
supplied for it, then the latest edit number is extracted. Therefore, this is
the default action if no options at all are specified.
Edit numbers can also be zero, negative, or be a name with an optional offset.
The number zero represents the latest edit number, and negative numbers
indicate edit numbers backwards from the latest edit number. Edit names
represent edit numbers whose name had been set by using the -Name
option. For example, if edit number 10 was associated with the name
foo, then the edit name foo represents 10, foo‐4
represents edit number6, and foo+2 represents edit number 12. The
special reserved names oldest and newest refer to the oldest and
newest versions of the module in the edit history.
As an example of retrievals, assume that you have saved ten versions of the
module prog.c. The following commands will then extract the versions of
the file with the specified edit numbers:
- fhist prog.c
- version 10 (the latest)
- fhist prog.c -e 9
- version 9 (the version just prior)
- fhist prog.c -e oldest
- version 1 (the oldest version)
- fhist prog.c -e -2
- version 8 (latest version - 2)
- -Output filename
-
You can change the output filename using the
-Output option. Thus, the command:
will extract the latest version of the module prog.c, and put it into the
file newprog.c. Once again, the file "prog.c" is ignored,
whether or not it existed.
fhist prog.c -o newprog.c
- -Force_Write
-
- -No_Write
-
- -Terminal [ edit ]
-
- -Modify number
When extracting a file, the fhist
program looks for and updates special character sequences in the first few
lines of the file. These special sequences are used for documentation
purposes, such as describing the edit number the file is from. For speed of
extraction and updating, these sequences are usually limited to the first 25
lines of the file, since the fhist program then does not have to
examine the entire file. The -Modify option can be used to change the
number of lines to be modified from the default value of 25. Specifying zero
totally disables the special character sequences, whereas specifying a very
large number will cause the sequences to be checked for each line of the file
(and thus slow the fhist program down).
Each special sequence is of the form [# keyword value, keyword value, ...,
keyword value #] , where each keyword describes an item, and each
value is the value for the preceding keyword. The keywords can be in
upper or lower case, or both. The single space following the [#,
following each comma, and preceding the #] must be present. If the
sequence is wrong, an unknown keyword is used, the line is longer than 200
characters, or more than four keywords are used, then the whole line will not
be changed. The current keywords which can be used are the following:
When an extract is done, the proper edit number and date are automatically
inserted as the new values. Thus, if you extract edit 23 of the module
delete.c which had been created on 8 August 89, then the resulting file
would begin:
When updating a module, it is never necessary to edit these sequences, as any
old values will be removed and replaced with the new ones. Also, when using
the -d or -du options (described below), lines with these
sequences compare as if the values were null, and thus will not cause spurious
differences.
During an update, the special character sequences are read and any edit value
found is compared against the current edit number of the module. If they
differ, then the update fails. This provides an interlock check for the case
of two users extracting the same version of a file, editing it, and then both
updating it without knowledge of each other. In this case, the second user
would fail, and then he can merge his edits with the previous user's edit and
then retry the update. This checking is disabled if there is no special
character sequence containing the edit keyword, the edit number value is null,
or if the -Forced_Update option is used to indicate that the check is
not needed.
- edit
- The edit number
- date
- The date that the edit was created
- user
- The user name of the user who created the edit
- module
- The module name
/* * Delete - program to delete files * [# Edit, Date #] */
/* * Delete - program to delete files * [# Edit 23, Date 8‐Aug‐89 #] */
- -No_Keywords
- This option may be used to disable the use of the keyword special character sequences described above. Text containing keyword sequences is treated as plain text. Note: the -No_Keywords option does not imply the -BINary option.
- -Name string
-
- -List [ edit1 [ edit2 ]]
-
- -Difference [ edit1 [ edit2 ]]
-
This option is used to display the differences
between two versions of a module, or a file and a version of a module. There
are three modes for this action, depending on how many edit numbers are
supplied. These modes are illustrated by the following examples:
- fhist foo.c -d
- Compare latest version against file "foo.c"
- fhist foo.c -d 3
- Compare version 3 against file "foo.c"
- fhist foo.c -d 3 4
- Compare version 3 against version 4
- -Difference_Update
-
This option combines the effects of the
-Difference and -Update options. It displays the differences
between a file and the latest version of a module. If there are any
differences, it then proceeds to perform an update of the module with that
file, asking for remarks as usual. This option is very useful when used with
wildcarded module names. Then you can update just those modules which were
changed by an edit session, and see the changes for each module before typing
the appropriate remark for each module.
You may specify both of the -Difference and -Update options, or
you may use this option. The results are identical.
- -Conditional_Update
-
This option conditionally updates a module.
That is, it will only do an update if there are any differences between a file
and the latest version of a module. This is convenient when related changes
are made to many modules in a directory, and one command using wildcards can
update just those modules that were changed.
The -CReate option may be combined with the -Update or
-Conditional_Update options to create the file if required.
- -CLean
-
- -CHeck
This option is used to find out if a file does
not match the latest version of a module. If so, a message is given. If the
file does match, no output occurs. This option is thus useful to determine
which files have been modified and in need of updating. The -ALL option
is defaulted for this option, since it is usually used for all modules. For
example,
will report on all files which are different than the latest modules. If
-Quick is specified, then the output will consist of the module names
with no other output. This is useful for the backquote operator in shell
scripts for referencing the modules which are out of date. The -CHeck
option will also accept the -Input option.
fhist -CHeck
- -PRune edit
This option is used to permanently remove
early edits from an edit history. This is useful if you wish to cut down on
the amount of disk space taken by an edit history file, or when you want to
start another release of a file, and want a copy of the edit history file for
that new release. The option takes an edit number to preserve, and all edits
in the edit history file before that edit are deleted, and can no longer be
referenced. For example, to keep only the current edit plus the previous 10
edits of the module file, you could use the command:
Since the -PRune option is unrecoverable (unless backup files are
available), the fhist program asks the user to verify that the prune is
really wanted. The -Forced_Update option can be used to bypass this
verification.
fhist file -prune -10
- -ALL
This option can be used with any of the action
options. It means perform the operation for all modules in the module storage
directory. Alternatively, you can specify multiple module names on the command
line, and the actions will be performed with those modules. You cannot specify
both -ALL and module names.
When using multiple modules or the -ALL option, the -Input and
-Output options have a slightly different meaning. In these cases, the
-Input and -Output arguments are a directory name which contains
filenames with the same name as the module names. If the argument is not a
directory, then an error is given. This feature is useful for example, to
extract all the modules and place them into some remote directory, as in:
You should be careful when specifying numeric edit numbers for multiple modules.
Most probably, a particular edit number is not appropriate for multiple
modules, since changes corresponding to a particular edit number are not
usually related. Using named edits avoids these problems. As an example, if
you wanted to extract every module which had an edit that was named
rev3, then you could use the command:
Some other useful examples of commands which use multiple modules are:
fhist -all -e -o tempdir
fhist -all -e rev3
fhist *.c -create fhist -check -all fhist -cu -all
- -Verbose
This option can be specified with any other
action, and outputs status information about the progress of the action. This
is useful for debugging of problems, or just for amusement when the system is
slow or a large file is being processed. It accepts a numeric argument to
indicate the verbosity for output. The levels are as follows:
- 0
- No output at all (except for errors).
- 1
- Single‐line output describing action (default).
- 2
- Detailed status as action proceeds.
- -Help
-
- -VERSion
-
FILE NAME EXPANSION¶
As a convenience, if a pathname begins with a period and a environment variable exists with that name, then the value of the environment variable will be used as the actual pathname. For example, if a environment variable of .FOO has the value this.is.a.long.name, then the commandfhist -o .FOO
fhist -o this.is.a.long.name
fhist -o ./.FOO
BINARY FILES¶
In general, fhist can handle all text files you throw at it, even international text with unusual encodings. However, fhist is unable to cope elegantly with files which contain the NUL character. The fcomp(1) program simply prints a warning, and continues, you need to know that it converts NUL characters into an 0x80 value before performing the comparison. The fmerge(1) program also converts the NUL character to an 0x80 value before merging, after a warning, and any output file will contain this value, rather than the original NUL character. The fhist(1) program, however, generates a fatal error if any input file contains NUL characters. This is intended to protect your source files for unintentional corruption. Use -BINary for files which absolutely must contain NUL characters.EXIT STATUS¶
The fhist program will exit with a status of 1 on any error. The fhist program will only exit with a status of 0 if there are no errors.REFERENCES¶
This program is based on the algorithm inAn O(ND) Difference Algorithm and Its
Variations, Eugene W. Myers, TR 85‐6, 10‐April‐1985,
Department of Computer Science, The University of Arizona, Tuscon, Arizona
85721.
See also:
A File Comparison Program, Webb Miller
and Eugene W. Myers, Software Practice and Experience, Volume 15, No. 11,
November 1985.
COPYRIGHT¶
fhist version 1.18.D001AUTHORS¶
Peter Miller | Web: | http://miller.emu.id.au/pmiller/ |
/\/\* | E‐Mail: | pmiller@opensource.org.au |
David I. Bell | Web: | http://www.canb.auug.org.au/~dbell |
E‐Mail: | dbell@canb.auug.org.au |
FHist | Reference Manual |