Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
fhist(1)		    General Commands Manual		      fhist(1)

       fhist - file history

       fhist filename...  option...

       fhist -Help

       fhist -VERSion

       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 abil-
       ity are:

       1.  You can make	a series of tentative edits to the file, and if	neces-
	   sary	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	imple-

       5.  The	date  the  file	was last edited	can be automatically stored in
	   the file.

       The fhist program manipulates modules.  A module	 is  simply  any  text
       file  that  you	are interested in keeping versions of.	For example, a
       source file doit.c  is  a  module,  and	so  is	a  documentation  file
       howto.doc.   The	module name includes the suffix	of the file (as	in the
       above examples).	 However, pathnames are	not part of a module name,  so
       that  /usr/dbell/bar.c cannot be	a legal	module name.  A	module name is
       limited to 12 characters	since the fhist	program	needs two extra	 char-
       acters for its own purpose.

   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.

       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  di-
	       rectory	anywhere  you choose.  This is useful if you choose to
	       have a common storage directory for all of your files, indepen-
	       dent 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	infor-
	       mation, though, each module is stored as	two files in  the  di-
	       rectory.	  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	 revi-
	       sions  of  the  module.	 Thus if the edit history is ever cor-
	       rupted, you will	at least have the most recent version  of  the

	       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 nec-

       -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,  -Condi-
	       tional_Update and -Extract options.  Failure to do so will pro-
	       duce inconsistent results.  Note: this is  different  behaviour
	       to the fcomp(1) option of the same name.	 Note: the -BINary op-
	       tion does not imply the -No-Keywords option.

	       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:
		      fhist prog.c -create
	       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 (de-
	       scribed below).	After the remarks have been  typed,  the  con-
	       tents 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

	       The -CReate option may be combined with the -Update or  -Condi-
	       tional_Update options to	create the file	if required.

	       To save another revision	of the module, you use the -Update op-
	       tion.  This updates the files in	the storage directory  to  in-
	       clude  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:
		      fhist prog.c -u
	       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 dis-
	       ables  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 -Condi-
	       tional_Update options to	create the file	if required.

       -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  up-
	       dated 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 exam-
	       ple, if you wanted to update prog.c, but	from a filename	called
	       newprog.c, then the command:
		      fhist prog.c -u -i newprog.c
	       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 ex-
	       ist.  Again, once the update is complete, you could delete  the
	       newprog.c  file	if desired and then later you can retrieve its

	       Remarks can be read from	a file instead of from	the  terminal.
	       The -Remarks option can be used to specify a file name contain-
	       ing the remarks.	 If there is no	file name following  the  -Re-
	       marks option, then no remarks at	all are	used.  The command:
		      fhist prog.c -u -r
	       would  create  a	 new  revision of prog.c without asking	for or
	       saving any remarks about	the edit.

       -Remark_String text
	       It is also possible to specify the remarks directly on the com-
	       mand 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 se-
	       quentially 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  de-
	       fault 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 exam-
	       ple, 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

	       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)

	       The  output filename is again defaulted to the module name.  So
	       when the	module prog.c is extracted, the	specified  version  of
	       the module is written to	the prog.c file.

	       In order	to prevent accidental overwriting of a file, the fhist
	       program will by default ask you if overwriting is permitted  if
	       that would occur.  A common mistake is to edit prog.c, and then
	       try to update the module, but forget to specify the -u  option.
	       Then  the fhist program would try to extract the	newest version
	       of the module,  and  thus  overwrite  the  file	with  the  new
	       changes.	  Asking  the  question	allows you to notice your mis-
	       take, and prevent the overwriting.

       -Output filename
	       You can change the output filename using	 the  -Output  option.
	       Thus, the command:
		      fhist prog.c -o newprog.c
	       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.

	       This option will	force overwriting of the file, thus never ask-
	       ing you if overwriting is permitted.  This is often  useful  in
	       shell  scripts, or when you are sure that you want to overwrite
	       any existing file.

	       This option is the no-overwrite option, and will	cause any  ex-
	       isting  files  to not be	overwritten, again without asking you.
	       This is useful if you already have some of the modules in  your
	       directory,  and	you  want  to  extract the rest	of the modules
	       without overwriting the ones you	already	have.  Specifying both
	       -Fore_Write and -No_Write is an error.

       -Terminal [ edit	]
	       This  option is used to output an extracted module to the stan-
	       dard output, instead of writing it to a file.  This  is	useful
	       in  order to view the beginning of a version of the file.  This
	       can be interrupted if you do not	want to	see the	whole file.

       -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  sin-
	       gle 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

	       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

	       In order	to use this special character sequence,	you simply in-
	       sert  it	into your module inside	of a comment (within the first
	       few lines).  When this is done, the value parts of the sequence
	       can  be	null.	For  example, if you want to put a special se-
	       quence into a program called delete.c, then you could edit  the
	       first few lines as follows:
		       * Delete	- program to delete files
		       * [# Edit, Date #]
	       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 Au-
	       gust 89,	then the resulting file	would begin:
		       * Delete	- program to delete files
		       * [# Edit 23, Date 8-Aug-89 #]

	       When updating a module, it is never necessary to	edit these se-
	       quences,	 as  any  old values will be removed and replaced with
	       the new ones.  Also, when using the  -d	or  -du	 options  (de-
	       scribed	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 num-
	       ber of the module.  If they  differ,  then  the	update	fails.
	       This  provides an interlock check for the case of two users ex-
	       tracting	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.

	       This  option may	be used	to disable the use of the keyword spe-
	       cial character sequences	described above.  Text containing key-
	       word  sequences	is  treated as plain text.  Note: the -No_Key-
	       words option does not imply the -BINary option.

       -Name string
	       This option is used to associate	a name for the newest  version
	       of  a module.  It can be	given along with the -CReate, -Update,
	       or -Difference_Update options, to specify a name	 for  the  new
	       version of the module.  It can also be given by itself in order
	       to specify a name for the newest	version	 of  a	module.	  Each
	       edit  number  can  have	many names associated with it, so this
	       will not	remove any previously defined name for the edit.  This
	       option is useful	to correlate many modules together.  For exam-
	       ple, when a new version of a program is ready to	 be  released,
	       you  could  give	 each  module of the program the same name re-
	       lease1.	Then in	the future, you	can recreate the sources  mak-
	       ing  up	that release by	extracting the edits with the name re-
	       lease1 for every	module.	 Edit names cannot begin with a	digit,
	       and  cannot  contain  plus or minus signs.  These rules prevent
	       ambiguous parsing of edit numbers for the -Extract,  -Terminal,
	       -ALL, and -List options.

       -List [ edit1 [ edit2 ]]
	       This  option  prints a list of edits for	the module, giving the
	       user name, date,	user remarks, and names	specified for the  ed-
	       its.  If	no edit	number is supplied, then all edits are printed
	       in reverse order.  If a single edit number  is  supplied,  then
	       only that edit number is	printed.  If two edit numbers are sup-
	       plied, then all edits in	the specified range are	printed.   The
	       output  from this option	defaults to the	terminal.  You can use
	       the -Output option to save the results to a file.

       -Difference [ edit1 [ edit2 ]]
	       This option is used to display the differences between two ver-
	       sions  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 fol-
	       lowing 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

	       This option accepts the -Input option to	specify	the file to be
	       compared.   When	 using	the -Difference	option,	the output de-
	       faults to the terminal.	Therefore, you must use	-Output	if you
	       wish  the differences saved to a	file.  Using -Quick with -Dif-
	       ference will only output	a quick	summary	of  the	 changes,  in-
	       stead  of the detailed changes.	This summary only supplies the
	       number of lines inserted, deleted, and  unchanged  between  the
	       files.	Using  -What with -Difference will display all of both
	       files, showing in detail	what the differences are using	change

	       The  -Difference	 option	may need to write one or two temporary
	       files in	order to extract old versions of a module to  be  com-
	       pared.  These files have	names like T$n_nnn .  They are deleted
	       again just before differences are output, so that stopping  the
	       output before it	is complete will not leave these files around.
	       The temporary files are usually written to the  current	direc-
	       tory.  If this is not reasonable	because	of permission or quota
	       problems, then you can specify the directory  for  writing  the
	       temporary  files	into.  This is done by defining	the TMPDIR en-
	       vironment variable to be	the path of the	directory.

	       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.

	       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  -Condi-
	       tional_Update options to	create the file	if required.

	       This option is used to remove files which match the newest ver-
	       sions of	modules.  If a file exists which  matches  the	newest
	       version	of a module, then the file is deleted, otherwise it is
	       kept.  This option is used to clean up a	work  directory	 after
	       building	a new version of a product.  This option is especially
	       useful when used	with the -ALL option.  It will also accept the
	       -Input option to	specify	a directory containing the files to be

	       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 up-
	       dating.	The -ALL option	is defaulted for this option, since it
	       is usually used for all modules.	 For example,
		      fhist -CHeck
	       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 ac-
	       cept the	-Input option.

       -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:
		      fhist file -prune	-10
	       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.

	       This  option  can  be  used with	any of the action options.  It
	       means perform the operation for all modules in the module stor-
	       age  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

	       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:
		      fhist -all -e -o tempdir

	       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 correspond-
	       ing 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:
		      fhist -all -e rev3

	       Some other useful examples of commands which use	multiple  mod-
	       ules are:
		      fhist *.c	-create
		      fhist -check -all
		      fhist -cu	-all

	       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  ac-
	       cepts  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.

Reference Manual		     FHist			      fhist(1)


Want to link to this manual page? Use this URL:

home | help