admin

Synopsis: admin [OPTIONS] [FILES]

• Alternate names – adm, rcs
• Requires – Working copy, repository
• Changes – Repository

This command is an interface to various administrative tasks – specifically, tasks applicable to individual RCS files in the repository, such as changing a file's keyword substitution mode or changing a log message after it's been committed.

Although admin behaves recursively if no files are given as arguments, you normally will want to name files explicitly. It's very rare for a single admin command to be meaningful when applied to all files in a project, or even in a directory. Accordingly, when the following explanations refer to the "file", they mean the file or (rarely) files passed as arguments to the admin command.

If there is a system group named cvsadmin on the repository machine, only members of that group can run admin (with the exception of the cvs admin -k command, which is always permitted). Thus you can disallow admin for all users by setting the group to have no users.

Options:

• -AOLDFILE – (Obsolete) Appends the RCS access list of OLDFILE to the access list of the file that is the argument to admin. CVS ignores RCS access lists, so this option is useless.
• -a USER1 [,USER2...] – (Obsolete) Appends the users in the comma-separated list to the access list of the file. Like -A, this option is useless in CVS.
• -bREV – Sets the revision of the file's default branch (usually the trunk) to REV. You won't normally need this option, because you can usually get the revisions you need via sticky tags, but you may use it to revert to a vendor's version if you're using vendor branches. There should be no space between the -b and its argument.
• -cCOMMENT_PREFIX – (Obsolete) Sets the comment leader of the file to COMMENT_PREFIX. The comment leader is not used by CVS or even by recent versions of RCS; therefore, this option is useless and is included only for backward-compatibility.
• -eUSER1[,USER2...] – (Obsolete) Removes the usernames appearing in the comma-separated list from the access list of the RCS file. Like -a and -A, this option is now useless in CVS.
• -i or -I – These two are so obsolete I'm not even going to tell you what they used to do. (See the Cederqvist manual if you're curious.)
• -kMODE – Sets the file's default keyword substitution mode to MODE. This option behaves like the -k option to add, only it gives you a way to change a file's mode after it's been added. (See the section Keyword Substitution (RCS Keywords) later in this chapter for valid modes.) There should be no space between -k and its argument.
• -L – Sets locking to strict. (See -l below.)
• -l[REV] – Locks the file's revision to REV. If REV is omitted, it locks the latest revision on the default branch (usually the trunk). If REV is a branch, it locks the latest revision on that branch.

  The intent of this option is to give you a way to do reserved checkouts, where only one user can be editing the file at a time. I'm not sure how useful this really is, but if you want to try it, you should probably do so in conjunction with the rcslock.pl script in the CVS source distribution's contrib/ directory. See comments in that file for further information. Among other things, those comments indicate that the locking must be set to strict. (See -L.) There is no space between -l and its argument.

• -mREV:MESSAGE – Changes the log message for revision REV to MESSAGE. Very handy – along with -k, this is probably the most frequently used admin option. There are no spaces between option and arguments or around the colon between the two arguments. Of course, MESSAGE may contain spaces within itself (in which case, remember to surround it with quotes so the shell knows it's all one thing).
• -NNAME[:[REV]] – Just like -n, except it forces the override of any existing assignment of the symbolic name NAME, instead of exiting with error.
• -nNAME[:[REV]] – This is a generic interface to assigning, renaming, and deleting tags. There is no reason, as far as I can see, to prefer it to the tag command and the various options available there (-d, -r, -b, -f, and so on). I recommend using the tag command instead. The NAME and optional REV can be combined in the following ways:
  • If only the NAME argument is given, the symbolic name (tag) named NAME is deleted.
  • If NAME: is given but no REV, NAME is assigned to the latest revision on the default branch (usually the trunk).
  • If NAME:REV is given, NAME is assigned to that revision. REV can be a symbolic name itself, in which case it is translated to a revision number first (can be a branch number).
  • If REV is a branch number and is followed by a period (.), NAME is attached to the highest revision on that branch. If REV is just $, NAME is attached to revision numbers found in keyword strings in the working files.

    In all cases where a NAME is assigned, CVS exits with an error if there is already a tag named NAME in the file (but see -N). There are no spaces between -n and its arguments.

• -oRANGE – Deletes the revisions specified by RANGE (also known as "outdating", hence the -o). Range can be specified in one of the following ways:
  • REV1::REV2 – Collapses all intermediate revisions between REV1 and REV2, so that the revision history goes directly from REV1 to REV2. After this, any revisions between the two no longer exist, and there will be a noncontiguous jump in the revision number sequence.
  • ::REV – Collapses all revisions between the beginning of REV's branch (which may be the beginning of the trunk) and REV, noninclusively of course. REV is then the first revision on that line.
  • REV:: – Collapses all revisions between REV and the end of its branch (which may be the trunk). REV is then the last revision on that line.
  • REV – Deletes the revision REV (-o1.8 would be equivalent to -o1.7::1.9).
  • REV1:REV2 – Deletes the revisions from REV1 to REV2, inclusive. They must be on the same branch. After this, you cannot retrieve REV1, REV2, or any of the revisions in between.
  • :REV – Deletes revisions from the beginning of the branch (or trunk) to REV, inclusive. (See the preceding warning.)
  • REV: – Deletes revisions from REV to the end of its branch (or trunk), inclusive. (See the preceding warning.)

    None of the revisions being deleted may have branches or locks. If any of the revisions have symbolic names attached, you have to delete them first with tag -d or admin -n. (Actually, right now CVS only protects against deleting symbolically named revisions if you're using one of the :: syntaxes, but the single-colon syntaxes may soon change to this behavior as well.)

    Instead of using this option to undo a bad commit, you should commit a new revision that undoes the bad change. There are no spaces between -o and its arguments.

• -q – Tells CVS to run quietly – don't print diagnostic messages (just like the global -q option).
• -sSTATE[:REV] – Sets the state attribute of revision REV to STATE. If REV is omitted, the latest revision on the default branch (usually the trunk) is used. If REV is a branch tag or number, the latest revision on that branch is used.

  Any string of letters or numbers is acceptable for STATE; some commonly used states are Exp for experimental, Stab for stable, and Rel for released. (In fact, CVS sets the state to Exp when a file is created.) Note that CVS uses the state dead for its own purposes, so don't specify that one.

  States are displayed in cvs log output, and in the $Log and $State RCS keywords in files. There is no space between -s and its arguments.

• -t[DESCFILE] – Replaces the description (creation message) for the file with the contents of DESCFILE, or reads from standard input if no DESCFILE is specified.

  This useful option, unfortunately, does not currently work in client/server CVS. In addition, if you try it in client/server and omit DESCFILE, any existing description for the file is wiped out and replaced with the empty string. If you need to rewrite a file's description, either do so using only local CVS on the same machine as the repository or -t-STRING (see below). There is no space between -t and its argument. DESCFILE may not begin with a hyphen (-).

• -t-STRING – Like -t, except that STRING is taken directly as the new description. STRING may contain spaces, in which case you should surround it with quotes. Unlike the other syntax for -t, this works in client/server as well as locally.
• -U – Sets locking to nonstrict. (See -l and -L options, discussed earlier.)
• -u[REV] – Unlocks revision REV. (See -l.) If REV is omitted, CVS unlocks the latest lock held by the caller. If REV is a branch, CVS unlocks the latest revision on that branch. If someone other than the owner of a lock breaks the lock, a mail message is sent to the original locker. The content for this message is solicited on standard input from the person breaking the lock. There is no space between -u and its argument.
• -VRCS_VERSION_NUMBER – (Obsolete) This used to be a way to tell CVS to produce RCS files acceptable to previous versions of RCS. Now the RCS format used by CVS is drifting away from the RCS format used by RCS, so this option is useless. Specifying it results in an error.
• -xSUFFIX – (Obsolete) Theoretically, this gives you a way to specify the suffix for RCS file names. However, CVS and related tools all depend on that suffix being the default (,v), so this option does nothing.