Annotation of src/usr.bin/cvs/cvs.1, Revision 1.30
1.30 ! xsa 1: .\" $OpenBSD: cvs.1,v 1.29 2005/01/19 18:10:08 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.27 xsa 197: .Oo Fl F Ar logfile \*(Ba
198: .Fl m Ar msg Oc
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.27 xsa 207: .Pp
208: The
209: .Fl l
210: flag is used to limit the scope of the search to the local directory only.
211: Sometimes one might want to force a file to be committed, even though
212: it is unchanged: this can be done using the
213: .Fl f
214: flag, which also has the effect of disabling recursive behaviour,
215: which can be requested with the
216: .Fl R
217: flag.
218: When using the
219: .Fl n
220: flag, programs listed in the CVSROOT/modules file do not get executed.
221: The
222: .Fl m
223: flag can be used to specify a log message on the command line which
224: suppresses the editor invocation, or use the
225: .Fl F
226: flag to specify a
227: .Ar file
228: as argument which contains the log message.
229: The
230: .Fl r
231: flag can be used to commit to a particular symbolic or numerical revision.
1.13 jmc 232: .Pp
233: Aliases:
234: .Ic ci ,
235: .Ic com .
1.24 jfb 236: .It Xo Ic diff Op Fl cilNpu
1.3 jfb 237: .Op Fl D Ar date
238: .Op Fl r Ar rev
1.4 jfb 239: .Op Ar file ...
1.3 jfb 240: .Xc
1.7 jfb 241: .Pp
1.3 jfb 242: The
1.11 jmc 243: .Ic diff
1.3 jfb 244: command is very similar to the
245: .Xr diff 1
1.5 jfb 246: program, except that the differential comparisons that it generates are
1.3 jfb 247: between local or remote revisions of files stored in the CVS repository.
1.13 jmc 248: .Pp
249: Aliases:
250: .Ic di ,
251: .Ic dif .
1.30 ! xsa 252: .It Xo Ic edit Op Fl lR
! 253: .Op Fl a Ar action
! 254: .Op Ar file ...
! 255: .Xc
! 256: .Pp
! 257: The
! 258: .Ic edit
! 259: command is used to make a file that is being watched (read-only)
! 260: readable and writable and to inform others that you are planning to edit it.
! 261: Notifications terminate when the
! 262: .Ic commit
! 263: command is issued.
! 264: Editing rights on the file can be given up using the
! 265: .Ic unedit
! 266: command.
! 267: This command terminates the temporary notifications.
! 268: .Pp
! 269: The
! 270: .Fl l
! 271: flag is used to limit the scope of the search to the local directory
! 272: only and to disable recursive behaviour, which can be requested with the
! 273: .Fl R
! 274: flag.
! 275: The
! 276: .Fl a
! 277: flag specifies the temporary notification wanted:
! 278: .Bl -tag -width "commitXX"
! 279: .It Cm commit
! 280: Another user has committed changes to the
! 281: .Ar file .
! 282: .It Cm edit
! 283: Another user has issued the
! 284: .Ic edit
! 285: command on the
! 286: .Ar file .
! 287: .It Cm unedit
! 288: Another user has issued the
! 289: .Ic unedit
! 290: command on the
! 291: .Ar file .
! 292: .It Cm all
! 293: All of the above.
! 294: .It Cm none
! 295: None of the above.
! 296: .El
! 297: .Pp
! 298: The
! 299: .Fl a
! 300: flag may appear more than once, or not at all.
! 301: If omitted, the action defaults to
! 302: .Ic Cm all .
1.13 jmc 303: .It Ic editors
304: See who is editing a watched file.
305: .It Ic export
306: Export sources from CVS;
307: similar to
308: .Ic checkout .
309: .Pp
310: Aliases:
311: .Ic ex ,
312: .Ic exp .
313: .It Ic history
314: Show repository access history.
315: .Pp
316: Aliases:
317: .Ic hi ,
318: .Ic his .
1.22 jmc 319: .It Xo Ic import
320: .Op Fl b Ar branch
321: .Op Fl m Ar msg
322: .Ar repository
323: .Ar vendortag
324: .Ar releasetag
325: .Xc
326: .Pp
1.13 jmc 327: Import sources into CVS using vendor branches.
1.22 jmc 328: .Pp
329: The
330: .Fl b
331: flag specifies the first-level branch number.
332: The
333: .Fl m
334: flag specifies the log message to send.
335: .Pp
336: At least three arguments are required:
337: .Ar repository
338: specifies the location of the sources to be imported;
339: .Ar vendortag
340: is a tag for the entire branch;
341: .Ar releasetag
342: is used to identify the files you created with
343: .Nm
344: .Ic import .
1.13 jmc 345: .Pp
346: Aliases:
347: .Ic im ,
348: .Ic imp .
349: .It Ic init
350: Create a CVS repository if it doesn't exist.
351: .It Ic kserver
352: Start a Kerberos authentication server.
353: .It Ic log
354: Print out history information for files.
355: .Pp
356: Aliases:
357: .Ic lo .
358: .It Ic login
359: Prompt for password for authenticating server.
360: .It Ic logout
361: Remove entry in .cvspass for remote repository.
362: .It Ic rdiff
363: Create
364: .Xr patch 1
365: format diffs between releases.
366: .It Ic release
367: Indicate that a module is no longer in use.
1.18 xsa 368: .It Xo Ic remove
369: .Op Fl flR
370: .Op Ar file ...
371: .Xc
372: The
373: .Ic remove
374: command is used to inform
375: .Nm
376: that
377: .Ar file
378: is scheduled to be removed from the repository.
379: Files are not actually removed from the repository until the
380: .Ic commit
381: command has been run subsequently.
1.28 xsa 382: .Pp
383: The
384: .Fl f
385: flag locally removes the file.
386: If this flag is not used, the file must be locally removed beforehand for
387: the command to be valid.
388: The
389: .Fl l
390: flag is used to limit the scope of the search to the local directory
391: only and to disable recursive behaviour, which can be requested with the
392: .Fl R
393: flag.
1.18 xsa 394: .Pp
395: Aliases:
1.19 xsa 396: .Ic rm ,
397: .Ic delete .
1.13 jmc 398: .It Ic rlog
399: Print out history information for a module.
400: .It Ic rtag
401: Add a symbolic link to a module.
402: .It Ic server
403: Server mode.
1.25 xsa 404: .It Xo Ic status
405: .Op Fl lRv
406: .Op Ar file ...
407: .Xc
408: The
409: .Ic status
410: command is used to display the state of checked out files.
411: .Pp
412: The
413: .Fl l
414: flag is used to limit the scope of the search to the local directory
415: only and to disable recursive behaviour, which can be requested with the
416: .Fl R
417: flag.
418: The
419: .Fl v
420: flag causes the symbolic tags for the file to be displayed.
421: .Pp
422: The following are the different possible states:
423: .Bl -tag -width "Unresolved ConflictXX"
424: .It Cm Locally Added
425: The file has been added with the
426: .Ic add
427: command, but has not been committed to the repository with the
428: .Ic commit
429: command.
430: .It Cm Locally Modified
431: The file is up to date, but has been locally modified since then.
432: .It Cm Locally Removed
433: The file has been removed with the
434: .Ic remove
435: command, but has not been committed to the repository with the
436: .Ic commit
437: command.
438: .It Cm Needs Checkout
439: The file has not been modified; a new version is available.
440: .It Cm Needs Merge
441: The file has been modified and a newer version is available.
442: A merge is necessary.
443: .It Cm Needs Patch
444: Same as
445: .Ic Needs Checkout
446: but, in client-server mode, only the differences are sent to save
447: network resources.
448: .It Cm Unresolved Conflict
449: A merge has been done, but unresolved conflicts still remain.
450: .It Cm Up-to-date
451: The file is up to date.
452: .El
1.13 jmc 453: .Pp
454: Aliases:
455: .Ic st ,
456: .Ic stat .
1.21 jmc 457: .It Xo Ic tag
458: .Op Fl bdl
459: .Op Fl r Ar old_tag
460: .Op Ar symbolic_tag
461: .Op Ar file ...
462: .Xc
463: .Pp
464: Add a symbolic tag to a checked out version of
465: .Ar file .
466: .Pp
467: The
468: .Fl b
469: flag is used to specify a branch tag.
470: If the
471: .Fl d
472: flag is specified the tag will be deleted.
473: The
474: .Fl l
475: flag is used to specify a local change only and disables the recursive
476: behaviour.
477: If the
478: .Fl r
479: flag is used,
480: .Nm
481: will only tag the files with
482: .Ar symbolic_tag
483: if they are already tagged with
484: .Ar old_tag .
485: When done, it will remove the old tag
486: leaving only the new tag behind on exactly the same files.
1.13 jmc 487: .Pp
488: Aliases:
489: .Ic ta ,
490: .Ic freeze .
1.30 ! xsa 491: .It Xo Ic unedit Op Fl lR
! 492: .Op Ar file ...
! 493: .Xc
! 494: .Pp
! 495: The
! 496: .Ic unedit
! 497: command is used to give up an edition on a file and thus cancel
! 498: the wanted temporary notifications.
! 499: If the file has been modified since the
1.13 jmc 500: .Ic edit
1.30 ! xsa 501: command has been issued,
! 502: .Nm
! 503: will ask if you want to go back to the previous version, and lose the
! 504: modifications done on the file, or stay in edition mode on it.
! 505: .Pp
! 506: The
! 507: .Fl l
! 508: flag is used to limit the scope of the search to the local directory
! 509: only and to disable recursive behaviour, which can be requested with the
! 510: .Fl R
! 511: flag.
1.11 jmc 512: .It Xo Ic update
1.3 jfb 513: .Op Fl ACdP
1.4 jfb 514: .Op Ar file ...
1.3 jfb 515: .Xc
1.7 jfb 516: .Pp
1.3 jfb 517: The
1.11 jmc 518: .Ic update
1.17 david 519: command is used to merge any of the changes that have occurred on the remote
1.3 jfb 520: repository into the local one where the command was run.
521: .Pp
522: The
523: .Fl A
1.8 jmc 524: flag resets any sticky tags, dates, or kopts that have been set on the tree.
1.3 jfb 525: The
526: .Fl l
527: flag is used to specify a local change only and disables the recursive
528: behaviour.
529: The
530: .Fl P
531: flag causes
532: .Nm
533: to prune any directories that have become empty as a result of the update.
1.29 xsa 534: .Pp
535: For each file updated, a single letter prefix is given to
536: specify the state of the file.
537: The possible prefixes are as follows:
538: .Bl -tag -width "XXX"
539: .It \&?
540: The file is unknown to
541: .Nm .
542: .It A
543: The file has been added with the
544: .Ic add
545: command, but has not been committed to the repository with the
546: .Ic commit
547: command.
548: .It C
549: A merge, with a more recent version of the file, has been done,
550: but unresolved conflicts still remain.
551: .It M
552: The file has been locally modified; if a more recent version
553: is available, the merge has been done without conflict.
554: .It P
555: The same as
556: .Sq U ,
557: but, in client-server mode, only differences are sent to save network
558: resources.
559: .It R
560: The file has been removed with the
561: .Ic remove
562: command, but has not been committed to the repository with the
563: .Ic commit
564: command.
565: .It U
566: The file is up to date.
567: .El
1.13 jmc 568: .Pp
569: Aliases:
570: .Ic up ,
571: .Ic upd .
1.11 jmc 572: .It Ic version
1.3 jfb 573: Causes
574: .Nm
575: to print its version information.
1.14 jfb 576: If this command is issued within a local copy of a remote repository or
577: if either the
578: .Ev CVSROOT
579: environment variable or the
580: .Fl d
581: flag specify a remote repository,
1.3 jfb 582: .Nm
583: will also connect to the server and ask it to print its version information.
1.13 jmc 584: .Pp
585: Aliases:
586: .Ic ve ,
587: .Ic ver .
588: .It Ic watch
589: Set watches.
590: .It Ic watchers
591: See who is watching a file.
1.1 jfb 592: .El
593: .Sh ENVIRONMENT
594: .Bl -tag -width CVS_CLIENT_LOG
1.8 jmc 595: .It Ev CVS_CLIENT_LOG
596: This variable enables logging of all communications between the client and
597: server when running in non-local mode.
598: If set, this environment variable must contain a base path from which two
599: paths will be generated by appending ".in" to the value for the server's
600: input and ".out" for the server's output.
1.1 jfb 601: .It Ev CVS_RSH
602: Name of the program to use when connecting to the server through a remote
603: shell.
604: The default is to use the
605: .Xr ssh 1
606: program.
607: .It Ev CVS_SERVER
608: If set, gives the name of the program to invoke as a
609: .Nm
610: server when using remote shell.
611: The default is to use `cvs'.
612: .It Ev CVSEDITOR
613: Name of the editor to use when editing commit messages.
1.8 jmc 614: Checked before
615: .Ev EDITOR
616: and
617: .Ev VISUAL .
618: .It Ev CVSROOT
619: When set, this variable should contain the string pointing to the root
620: directory of the CVS repository.
621: The contents of this variable are ignored when the
622: .Fl d
623: option is given or if `Root' files exist in the checked-out copy.
1.1 jfb 624: .It Ev EDITOR
1.9 jmc 625: Name of the editor to use when editing commit messages.
626: This is traditionally a line-oriented editor,
627: such as
628: .Xr ex 1 .
1.1 jfb 629: .It Ev VISUAL
1.9 jmc 630: Name of the editor to use when editing commit messages.
631: This is traditionally a screen-oriented editor,
632: such as
633: .Xr vi 1 .
1.8 jmc 634: .El
635: .Sh FILES
636: .Bl -tag -width Ds
637: .It Pa $HOME/.cvsrc
638: File containing a list of implicit options to pass to certain commands.
639: This file is read on startup unless the
640: .Fl f
641: option is specified.
642: .It Pa $CVSROOT/CVSROOT
643: Directory containing repository administrative files.
644: .It Pa $CVSROOT/CVSROOT/loginfo
645: File containing associations between modules and handlers for
646: post-commit logging.
1.1 jfb 647: .El
648: .Sh SEE ALSO
649: .Xr diff 1 ,
1.15 jmc 650: .Xr gzip 1 ,
1.1 jfb 651: .Xr patch 1 ,
1.8 jmc 652: .Xr rcs 1 ,
1.16 jmc 653: .Xr cvsrc 5 ,
1.1 jfb 654: .Xr cvsd 8
1.8 jmc 655: .Sh HISTORY
656: The OpenCVS project is a BSD-licensed rewrite of the original
657: Concurrent Versioning System written by Jean-Francois Brousseau.
658: The original CVS code was written in large parts by Dick Grune,
659: Brian Berliner and Jeff Polk.
660: .Sh AUTHORS
661: .An Jean-Francois Brousseau
662: .An Vincent Labrecque
663: .An Joris Vink
1.2 jfb 664: .Sh CAVEATS
665: This CVS implementation does not fully conform to the GNU CVS version.
1.3 jfb 666: In some cases, this was done explicitly because GNU CVS has inconsistencies
1.2 jfb 667: or ambiguous behaviour.
1.3 jfb 668: Some things have also been left out or modified to enhance the overall
669: security of the system.
670: .Pp
671: Among other things, support for the pserver connection mechanism has been
672: dropped because of security issues with the authentication mechanism.