Next: , Previous: Date Formats, Up: Commands And Options


Global Options

Here are all the global options to CVS.

--allow-root=REPOSITORY

The alphabetically first global option is one that is virtually never used on the command line. The –allow-root option is used with the pserver command to allow authenticated access to the named repository (which is a repository top level, such as /usr/local/newrepos, not a project subdirectory such as /usr/local/newrepos/myproj).

This global option is virtually never used on the command line. Normally, the only place you'd ever use it is in /etc/inetd.conf files (see Repository Administration), which is also about the only place the pserver command is used.

Every repository to be accessed via cvs pserver on a given host needs a corresponding –allow-root option in /etc/inetd.conf. This is a security device, meant to ensure that people can't use a CVS pserver to gain access to private repositories.

(See The Password-Authenticating Server also the node Password Authentication Server in the Cederqvist manual.)

-a

This authenticates all communications with the server. This option has no effect unless you're connecting via the GSSAPI server (gserver). GSSAPI connections are not covered in this book, because they're still somewhat rarely used (although that may change). (See the nodes Global Options and GSSAPI Authenticated in the Cederqvist manual for more information.)

-b (Obsolete)

This option formerly specified the directory where the RCS binaries could be found. CVS now implements the RCS functions internally, so this option has no effect (it is kept only for backward compatibility).

-d REPOSITORY

This specifies the repository, which might be an absolute pathname or a more complex expression involving a connection method, username and host, and path. If it is an expression specifying a connection method, the general syntax is:

     :METHOD:USER@HOSTNAME:PATH_TO_REPOSITORY

Here are examples using each of the connection methods:

-e EDITOR

Invokes EDITOR for your commit message, if the commit message was not specified on the command line with the -m option. Normally, if you don't give a message with -m, CVS invokes the editor based on the $CVSEDITOR, $VISUAL, or $EDITOR environment variables, which it checks in that order. Failing that, it invokes the popular Unix editor vi.

If you pass both the -e global option and the -m option to commit, the -e is ignored in favor of the commit message given on the command line (that way it's safe to use -e in a .cvsrc file).

-f

This global option suppresses reading of the .cvsrc file.

--help [COMMAND] or -H [COMMAND]

These two options are synonymous. If no COMMAND is specified, a basic usage message is printed to the standard output. If COMMAND is specified, a usage message for that command is printed.

--help-options

Prints out a list of all global options to CVS, with brief explanations.

--help-synonyms

Prints out a list of CVS commands and their short forms ("up" for "update", and so on).

-l

Suppresses logging of this command in the CVSROOT/history file in the repository. The command is still executed normally, but no record of it is made in the history file.

-n

Doesn't change any files in the working copy or in the repository. In other words, the command is executed as a "dry run" – CVS goes through most of the steps of the command but stops short of actually running it.

This is useful when you want to see what the command would have done had you actually run it. One common scenario is when you want to see what files in your working directory have been modified, but not do a full update (which would bring down changes from the repository). By running cvs -n update, you can see a summary of what's been done locally, without changing your working copy.

-q

This tells CVS to be moderately quiet by suppressing the printing of unimportant informational messages. What is considered "important" depends on the command. For example, in updates, the messages that CVS normally prints on entering each subdirectory of the working copy are suppressed, but the one-line status messages for modified or updated files are still printed.

-Q

This tells CVS to be very quiet, by suppressing all output except what is absolutely necessary to complete the command. Commands whose sole purpose is to produce some output (such as diff or annotate), of course, still give that output. However, commands that could have an effect independent of any messages that they may print (such as update or commit) print nothing.

-r

Causes new working files to be created read-only (the same effect as setting the $CVSREAD environment variable).

If you pass this option, checkouts and updates make the files in your working copy read-only (assuming your operating system permits it). Frankly, I'm not sure why one would ever want to use this option.

-s VARIABLE=VALUE

This sets an internal CVS variable named VARIABLE to VALUE.

On the repository side, the CVSROOT/*info trigger files can expand such variables to values that were assigned in the -s option. For example, if CVSROOT/loginfo contains a line like this

     myproj  /usr/local/bin/foo.pl ${=FISH}

and someone runs a commit from a myproj working copy like this

     floss$ cvs -s FISH=carp commit -m "fixed the bait bug"

the foo.pl script is invoked with carp as an argument. Note the funky syntax, though: The dollar sign, equal sign, and curly braces are all necessary – if any of them are missing, the expansion will not take place (at least not as intended). Variable names may contain alphanumerics and underscores only. Although it is not required that they consist entirely of capital letters, most people do seem to follow that convention.

You can use the -s flag as many times as you like in a single command. However, if the trigger script refers to variables that aren't set in a particular invocation of CVS, the command still succeeds, but none of the variables are expanded, and the user sees a warning. For example, if loginfo has this

     myproj  /usr/local/bin/foo.pl  ${=FISH}  ${=BIRD}

but the same command as before is run

     floss$ cvs -s FISH=carp commit -m "fixed the bait bug"

the person running the command sees a warning something like this (placed last in the output)

     loginfo:31: no such user variable ${=BIRD}

and the foo.pl script is invoked with no arguments. But if this command were run

     floss$ cvs -s FISH=carp -s BIRD=vulture commit -m "fixed the bait bug"

there would be no warning, and both ${=FISH} and ${=BIRD} in loginfo would be correctly expanded. In either case, the commit itself would still succeed.

Although these examples all use commit, variable expansion can be done with any CVS command that can be noticed in a CVSROOT/ trigger file – which is why the -s option is global.

(See the section Repository Administrative Files later in this chapter for more details about variable expansion in trigger files.)

-T DIR

Stores any temporary files in DIR instead of wherever CVS normally puts them (specifically, this overrides the value of the $TMPDIR environment variable, if any exists). DIR should be an absolute path.

This option is useful when you don't have write permission (and, therefore, CVS doesn't either) to the usual temporary locations.

-t

Traces the execution of a CVS command. This causes CVS to print messages showing the steps that it's going through to complete a command. You may find it particularly useful in conjunction with the -n global option, to preview the effects of an unfamiliar command before running it for real. It can also be handy when you're trying to discover why a command failed.

-v or --version

Causes CVS to print out its version and copyright information and then exit with no error.

-w

Causes new working files to be created read-write (overrides any setting of the $CVSREAD environment variable). Because files are created read-write by default anyway, this option is rarely used.

If both -r and -w are passed, -w dominates.

-x

Encrypts all communications with the server. This option has no effect unless you're connecting via the GSSAPI server (gserver). GSSAPI connections are not covered in this book, because they're still somewhat rarely used (although that may change). (See the nodes Global Options and GSSAPI Authenticated in the Cederqvist manual for more information.)

-z GZIPLEVEL

Sets the compression level on communications with the server. The argument GZIPLEVEL must be a number from 1 to 9. Level 1 is minimal compression (very fast, but doesn't compress much); Level 9 is highest compression (uses a lot of CPU time, but sure does squeeze the data). Level 9 is only useful on very slow network connections. Most people find levels between 3 and 5 to be most beneficial.

A space between -z and its argument is optional.

Karl Fogel wrote this book. Buy a printed copy via his homepage at red-bean.com

copyright  ©  January 18 2019 sean dreilinger url: https://durak.org/sean/pubs/software/cvsbook/Global-Options.html