- Copy stable/10 (r259064) to releng/10.0 as part of the

[FreeBSD/releng/10.0.git] / gnu / usr.bin / rcs / NEWS

Recent changes to RCS (and possible future changes)

 $FreeBSD$

        Copyright 1991, 1992, 1993, 1994, 1995 Paul Eggert
        Distributed under license by the Free Software Foundation, Inc.

        This file is part of RCS.

        RCS 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, or (at your
        option) any later version.

        RCS 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 RCS; see the file COPYING.
        If not, write to the Free Software Foundation,
        59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

        Report problems and direct all questions to:

                rcs-bugs@cs.purdue.edu


Here is a brief summary of user-visible changes since 5.6.

  New options:
    `-kb' supports binary files.
    `-T' preserves the modification time of RCS files.
    `-V' prints the version number.
    `-zLT' causes RCS to use local time in working files and logs.
    `rcsclean -n' outputs what rcsclean would do, without actually doing it.
    `rlog -N' omits symbolic names.
  There is a new keyword `Name'.
  Inserted log lines now have the same prefix as the preceding `$Log' line.

Most changes for RCS version 5.7 are to fix bugs and improve portability.
RCS now conforms to GNU configuration standards and to Posix 1003.1b-1993.


Features new to RCS version 5.7, and possibly incompatible
in minor ways with previous practice, include:

  Inserted log lines now have the same prefix as the preceding `$Log' line.
  E.g. if a $Log line starts with `// $Log', log lines are prefixed with `// '.
  RCS still records the (now obsolescent) comment leader inside RCS files,
  but it ignores the comment leader unless it is emulating older RCS versions.
  If you plan to access a file with both old and new versions of RCS,
  make sure its comment leader matches its `$Log' line prefix.
  For backwards compatibility with older versions of RCS,
  if the log prefix is `/*' or `(*' surrounded by optional white space,
  inserted log lines contain ` *' instead of `/*' or `(*';
  however, this usage is obsolescent and should not be relied on.

  $Log string `Revision' times now use the same format as other times.

  Log lines are now inserted even if -kk is specified; this simplifies merging.

  ci's -rR option (with a nonempty R) now just specifies a revision number R.
  In some beta versions, it also reestablished the default behavior of
  releasing a lock and removing the working file.
  Now, only the bare -r option does this.

  With an empty extension, any appearance of a directory named `RCS'
  in a pathname identifies the pathname as being that of an RCS file.
  For example, `a/RCS/b/c' is now an RCS file with an empty extension.
  Formerly, `RCS' had to be the last directory in the pathname.

  rlog's -d option by default now uses exclusive time ranges.
  E.g. `rlog -d"<T"' now excludes revisions whose times equal T exactly.
  Use `rlog -d"<=T"' to get the old behavior.

  merge now takes up to three -L options, one for each input file.
  Formerly, it took at most two -L options, for the 1st and 3rd input files.

  `rcs' now requires at least one option; this is for future expansion.

Other features new to RCS version 5.7 include:

  merge and rcsmerge now pass -A, -E, and -e options to the subsidiary diff3.

  rcs -kb acts like rcs -ko, except it uses binary I/O on working files.
  This makes no difference under Posix or Unix, but it does matter elsewhere.
  With -kb in effect, rcsmerge refuses to merge;
  this avoids common problems with CVS merging.

  The following is for future use by GNU Emacs 19's version control package:

    rcs's new -M option causes it to not send mail when you break somebody
    else's lock.  This is not meant for casual use; see rcs(1).

    ci's new -i option causes an error if the RCS file already exists.
    Similarly, -j causes an error if the RCS file does not already exist.

  The new keyword `Name' is supported; its value is the name, if any,
  used to check out the revision.  E.g. `co -rN foo' causes foo's
  $Name...$ keyword strings to end in `: N $'.

  The new -zZONE option causes RCS to output dates and times using ISO 8601
  format with ZONE as the time zone, and to use ZONE as the default time
  zone for input.  Its most common use is the -zLT option, which causes RCS
  to use local time externally.  You can also specify foreign time zones;
  e.g. -z+05:30 causes RCS to use India time (5 hours 30 minutes east of UTC).
  This option does not affect RCS files themselves, which always use UTC;
  it affects only output (e.g. rlog output, keyword expansion, diff -c times)
  and interpretation of options (e.g. the -d option of ci, co, and rlog).
  Bare -z restores the default behavior of UTC with no time zone indication,
  and the traditional RCS date separator `/' instead of the ISO 8601 `-'.
  RCSINIT may contain a -z option.  ci -k parses UTC offsets.

  The new -T option of ci, co, rcs, and rcsclean preserves the modification
  time of the RCS file unless a revision is added or removed.
  ci -T sets the RCS file's modification time to the new revision's time
  if the former precedes the latter and there is a new revision;
  otherwise, it preserves the RCS file's modification time.
  Use this option with care, as it can confuse `make'; see ci(1).

  The new -N option of rlog omits symbolic names from the output.

  A revision number that starts with `.' is considered to be relative to
  the default branch (normally the trunk).  A branch number followed by `.'
  stands for the last revision on that branch.

  If someone else already holds the lock, rcs -l now asks whether you want
  to break it, instead of immediately reporting an error.

  ci now always unlocks a revision like 3.5 if you check in a revision
  like 3.5.2.1 that is the first of a new branch of that revision.
  Formerly it was inconsistent.

  File names may now contain tab, newline, space, and '$'.
  They are represented in keyword strings with \t, \n, \040, and \044.
  \ in a file name is now represented by \\ in a keyword string.

  Identifiers may now start with a digit and (unless they are symbolic names)
  may contain `.'.  This permits author names like `john.doe' and `4tran'.

  A bare -V option now prints the current version number.

  rcsdiff outputs more readable context diff headers if diff -L works.

  rcsdiff -rN -rN now suppresses needless checkout and comparison
  of identical revisions.

  Error messages now contain the names of files to which they apply.

  Mach style memory mapping is now supported.

  The installation procedure now conforms to the GNU coding standards.

  When properly configured, RCS now strictly conforms to Posix 1003.1b-1993.


Features new to RCS version 5.6 include:

  Security holes have been plugged; setgid use is no longer supported.

  co can retrieve old revisions much more efficiently.
  To generate the Nth youngest revision on the trunk,
  the old method used up to N passes through copies of the working file;
  the new method uses a piece table to generate the working file in one pass.

  When ci finds no changes in the working file,
  it automatically reverts to the previous revision unless -f is given.

  RCS follows symbolic links to RCS files instead of breaking them,
  and warns when it breaks hard links to RCS files.

  `$' stands for the revision number taken from working file keyword strings.
  E.g. if F contains an Id keyword string,
  `rcsdiff -r$ F' compares F to its checked-in revision, and
  `rcs -nL:$ F' gives the symbolic name L to F's revision.

  co and ci's new -M option sets the modification time
  of the working file to be that of the revision.
  Without -M, ci now tries to avoid changing the working file's
  modification time if its contents are unchanged.

  rcs's new -m option changes the log message of an old revision.

  RCS is portable to hosts that do not permit `,' in filenames.
  (`,' is not part of the Posix portable filename character set.)
  A new -x option specifies extensions other than `,v' for RCS files.
  The Unix default is `-x,v/', so that the working file `w' corresponds
  to the first file in the list `RCS/w,v', `w,v', `RCS/w' that works.
  The non-Unix default is `-x', so that only `RCS/w' is tried.
  Eventually, the Unix default should change to `-x/,v'
  to encourage interoperability among all Posix hosts.

  A new RCSINIT environment variable specifies defaults for options like -x.

  The separator for revision ranges has been changed from `-' to `:', because
  the range `A-B' is ambiguous if `A', `B' and `A-B' are all symbolic names.
  E.g. the old `rlog -r1.5-1.7' is now `rlog -r1.5:1.7'; ditto for `rcs -o'.
  For a while RCS will still support (but warn about) the old `-' separator.

  RCS manipulates its lock files using a method that is more reliable under NFS.


Features new to RCS version 5 include:

  RCS can check in arbitrary files, not just text files, if diff -a works.
  RCS can merge lines containing just a single `.' if diff3 -m works.
  GNU diff supports the -a and -m options.

  RCS can now be used as a setuid program.
  See ci(1) for how users can employ setuid copies of ci, co, and rcsclean.
  Setuid privileges yield extra security if the effective user owns RCS files
  and directories, and if only the effective user can write RCS directories.
  RCS uses the real user for all accesses other than writing RCS directories.
  As described in ci(1), there are three levels of setuid support.

    1.  Setuid works fully if the seteuid() system call lets any
    process switch back and forth between real and effective users,
    as specified in Posix 1003.1a Draft 5.

    2.  On hosts with saved setuids (a Posix 1003.1-1990 option) and without
    a modern seteuid(), setuid works unless the real or effective user is root.

    3.  On hosts that lack both modern seteuid() and saved setuids,
    setuid does not work, and RCS uses the effective user for all accesses;
    formerly it was inconsistent.

  New options to co, rcsdiff, and rcsmerge give more flexibility to keyword
  substitution.

    -kkv substitutes the default `$Keyword: value $' for keyword strings.
    However, a locker's name is inserted only as a file is being locked,
    i.e. by `ci -l' and `co -l'.  This is normally the default.

    -kkvl acts like -kkv, except that a locker's name is always inserted
    if the given revision is currently locked.  This was the default in
    version 4.  It is now the default only with when using rcsdiff to
    compare a revision to a working file whose mode is that of a file
    checked out for changes.

    -kk substitutes just `$Keyword$', which helps to ignore keyword values
    when comparing revisions.

    -ko retrieves the old revision's keyword string, thus bypassing keyword
    substitution.

    -kv retrieves just `value'.  This can ease the use of keyword values, but
    it is dangerous because it causes RCS to lose track of where the keywords
    are, so for safety the owner write permission of the working file is
    turned off when -kv is used; to edit the file later, check it out again
    without -kv.

  rcs -ko sets the default keyword substitution to be in the style of co -ko,
  and similarly for the other -k options.  This can be useful with file
  formats that cannot tolerate changing the lengths of keyword strings.
  However it also renders a RCS file readable only by RCS version 5 or later.
  Use rcs -kkv to restore the usual default substitution.

  RCS can now be used by development groups that span time zone boundaries.
  All times are now displayed in UTC, and UTC is the default time zone.
  To use local time with co -d, append ` LT' to the time.
  When interchanging RCS files with sites running older versions of RCS,
  time stamp discrepancies may prevent checkins; to work around this,
  use `ci -d' with a time slightly in the future.

  Dates are now displayed using four-digit years, not two-digit years.
  Years given in -d options must now have four digits.
  This change is required for RCS to continue to work after 1999/12/31.
  The form of dates in version 5 RCS files will not change until 2000/01/01,
  so in the meantime RCS files can still be interchanged with sites
  running older versions of RCS.  To make room for the longer dates,
  rlog now outputs `lines: +A -D' instead of `lines added/del: A/D'.

  To help prevent diff programs that are broken or have run out of memory
  from trashing an RCS file, ci now checks diff output more carefully.

  ci -k now handles the Log keyword, so that checking in a file
  with -k does not normally alter the file's contents.

  RCS no longer outputs white space at the ends of lines
  unless the original working file had it.
  For consistency with other keywords,
  a space, not a tab, is now output after `$Log:'.
  Rlog now puts lockers and symbolic names on separate lines in the output
  to avoid generating lines that are too long.
  A similar fix has been made to lists in the RCS files themselves.

  RCS no longer outputs the string `Locker: ' when expanding Header or Id
  keywords.  This saves space and reverts back to version 3 behavior.

  The default branch is not put into the RCS file unless it is nonempty.
  Therefore, files generated by RCS version 5 can be read by RCS version 3
  unless they use the default branch feature introduced in version 4.
  This fixes a compatibility problem introduced by version 4.

  RCS can now emulate older versions of RCS; see `co -V'.
  This may be useful to overcome compatibility problems
  due to the above changes.

  Programs like Emacs can now interact with RCS commands via a pipe:
  the new -I option causes ci, co, and rcs to run interactively,
  even if standard input is not a terminal.
  These commands now accept multiple inputs from stdin separated by `.' lines.

  ci now silently ignores the -t option if the RCS file already exists.
  This simplifies some shell scripts and improves security in setuid sites.

  Descriptive text may be given directly in an argument of the form -t-string.

  The character set for symbolic names has been upgraded
  from Ascii to ISO 8859.

  rcsdiff now passes through all options used by GNU diff;
  this is a longer list than 4.3BSD diff.

  merge's new -L option gives tags for merge's overlap report lines.
  This ability used to be present in a different, undocumented form;
  the new form is chosen for compatibility with GNU diff3's -L option.

  rcsmerge and merge now have a -q option, just like their siblings do.

  rcsclean's new -n option outputs what rcsclean would do,
  without actually doing it.

  RCS now attempts to ignore parts of an RCS file that look like they come
  from a future version of RCS.

  When properly configured, RCS now strictly conforms with Posix 1003.1-1990.
  RCS can still be compiled in non-Posix traditional Unix environments,
  and can use common BSD and USG extensions to Posix.
  RCS is a conforming Standard C program, and also compiles under traditional C.

  Arbitrary limits on internal table sizes have been removed.
  The only limit now is the amount of memory available via malloc().

  File temporaries, lock files, signals, and system call return codes
  are now handled more cleanly, portably, and quickly.
  Some race conditions have been removed.

  A new compile-time option RCSPREFIX lets administrators avoid absolute path
  names for subsidiary programs, trading speed for flexibility.

  The configuration procedure is now more automatic.

  Snooping has been removed.


Version 4 was the first version distributed by FSF.
Beside bug fixes, features new to RCS version 4 include:

  The notion of default branch has been added; see rcs -b.


Version 3 was included in the 4.3BSD distribution.


Here are some possible future changes for RCS:

  Bring back sccstorcs.

  Add an option to `rcsmerge' so that it can use an arbitrary program
  to do the 3-way merge, instead of the default `merge'.
  Likewise for `rcsdiff' and `diff'.  It should be possible to pass
  arbitrary options to these programs, and to the subsidiary `co's.

  Add format options for finer control over the output of ident and rlog.
  E.g. there should be an easy way for rlog to output lines like
  `src/main.c 2.4 wft', one for each locked revision.
  rlog options should have three orthogonal types: selecting files,
  selecting revisions, and selecting rlog format.

  Add format options for finer control over the output of keyword strings.
  E.g. there should be some way to prepend @(#), and there should be some
  way to change $ to some other character to disable further substitution.
  These options should make the resulting files uneditable, like -kv.

  Add long options, e.g. `--version'.  Unfortunately RCS's option syntax
  is incompatible with getopt.  Perhaps the best way is to overload `rcs', e.g.
  `rcs diff --keyword-substitution=old file' instead of `rcsdiff -ko file'.

  Add a way to put only the interesting part of the path into the $Header
  keyword expansion.

  rlog -rM:N should work even if M and N have different numbers of fields,
  so long as M is an ancestor of N or vice versa.

  rcs should evaluate options in order; this allows rcs -oS -nS.

  rcs should be able to fix minor mistakes in checkin dates and authors.

  Be able to redo your most recent checkin with minor changes.

  co -u shouldn't complain about a writable working file if it won't change
  its contents.

  Configure the Makefile automatically, as well as conf.h.

  Add a new option to rcs that behaves like -o, but that doesn't lose the
  nonempty log messages, but instead merges them with the next revision
  if it exists, perhaps with a 1-line header containing author, date, etc.

  Add a `-' option to take the list of pathnames from standard input.
  Perhaps the pathnames should be null-terminated, not newline-terminated,
  so that pathnames that contain newlines are handled properly.

  Permit multiple option-pathname pairs, e.g. co -r1.4 a -r1.5 b.

  Add options to allow arbitrary combinations of working file names
  with RCS file names -- they shouldn't have to match.

  Add an option to break a symbolic link to an RCS file,
  instead of breaking the hard link that it points to.

  Add ways to specify the earliest revision, the most recent revision,
  the earliest or latest revision on a particular branch, and
  the parent or child of some other revision.

  If a user has multiple locks, perhaps ci should fall back on ci -k's
  method to figure out which revision to use.

  Symbolic names need not refer to existing branches and revisions.
  rcs(1)'s BUGS section says this is a bug.  Is it?  If so, it should be fixed.

  Add an option to rcs -o so that old log messages are not deleted if
  the next undeleted revision exists, but are merely appended to the log
  message of that revision.

  ci -k should be able to get keyword values from the first `$Log' entry.

  Add an option to rcsclean to clean directories recursively.

  Write an rcsck program that repairs corrupted RCS files,
  much as fsck repairs corrupted file systems.
  For example, it should remove stale lock files.

  Clean up the source code with a consistent indenting style.

  Update the date parser to use the more modern getdate.y by Bellovin,
  Salz, and Berets, or the even more modern getdate by Moraes.  None of
  these getdate implementations are as robust as RCS's old warhorse in
  avoiding problems like arithmetic overflow, so they'll have to be
  fixed first.

  Break up the code into a library so that it's easier to write new programs
  that manipulate RCS files, and so that useless code is removed from the
  existing programs.  For example, the rcs command contains unnecessary
  keyword substitution baggage, and the merge command can be greatly pruned.

  Make it easier to use your favorite text editor to edit log messages,
  etc. instead of having to type them in irretrievably at the terminal.

  Let the user specify a search path for default branches,
  e.g. to use L as the default branch if it works, and M otherwise.
  Let the user require that at least one entry in the default branch path works.
  Let the user say that later entries in the default branch path are read only,
  i.e. one cannot check in changes to them.
  This should be an option settable by RCSINIT.

  Add a way for a user to see which revisions affected which lines.

  Have `rlog -nN F' print just the revision number that N translates to.
  E.g. `rlog -nB. F' would print the highest revision on the branch B.
  Use this to add an option -bB to rcsbranch, to freeze the named branch.
  This should interact well with default branches.

  Add a co option that prints the revision number before each line,
  as SCCS's `get -m' does.

The following projects require a change to RCS file format.

  Allow keyword expansion to be changed on a per-revision basis,
  not on a per-file basis as now.  This would allow -ko to be used
  on imported revisions, with the default -kkv otherwise.

  When two or more branches are merged, record all the ancestors
  of the new revision.  The hard part of this is keeping track of all
  the ancestors of a working file while it's checked out.

  Add loose locking, which is like non-strict but applies to all users,
  not just the owner of the RCS file.

  Be able to store RCS files in compressed format.
  Don't bother to use a .Z extension that would exceed file name length limits;
  just look at the magic number.

  Add locker commentary, e.g. `co -l -m"checkout to fix merge bug" foo'
  to tell others why you checked out `foo'.
  Also record the time when the revision was locked,
  and perhaps the working pathname (if applicable).

  Let the user mark an RCS revision as deleted; checking out such a revision
  would result in no working file.  Similarly, using `co -d' with a date either
  before the initial revision or after the file was marked deleted should
  remove the working file.  For extra credit, extend the notion of `deleted' to
  include `renamed'.  RCS should support arbitrary combinations of renaming and
  deletion, e.g. renaming A to B and B to A, checking in new revisions to both
  files, and then renaming them back.

  Be able to check in an entire directory structure into a single RCS file.

  Use a better scheme for locking revisions; the current scheme requires
  changing the RCS file just to lock or unlock a revision.
  The new scheme should coexist as well as possible with older versions of RCS,
  and should avoid the rare NFS bugs mentioned in rcsedit.c.
  E.g. if there's a reliable lockd running, RCS should use it
  instead of relying on NFS.

  Add rcs options for changing keyword names, e.g. XConsortium instead of Id.

  Add a `$Description' keyword; but this may be tricky, since descriptions can
  contain newlines and $s.

  Add a `$Copyright' keyword that expands to a copyright notice.

  Add frozen branches a la SCCS.  In general, be able to emulate all of
  SCCS, so that an SCCS-to-RCS program can be practical.  For example,
  there should be an equivalent to the SCCS prt command.

  Add support for distributed RCS, where widely separated
  users cannot easily access each others' RCS files,
  and must periodically distribute and reconcile new revisions.

  Be able to create empty branches.

  Be able to store just deltas from a read-only principal copy,
  e.g. from source on CD-ROM.

  Improve RCS's method for storing binary files.
  Although it is more efficient than SCCS's,
  the diff algorithm is still line oriented,
  and often generates long output for minor changes to an executable file.

  From the user's point of view, it would be best if
  RCS detected and handled binary files without human intervention,
  switching expansion methods as needed from revision to revision.

  Allow RCS to determine automagically whether -ko or -kb should be the default
  by inspecting the file's contents or name.  The magic should be optional
  and user-programmable.

  Extend the grammar of RCS files so that keywords need not be in a fixed order.

  Internationalize messages; unfortunately, there's no common standard yet.
  This requires a change in RCS file format because of the
  `empty log message' and `checked in with -k' hacks inside RCS files.

  Add documentation in texinfo format.