Annotation of src/usr.bin/cvs/cvs.5, Revision 1.9
1.9 ! jmc 1: .\" $OpenBSD: cvs.5,v 1.8 2010/09/19 21:30:04 jmc Exp $
1.1 jmc 2: .\"
3: .\" Copyright (c) 2004 Jean-Francois Brousseau <jfb@openbsd.org>
1.5 xsa 4: .\" Copyright (c) 2004-2008 Xavier Santolaria <xsa@openbsd.org>
1.1 jmc 5: .\" All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\"
11: .\" 1. Redistributions of source code must retain the above copyright
12: .\" notice, this list of conditions and the following disclaimer.
13: .\" 2. The name of the author may not be used to endorse or promote products
14: .\" derived from this software without specific prior written permission.
15: .\"
16: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
17: .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
18: .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
19: .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20: .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21: .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22: .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23: .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24: .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
25: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26: .\"
1.9 ! jmc 27: .Dd $Mdocdate: September 19 2010 $
1.1 jmc 28: .Dt CVS 5
29: .Os
30: .Sh NAME
31: .Nm cvs
32: .Nd OpenCVS files format
33: .Sh DESCRIPTION
34: This manual page documents the various support files for
35: .Xr cvs 1
36: and the format of those files.
37: .Pp
38: The location of a module's files are known as its
39: .Dv CVSROOT .
40: The files within CVSROOT are as follows:
41: .Bl -tag -width Ds
42: .It Pa $CVSROOT/CVSROOT
43: Directory containing repository administrative files.
44: .It Pa $CVSROOT/CVSROOT/config
45: File containing various configuration options.
46: The format of each line is as follows:
47: .Pp
48: .Dl keyword=value
49: .Pp
50: Extraneous spaces or tabs are not permitted.
51: A line beginning with a hash character
52: .Pq Sq #
53: is considered a comment and ignored.
54: .Pp
55: The following options are available:
56: .Pp
57: .Bl -tag -width "dlimit=XvalueXXX" -offset indent -compact
58: .It dlimit='value'
59: Set the process data size limit.
60: .It tag='value'
61: Set the name of a local tag to use in addition to Id.
62: .It umask='value'
63: Set the default umask to use when creating files and directories.
64: .El
65: .It Pa $CVSROOT/CVSROOT/history
66: File containing reports of
67: .Ic checkout ,
68: .Ic commit ,
69: .Ic export ,
70: .Ic release ,
71: .Ic rtag ,
72: and
73: .Ic update
74: commands that have been issued.
75: By default, the
76: .Ic init
77: command creates the
78: .Pa history
79: file.
80: To disable history logging, the
81: .Pa history
82: file should be removed manually.
83: The
84: .Ic history
85: command shows these reports according to several criteria.
86: .It Pa $CVSROOT/CVSROOT/loginfo
87: File containing associations between modules and handlers for
88: post-commit logging.
1.5 xsa 89: .It Pa $CVSROOT/CVSROOT/modules
90: The format of each line is as follows:
91: .Pp
1.6 xsa 92: .Dl module [option] directory [file ...] [&module ...]
1.5 xsa 93: .Pp
94: Empty lines are ignored.
95: A line beginning with a hash character
96: .Pq Sq #
97: is considered a comment and ignored.
98: A long line can be continued on the next line by specifying a backslash
99: .Pq Sq \e
100: character as last character.
101: .Pp
102: The following options are available:
103: .Bl -tag -width Ds -offset 3n
104: .It Fl d Ar name
105: Allow check out of module under different
106: .Ar name .
107: .It Fl i Ar prog
108: Specify program
109: .Ar prog
110: to run whenever the
111: .Ic commit
112: command is issued.
113: .It Fl o Ar prog
114: Specify program
115: .Ar prog
116: to run whenever the
117: .Ic checkout
118: command is issued.
119: .It Fl s Ar status
120: Set
121: .Ar status
122: to module.
123: .It Fl t Ar prog
124: Specify program
125: .Ar prog
126: to run whenever the
127: .Ic rtag
128: command is issued.
129: .It Fl u Ar prog
130: Specify program
131: .Ar prog
132: to run whenever the
133: .Ic update
134: command is issued.
135: .El
1.1 jmc 136: .El
137: .Pp
138: Each directory that is managed by
139: .Nm
140: contains a
141: .Pa CVS
142: directory.
143: This directory is used by various
144: .Nm
145: commands to record the status of files in the current working directory.
146: These files should not be modified manually by the user but by the
147: .Nm
148: commands instead.
149: Files that are always stored in every
150: .Pa CVS
151: directory are as follows:
152: .Bl -tag -width Ds
153: .It Pa CVS/Entries
154: File containing a list of files managed by
155: .Nm .
156: .Pa Entries
157: has one line per file or directory describing the state of it with
158: regard to the source repository.
159: These lines have the following format:
160: .Pp
161: .Dl /name/revision/timestamp/options/tag
162: .Bl -tag -width Ds
163: .It name
164: Name of the file in the directory.
165: .It revision
166: Revision of the file in the working directory.
167: The revision is equal to
168: .Sq 0
169: if the file has been added with the
170: .Ic add
171: command or preceded by the
172: .Sq -
173: character if the file has been removed with the
174: .Ic remove
175: command.
176: .It timestamp
177: Contains the timestamp of the file at the time
178: .Nm
179: created it.
180: If the timestamp is different from the actual modification time of the file,
181: it means that the file has been modified.
182: .It options
183: Contains the keyword substitution mode used for this file.
184: .It tag
185: Contains
186: .Sq T
187: followed by a tagname or
188: .Sq D
189: followed by a date.
190: .El
191: .Pp
192: Entries corresponding to directories have the following format:
193: .Pp
194: .Dl D/name////
195: .Pp
196: The lines in the
197: .Pa Entries
198: file can be in any order.
199: .It Pa CVS/Repository
200: File containing the path to the corresponding directory in the
201: source repository.
202: .It Pa CVS/Root
203: File containing the value of the
204: .Ev CVSROOT
205: variable at the time of checkout.
206: This file is used by all
207: .Nm
208: commands instead of
209: .Ev CVSROOT
210: once
211: .Nm
212: has checked for its existence.
213: .El
214: .Pp
215: Depending on the circumstances, other files may exist in the
216: .Pa CVS
217: directory:
218: .Bl -tag -width Ds
219: .It Pa CVS/Base
220: If pseudo-lock mode is enabled in client-server mode,
221: the
222: .Pa Base
223: directory contains a copy of the file on which the
224: .Ic edit
225: command has been issued.
226: This allows the
227: .Ic unedit
228: command to operate even if the CVS server is unreachable.
229: .It Pa CVS/Baserev
230: File listing the revisions for each file contained in the
231: .Pa Base
232: directory under the following format:
233: .Pp
234: .Dl name/revision/
235: .It Pa CVS/Baserev.tmp
236: Temporary file used to write
237: .Pa CVS/Baserev
238: content then atomically renamed to
239: .Pa Baserev .
240: .It Pa CVS/Checkin.prog
241: File containing the path to the command specified with the
242: .Fl i
243: option in the
244: .Pa CVSROOT/modules
245: file.
246: .It Pa CVS/Entries.Backup
247: Temporary file used to write
248: .Pa CVS/Entries
249: content then atomically renamed to
250: .Pa Entries .
251: .It Pa CVS/Entries.Static
252: Tells
253: .Nm
254: to not add files to the directory unless the
255: .Ic update
256: command is issued with the
257: .Fl d
258: option.
259: .It Pa CVS/Notify
260: File containing the notifications that could not be sent to the
261: CVS server but will be sent at the next successful connection.
262: .It Pa CVS/Notify.tmp
263: Temporary file used to write
264: .Pa CVS/Notify
265: content then atomically renamed to
266: .Pa Notify .
267: .It Pa CVS/Tag
268: File containing the symbolic revision that was used at checkout.
269: The first character of the line is a single letter indicating the
270: type of tag:
271: .Sq D ,
272: .Sq N ,
273: or
274: .Sq T ,
275: for date, non-branch tag, or branch tag, respectively.
276: The rest of the line is the tag or date itself.
277: The
278: .Pa Tag
279: file should not be removed manually:
280: instead, use
281: .Dq update -A .
282: .It Pa CVS/Template
283: File containing the template specified by the
284: .Pa CVSROOT/rcsinfo
285: file.
286: It is only used in client-server mode.
287: Locally,
288: .Nm
289: uses the
290: .Pa rcsinfo
291: file directly.
292: .It Pa CVS/Update.prog
293: File containing the path to the command specified with the
294: .Fl u
295: option in the
296: .Pa CVSROOT/modules
297: file.
298: .It Pa CVS/<name>,t
299: File containing the description of the file
300: .Pa file
301: that has been added with the
302: .Ic add
303: command.
304: This description is used by
305: .Nm
306: when archiving this file with the
307: .Ic commit
308: command.
309: .It Pa $HOME/.cvsignore
310: This file provides a list of files (or
311: .Xr sh 1
312: file name patterns) that should be ignored by
313: .Xr cvs 1
314: during the
315: .Ic import ,
316: .Ic release ,
317: and
318: .Ic update
319: commands.
320: .Pp
321: The syntax of the
322: .Nm
323: file consists of a series of lines, each of which contains a
324: space-separated list of filenames.
325: There is currently no way of using comments in this file.
326: .Pp
327: Default patterns that are ignored by
328: .Xr cvs 1
329: are as follows:
330: .Bd -filled
331: CVS,
332: RCS,
333: RCSLOG,
334: SCCS,
335: TAGS,
336: tags,
337: core,
338: cvslog*,
339: *.o,
340: *.so,
341: *.a,
342: *.bak,
343: *.orig,
344: *.rej,
345: *.old,
346: *.exe,
347: *.depend,
348: *.obj,
349: *.elc,
350: *.ln,
351: *.olb,
352: *.core,
1.8 jmc 353: \&.#*,
1.1 jmc 354: *~,
355: _$*,
356: *$,
357: #*,
358: ,*.
359: .Ed
360: .Pp
361: The list can be modified using the methods described below:
362: .Pp
363: .Bl -enum -compact
364: .It
365: The
366: .Pa $CVSROOT/CVSROOT/cvsignore
367: file appends patterns to ignore for the whole repository.
368: .It
369: The
370: .Pa $HOME/.cvsignore
371: file appends patterns to ignore for user only.
372: .It
373: The content of the
374: .Ev CVSIGNORE
375: variable is appended to the list.
376: .It
377: Options to the command line
378: .Fl I
379: flag, available for the
380: .Ic import
381: and
382: .Ic update
383: commands, appends patterns for the current command line action only.
384: .It
385: .Pa .cvsignore
386: files placed in the repository directories allow to add patterns to
387: ignore locally.
388: They do not take effect on sub-directories.
389: .El
390: .Pp
391: The
392: .Sq !\&
393: character can be used to reset the list of patterns using any of these
394: five methods.
395: .Pp
396: For the
397: .Ic update
398: command,
399: .Xr cvs 1
400: handles files that are already present in the repository even if they
401: are in the list to ignore.
402: Files that are in the list to ignore but not in the repository will not
403: be listed.
404: This way, files preceded by the
405: .Sq ?\&
406: character will not appear even if they should.
407: .It Pa $HOME/.cvsrc
408: This file provides a way to give the
409: .Xr cvs 1
410: program implicit global options and command-specific options.
411: Unless the
412: .Fl f
413: option is specified,
414: .Xr cvs 1
415: reads its startup configuration file
416: .Pa .cvsrc
417: from the home directory of the user who invoked it.
418: .Pp
419: The format of each line is as follows:
420: .Pp
421: .Dl command [arg ...]
422: .Pp
423: where
424: .Ar command
425: is either the
426: .Sq cvs
427: keyword to specify global options, one of the supported
428: .Xr cvs 1
429: commands or a command alias.
430: Arguments following
431: .Ar command
432: will be added implicitly to the appropriate command's argument vector if it is
433: run.
434: Lines whose
435: .Ar command
1.3 tobias 436: argument is not a valid command will generate a warning when running with
1.1 jmc 437: the
1.3 tobias 438: .Fl V
439: flag.
1.1 jmc 440: .Pp
1.4 tobias 441: Empty lines are ignored.
1.1 jmc 442: A line beginning with a hash character
443: .Pq Sq #
444: is considered a comment and ignored.
445: .Pp
446: For example, to specify that
447: .Xr cvs 1
448: should always run in quiet mode and the
449: .Ic diff
450: internal command should always produce unified output:
451: .Bd -literal -offset indent
452: cvs -q
453: diff -u
454: .Ed
455: .It Pa $HOME/.cvswrappers
456: This file, located in
457: .Pa $CVSROOT/CVSROOT
458: and/or
459: .Pa $HOME/.cvswrappers ,
460: provides a way to configure filters for
461: .Xr cvs 1
462: based on file type (name).
463: This works by specifying a pattern to match for varying file types.
464: .Pp
465: The format of each line is as follows:
466: .Pp
467: .Dl pattern [option 'value'] [option 'value'] ...
468: .Pp
469: The following options are supported:
470: .Bl -tag -width Ds
471: .It Fl f Ar filter
472: Execute
473: .Ar filter
474: when the file is extracted from the repository (for the
475: .Ic checkout ,
476: .Ic export ,
477: and
478: .Ic update
479: commands).
480: .It Fl k Ar mode
481: Specify the keyword substitution mode.
1.9 ! jmc 482: See the KEYWORD SUBSTITUTION section of
1.1 jmc 483: .Xr rcs 1
484: for more information.
485: .It Fl m Ar method
486: Specify the merge methodology to be used when a file is updated.
487: .Pp
488: The methods are as follows:
489: .Bl -tag -width Ds
490: .It COPY
491: When the
492: .Ic update
493: command is used,
494: .Xr cvs 1
495: will merely copy one version over another and let the user do the merge
496: by himself.
497: This method is used by default on binary files (see the
498: .Fl k Ar b
499: option).
500: .It MERGE
501: Try to merge the files.
502: This method is the default.
503: .El
504: .It Fl t Ar filter
505: Execute
506: .Ar filter
507: before the file is archived in the repository (for the
508: .Ic commit ,
509: and
510: .Ic import
511: commands).
512: .El
513: .It Pa $TMPDIR/cvs-serv Ns Aq Pa pid
514: Temporary directory created by the server where
515: .Ar pid
516: is the process ID of the server.
517: It is located in the directory specified by the
518: .Ev TMPDIR
519: environment variable or the
520: .Fl T
521: global option.
522: See above for more information.
523: .El
524: .Sh SEE ALSO
525: .Xr cvs 1 ,
526: .Xr cvsintro 7