add a KEYWORD SUBSTITUTION section; ok jmc@ jfb@ Joris Vink;

1 files changed, 114 insertions, 1 deletions

diff --git a/usr.bin/cvs/cvs.1 b/usr.bin/cvs/cvs.1
index e62160b3563..40a6f2c0316 100644
--- a/usr.bin/cvs/cvs.1
+++ b/usr.bin/cvs/cvs.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: cvs.1,v 1.44 2005/02/06 14:52:06 jmc Exp $
+.\"	$OpenBSD: cvs.1,v 1.45 2005/02/09 16:11:15 xsa Exp $
 .\"
 .\" Copyright (c) 2004 Jean-Francois Brousseau <jfb@openbsd.org>
 .\" Copyright (c) 2004, 2005 Xavier Santolaria <xsa@openbsd.org>
@@ -107,6 +107,119 @@ with 1 being the fastest,
 and 9 providing the best level of compression.
 The default is 6.
 .El
+.Sh KEYWORD SUBSTITUTION
+As long as you edit source files inside a working directory you
+can always find out the state of your files via the
+.Ic status
+or
+.Ic log
+commands, but as soon as files get exported from
+your local working copy, it becomes harder to identify which
+revisions they are.
+.Pp
+.Nm
+can use a mechanism known as
+.Sq keyword substitution
+to help identify the files.
+Embedded strings of the form $keyword$ and $keyword:...$ in a file
+are replaced with strings of the form $keyword: value$ whenever you
+obtain a new revision of the file.
+The possible keywords are as follows:
+.Bl -tag -width "RevisionXXX"
+.It $Author: xsa $
+The name of the user who checked in the revision.
+.It $Date: 2005/02/09 16:11:15 $
+The date and hour (UTC) the revision was checked in.
+.It $Header: /cvs/OpenBSD/src/usr.bin/cvs/cvs.1,v 1.45 2005/02/09 16:11:15 xsa Exp $
+Standard header containing the full pathname of the RCS
+file, the revision number, the date (UTC), the author and the state.
+.It $Id: cvs.1,v 1.45 2005/02/09 16:11:15 xsa Exp $
+The same content as $Header: /cvs/OpenBSD/src/usr.bin/cvs/cvs.1,v 1.45 2005/02/09 16:11:15 xsa Exp $ but without the path
+of the RCS file.
+.It $Log: cvs.1,v $
+.It Revision 1.45  2005/02/09 16:11:15  xsa
+.It add a KEYWORD SUBSTITUTION section; ok jmc@ jfb@ Joris Vink;
+.It
+The log message supplied during commit, preceded by a header
+containing the RCS filename, the revision number, the
+author, and the date (UTC).
+.It $Name:  $
+The tag name used to check out the file.
+.It $RCSfile: cvs.1,v $
+The name of the RCS file, but without a path.
+.It $Revision: 1.45 $
+The revision number assigned to the revision.
+.It $Source: /cvs/OpenBSD/src/usr.bin/cvs/cvs.1,v $
+The full pathname of the RCS file.
+.It $State: Exp $
+The state assigned to the revision.
+.El
+.Pp
+Keyword substitution has its disadvantages: sometimes the
+literal text string $Author: xsa $ is wanted inside a file without
+.Nm
+interpreting it as a keyword and expanding it into something like
+$Author: xsa $.
+The
+.Fl k Ar o
+option can be used to turn off keyword substitution entirely though. 
+There is unfortunately no way to selectively turn off keyword substitution.
+.Pp
+Each file and working directory copy of a file have a stored
+default substitution mode.
+Substitution modes on files are set by the
+.Fl k Ar mode
+option to the
+.Ic add
+and
+.Ic admin
+commands or by the
+.Fl k Ar mode
+or
+.Fl A
+options to the
+.Ic checkout
+or
+.Ic update
+commands.
+.Pp
+The possible substitution modes are as follows:
+.Bl -tag -width Ds -offset 3n
+.It Fl k Ar b
+Like
+.Fl k Ar o ,
+but also avoids the conversion of line endings.
+This option is used to handle binary files.
+.It Fl k Ar k
+Does not substitute the keywords.
+Useful with the
+.Ic diff
+command to avoid displaying the differences between keyword substitutions.
+.It Fl k Ar kv
+The default behaviour.
+Keywords are normally substituted i.e. $Revision: 1.45 $ becomes $Revision: 1.45 $.
+.It Fl k Ar kvl
+Like
+.Fl k Ar kv ,
+except that the locker's name is displayed along with the version
+if the given revision is currently locked.
+This option is normally not useful as
+.Nm
+does not use file locking by default.
+.It Fl k Ar o
+No substitutions are done.
+This option is often used with the
+.Ic import
+command to guarantee that files that already contain external keywords
+do not get modified.
+.It Fl k Ar v
+Substitue the value of keywords instead of keywords themselves
+e.g. instead of $Revision: 1.45 $, only insert 1.1 and not $Revision: 1.45 $.
+This option must be used with care, as it can only be used once.
+It is often used with the
+.Ic export
+command to freeze the values before releasing software.
+.El
 .Sh COMMANDS
 The following commands are supported by
 .Nm :