Annotation of src/usr.bin/cvs/cvs.1, Revision 1.26
1.26 ! xsa 1: .\" $OpenBSD: cvs.1,v 1.25 2005/01/14 17:02:56 xsa Exp $
1.1 jfb 2: .\"
3: .\" Copyright (c) 2004 Jean-Francois Brousseau <jfb@openbsd.org>
4: .\" All rights reserved.
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\"
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. The name of the author may not be used to endorse or promote products
13: .\" derived from this software without specific prior written permission.
14: .\"
15: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
16: .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
17: .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
18: .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
19: .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
20: .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
21: .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
22: .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
23: .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
24: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25: .\"
26: .Dd May 16, 2004
27: .Dt CVS 1
28: .Os
29: .Sh NAME
30: .Nm cvs
1.3 jfb 31: .Nd OpenCVS Concurrent Versioning System client
1.1 jfb 32: .Sh SYNOPSIS
33: .Nm
1.15 jmc 34: .Op Fl flQqtv
1.1 jfb 35: .Op Fl d Ar root
36: .Op Fl e Ar editor
1.20 jmc 37: .Xo
38: .Oo Fl s
39: .Ar var Ns = Ns Ar val Oc
40: .Xc
1.15 jmc 41: .Op Fl z Ar level
1.1 jfb 42: .Ar command Op Ar ...
43: .Sh DESCRIPTION
44: The
45: .Nm
46: program acts as both client and server for the use of and administration of
47: a CVS source repository.
48: CVS is used to maintain version information on files that are kept in a
49: repository.
50: Although it is more commonly used to track changes in source code, there
51: are no real limitations to the type of files that you can store in a
52: repository.
53: .Pp
1.7 jfb 54: Unless the
55: .Fl f
56: option is specified,
57: .Nm
58: reads its startup configuration file
59: .Pa .cvsrc
60: from the home directory of the user who invoked it.
61: This file is used to specify implicit options passed to
62: .Nm
63: or one of its commands whenever it is invoked.
1.16 jmc 64: See
65: .Xr cvsrc 5
66: for further information.
1.7 jfb 67: .Pp
1.1 jfb 68: The following options are supported:
1.15 jmc 69: .Bl -tag -width "-e editorXX"
1.1 jfb 70: .It Fl d Ar root
71: Use
72: .Ar root
73: as the path to the root directory of the CVS repository.
74: The value must specify an absolute path.
75: .It Fl e Ar editor
76: Use the program
77: .Ar editor
78: whenever editing log information.
1.8 jmc 79: This option overrides the environment variables CVSEDITOR, VISUAL, and EDITOR.
1.1 jfb 80: .It Fl f
1.7 jfb 81: Do not read the user's configuration file on startup.
1.1 jfb 82: .It Fl l
83: Suppress logging of history information.
84: .It Fl Q
85: Be extra quiet.
86: Only error messages will be displayed.
87: .It Fl q
88: Be quiet about reporting.
1.20 jmc 89: .It Fl s Ar var Ns = Ns Ar val
90: Set the value of the internal variable
91: .Ar var
92: to the string
93: .Ar val .
1.15 jmc 94: .It Fl t
95: Trace program execution.
1.1 jfb 96: .It Fl v
97: Display version information and exit.
1.15 jmc 98: .It Fl z Ar level
99: Specify the compression level to
100: .Xr gzip 1
101: when transferring files.
102: The compression level ranges from 1 to 9,
103: with 1 being the fastest,
104: and 9 providing the best level of compression.
105: The default is 6.
1.1 jfb 106: .El
107: .Sh COMMANDS
1.3 jfb 108: The following commands are supported by
109: .Nm .
1.7 jfb 110: .Bl -tag -width "xxxxxxxxxxxx"
1.11 jmc 111: .It Xo Ic add Op Fl m Ar msg
1.1 jfb 112: .Ar file Op ...
1.3 jfb 113: .Xc
1.7 jfb 114: .Pp
1.1 jfb 115: Before a file is known to CVS, it must be added to the repository using
116: this command.
117: Adding a file does not actually publish the contents of the
1.7 jfb 118: file, so you must
1.11 jmc 119: .Ic commit
1.7 jfb 120: the first revision in order to let other users see the file with the
1.11 jmc 121: .Ic update
1.4 jfb 122: or
1.11 jmc 123: .Ic checkout
1.4 jfb 124: commands.
1.1 jfb 125: .Pp
1.7 jfb 126: Although adding a file does not involve a log message, it is possible to
127: specify one to include with the action, using the
128: .Fl m
129: option.
1.13 jmc 130: .Pp
131: Aliases:
132: .Ic ad ,
133: .Ic new .
134: .It Ic admin
135: Administration front-end for
136: .Xr rcs 1 .
137: .Pp
138: Aliases:
139: .Ic adm ,
140: .Ic rcs .
1.26 ! xsa 141: .It Xo Ic annotate
! 142: .Op Fl flR
! 143: .Oo Fl D Ar date \*(Ba
! 144: .Fl r Ar rev Oc
! 145: .Op Ar file ...
! 146: .Xc
! 147: .Pp
1.23 xsa 148: For each line of any files specified, show information about its
149: last revision.
150: The information given is the last revision when a modification occurred,
151: the author's name, and the date of the revision.
1.26 ! xsa 152: .Pp
! 153: The
! 154: .Fl f
! 155: flag is used to force the use of the head revision if the specified
! 156: tag or date is not found.
! 157: This can be used in combination with
! 158: .Fl D
! 159: or
! 160: .Fl r
! 161: to ensure that there is some output from the
! 162: .Ic annotate
! 163: command, even if only to show Revision 1.1 of the file.
! 164: The
! 165: .Fl l
! 166: flag is used to limit the scope of the search to the local directory
! 167: only and to disable recursive behaviour, which can be requested with the
! 168: .Fl R
! 169: flag.
! 170: The
! 171: .Fl D
! 172: flag shows the annotations as of the latest revision no later than
! 173: .Ar date .
! 174: The
! 175: .Fl r
! 176: flag shows annotations as of revision
! 177: .Ar rev
! 178: (can be a revision number or a tag).
1.13 jmc 179: .Pp
180: Aliases:
181: .Ic ann .
1.11 jmc 182: .It Xo Ic checkout
1.7 jfb 183: .Op Fl c
184: .Op Ar module ...
185: .Xc
186: .Pp
187: The
1.11 jmc 188: .Ic checkout
1.7 jfb 189: command is used to create a local copy of one or more modules present on the
190: target CVS repository.
1.13 jmc 191: .Pp
192: Aliases:
193: .Ic co ,
194: .Ic get .
1.11 jmc 195: .It Xo Ic commit
1.3 jfb 196: .Op Fl flnR
1.8 jmc 197: .Op Fl F Ar logfile
1.1 jfb 198: .Op Fl m Ar msg
1.3 jfb 199: .Op Fl r Ar rev
1.4 jfb 200: .Op Ar file ...
1.3 jfb 201: .Xc
1.7 jfb 202: .Pp
1.1 jfb 203: The
1.11 jmc 204: .Ic commit
1.1 jfb 205: command is used to send local changes back to the server and update the
206: repository's information to reflect the changes.
1.13 jmc 207: .Pp
208: Aliases:
209: .Ic ci ,
210: .Ic com .
1.24 jfb 211: .It Xo Ic diff Op Fl cilNpu
1.3 jfb 212: .Op Fl D Ar date
213: .Op Fl r Ar rev
1.4 jfb 214: .Op Ar file ...
1.3 jfb 215: .Xc
1.7 jfb 216: .Pp
1.3 jfb 217: The
1.11 jmc 218: .Ic diff
1.3 jfb 219: command is very similar to the
220: .Xr diff 1
1.5 jfb 221: program, except that the differential comparisons that it generates are
1.3 jfb 222: between local or remote revisions of files stored in the CVS repository.
1.13 jmc 223: .Pp
224: Aliases:
225: .Ic di ,
226: .Ic dif .
227: .It Ic edit
228: Get ready to edit a watched file.
229: .It Ic editors
230: See who is editing a watched file.
231: .It Ic export
232: Export sources from CVS;
233: similar to
234: .Ic checkout .
235: .Pp
236: Aliases:
237: .Ic ex ,
238: .Ic exp .
239: .It Ic history
240: Show repository access history.
241: .Pp
242: Aliases:
243: .Ic hi ,
244: .Ic his .
1.22 jmc 245: .It Xo Ic import
246: .Op Fl b Ar branch
247: .Op Fl m Ar msg
248: .Ar repository
249: .Ar vendortag
250: .Ar releasetag
251: .Xc
252: .Pp
1.13 jmc 253: Import sources into CVS using vendor branches.
1.22 jmc 254: .Pp
255: The
256: .Fl b
257: flag specifies the first-level branch number.
258: The
259: .Fl m
260: flag specifies the log message to send.
261: .Pp
262: At least three arguments are required:
263: .Ar repository
264: specifies the location of the sources to be imported;
265: .Ar vendortag
266: is a tag for the entire branch;
267: .Ar releasetag
268: is used to identify the files you created with
269: .Nm
270: .Ic import .
1.13 jmc 271: .Pp
272: Aliases:
273: .Ic im ,
274: .Ic imp .
275: .It Ic init
276: Create a CVS repository if it doesn't exist.
277: .It Ic kserver
278: Start a Kerberos authentication server.
279: .It Ic log
280: Print out history information for files.
281: .Pp
282: Aliases:
283: .Ic lo .
284: .It Ic login
285: Prompt for password for authenticating server.
286: .It Ic logout
287: Remove entry in .cvspass for remote repository.
288: .It Ic rdiff
289: Create
290: .Xr patch 1
291: format diffs between releases.
292: .It Ic release
293: Indicate that a module is no longer in use.
1.18 xsa 294: .It Xo Ic remove
295: .Op Fl flR
296: .Op Ar file ...
297: .Xc
298: The
299: .Ic remove
300: command is used to inform
301: .Nm
302: that
303: .Ar file
304: is scheduled to be removed from the repository.
305: Files are not actually removed from the repository until the
306: .Ic commit
307: command has been run subsequently.
308: .Pp
309: Aliases:
1.19 xsa 310: .Ic rm ,
311: .Ic delete .
1.13 jmc 312: .It Ic rlog
313: Print out history information for a module.
314: .It Ic rtag
315: Add a symbolic link to a module.
316: .It Ic server
317: Server mode.
1.25 xsa 318: .It Xo Ic status
319: .Op Fl lRv
320: .Op Ar file ...
321: .Xc
322: The
323: .Ic status
324: command is used to display the state of checked out files.
325: .Pp
326: The
327: .Fl l
328: flag is used to limit the scope of the search to the local directory
329: only and to disable recursive behaviour, which can be requested with the
330: .Fl R
331: flag.
332: The
333: .Fl v
334: flag causes the symbolic tags for the file to be displayed.
335: .Pp
336: The following are the different possible states:
337: .Bl -tag -width "Unresolved ConflictXX"
338: .It Cm Locally Added
339: The file has been added with the
340: .Ic add
341: command, but has not been committed to the repository with the
342: .Ic commit
343: command.
344: .It Cm Locally Modified
345: The file is up to date, but has been locally modified since then.
346: .It Cm Locally Removed
347: The file has been removed with the
348: .Ic remove
349: command, but has not been committed to the repository with the
350: .Ic commit
351: command.
352: .It Cm Needs Checkout
353: The file has not been modified; a new version is available.
354: .It Cm Needs Merge
355: The file has been modified and a newer version is available.
356: A merge is necessary.
357: .It Cm Needs Patch
358: Same as
359: .Ic Needs Checkout
360: but, in client-server mode, only the differences are sent to save
361: network resources.
362: .It Cm Unresolved Conflict
363: A merge has been done, but unresolved conflicts still remain.
364: .It Cm Up-to-date
365: The file is up to date.
366: .El
1.13 jmc 367: .Pp
368: Aliases:
369: .Ic st ,
370: .Ic stat .
1.21 jmc 371: .It Xo Ic tag
372: .Op Fl bdl
373: .Op Fl r Ar old_tag
374: .Op Ar symbolic_tag
375: .Op Ar file ...
376: .Xc
377: .Pp
378: Add a symbolic tag to a checked out version of
379: .Ar file .
380: .Pp
381: The
382: .Fl b
383: flag is used to specify a branch tag.
384: If the
385: .Fl d
386: flag is specified the tag will be deleted.
387: The
388: .Fl l
389: flag is used to specify a local change only and disables the recursive
390: behaviour.
391: If the
392: .Fl r
393: flag is used,
394: .Nm
395: will only tag the files with
396: .Ar symbolic_tag
397: if they are already tagged with
398: .Ar old_tag .
399: When done, it will remove the old tag
400: leaving only the new tag behind on exactly the same files.
1.13 jmc 401: .Pp
402: Aliases:
403: .Ic ta ,
404: .Ic freeze .
405: .It Ic unedit
406: Undo an
407: .Ic edit
408: command.
1.11 jmc 409: .It Xo Ic update
1.3 jfb 410: .Op Fl ACdP
1.4 jfb 411: .Op Ar file ...
1.3 jfb 412: .Xc
1.7 jfb 413: .Pp
1.3 jfb 414: The
1.11 jmc 415: .Ic update
1.17 david 416: command is used to merge any of the changes that have occurred on the remote
1.3 jfb 417: repository into the local one where the command was run.
418: .Pp
419: The
420: .Fl A
1.8 jmc 421: flag resets any sticky tags, dates, or kopts that have been set on the tree.
1.3 jfb 422: The
423: .Fl l
424: flag is used to specify a local change only and disables the recursive
425: behaviour.
426: The
427: .Fl P
428: flag causes
429: .Nm
430: to prune any directories that have become empty as a result of the update.
1.13 jmc 431: .Pp
432: Aliases:
433: .Ic up ,
434: .Ic upd .
1.11 jmc 435: .It Ic version
1.3 jfb 436: Causes
437: .Nm
438: to print its version information.
1.14 jfb 439: If this command is issued within a local copy of a remote repository or
440: if either the
441: .Ev CVSROOT
442: environment variable or the
443: .Fl d
444: flag specify a remote repository,
1.3 jfb 445: .Nm
446: will also connect to the server and ask it to print its version information.
1.13 jmc 447: .Pp
448: Aliases:
449: .Ic ve ,
450: .Ic ver .
451: .It Ic watch
452: Set watches.
453: .It Ic watchers
454: See who is watching a file.
1.1 jfb 455: .El
456: .Sh ENVIRONMENT
457: .Bl -tag -width CVS_CLIENT_LOG
1.8 jmc 458: .It Ev CVS_CLIENT_LOG
459: This variable enables logging of all communications between the client and
460: server when running in non-local mode.
461: If set, this environment variable must contain a base path from which two
462: paths will be generated by appending ".in" to the value for the server's
463: input and ".out" for the server's output.
1.1 jfb 464: .It Ev CVS_RSH
465: Name of the program to use when connecting to the server through a remote
466: shell.
467: The default is to use the
468: .Xr ssh 1
469: program.
470: .It Ev CVS_SERVER
471: If set, gives the name of the program to invoke as a
472: .Nm
473: server when using remote shell.
474: The default is to use `cvs'.
475: .It Ev CVSEDITOR
476: Name of the editor to use when editing commit messages.
1.8 jmc 477: Checked before
478: .Ev EDITOR
479: and
480: .Ev VISUAL .
481: .It Ev CVSROOT
482: When set, this variable should contain the string pointing to the root
483: directory of the CVS repository.
484: The contents of this variable are ignored when the
485: .Fl d
486: option is given or if `Root' files exist in the checked-out copy.
1.1 jfb 487: .It Ev EDITOR
1.9 jmc 488: Name of the editor to use when editing commit messages.
489: This is traditionally a line-oriented editor,
490: such as
491: .Xr ex 1 .
1.1 jfb 492: .It Ev VISUAL
1.9 jmc 493: Name of the editor to use when editing commit messages.
494: This is traditionally a screen-oriented editor,
495: such as
496: .Xr vi 1 .
1.8 jmc 497: .El
498: .Sh FILES
499: .Bl -tag -width Ds
500: .It Pa $HOME/.cvsrc
501: File containing a list of implicit options to pass to certain commands.
502: This file is read on startup unless the
503: .Fl f
504: option is specified.
505: .It Pa $CVSROOT/CVSROOT
506: Directory containing repository administrative files.
507: .It Pa $CVSROOT/CVSROOT/loginfo
508: File containing associations between modules and handlers for
509: post-commit logging.
1.1 jfb 510: .El
511: .Sh SEE ALSO
512: .Xr diff 1 ,
1.15 jmc 513: .Xr gzip 1 ,
1.1 jfb 514: .Xr patch 1 ,
1.8 jmc 515: .Xr rcs 1 ,
1.16 jmc 516: .Xr cvsrc 5 ,
1.1 jfb 517: .Xr cvsd 8
1.8 jmc 518: .Sh HISTORY
519: The OpenCVS project is a BSD-licensed rewrite of the original
520: Concurrent Versioning System written by Jean-Francois Brousseau.
521: The original CVS code was written in large parts by Dick Grune,
522: Brian Berliner and Jeff Polk.
523: .Sh AUTHORS
524: .An Jean-Francois Brousseau
525: .An Vincent Labrecque
526: .An Joris Vink
1.2 jfb 527: .Sh CAVEATS
528: This CVS implementation does not fully conform to the GNU CVS version.
1.3 jfb 529: In some cases, this was done explicitly because GNU CVS has inconsistencies
1.2 jfb 530: or ambiguous behaviour.
1.3 jfb 531: Some things have also been left out or modified to enhance the overall
532: security of the system.
533: .Pp
534: Among other things, support for the pserver connection mechanism has been
535: dropped because of security issues with the authentication mechanism.