Annotation of src/usr.bin/cvs/cvs.5, Revision 1.3
1.3 ! tobias 1: .\" $OpenBSD: cvs.5,v 1.2 2007/05/31 19:20:09 jmc Exp $
1.1 jmc 2: .\"
3: .\" Copyright (c) 2004 Jean-Francois Brousseau <jfb@openbsd.org>
4: .\" Copyright (c) 2004-2007 Xavier Santolaria <xsa@openbsd.org>
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.3 ! tobias 27: .Dd $Mdocdate: May 31 2007 $
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.
89: .El
90: .Pp
91: Each directory that is managed by
92: .Nm
93: contains a
94: .Pa CVS
95: directory.
96: This directory is used by various
97: .Nm
98: commands to record the status of files in the current working directory.
99: These files should not be modified manually by the user but by the
100: .Nm
101: commands instead.
102: Files that are always stored in every
103: .Pa CVS
104: directory are as follows:
105: .Bl -tag -width Ds
106: .It Pa CVS/Entries
107: File containing a list of files managed by
108: .Nm .
109: .Pa Entries
110: has one line per file or directory describing the state of it with
111: regard to the source repository.
112: These lines have the following format:
113: .Pp
114: .Dl /name/revision/timestamp/options/tag
115: .Bl -tag -width Ds
116: .It name
117: Name of the file in the directory.
118: .It revision
119: Revision of the file in the working directory.
120: The revision is equal to
121: .Sq 0
122: if the file has been added with the
123: .Ic add
124: command or preceded by the
125: .Sq -
126: character if the file has been removed with the
127: .Ic remove
128: command.
129: .It timestamp
130: Contains the timestamp of the file at the time
131: .Nm
132: created it.
133: If the timestamp is different from the actual modification time of the file,
134: it means that the file has been modified.
135: .It options
136: Contains the keyword substitution mode used for this file.
137: .It tag
138: Contains
139: .Sq T
140: followed by a tagname or
141: .Sq D
142: followed by a date.
143: .El
144: .Pp
145: Entries corresponding to directories have the following format:
146: .Pp
147: .Dl D/name////
148: .Pp
149: The lines in the
150: .Pa Entries
151: file can be in any order.
152: .It Pa CVS/Repository
153: File containing the path to the corresponding directory in the
154: source repository.
155: .It Pa CVS/Root
156: File containing the value of the
157: .Ev CVSROOT
158: variable at the time of checkout.
159: This file is used by all
160: .Nm
161: commands instead of
162: .Ev CVSROOT
163: once
164: .Nm
165: has checked for its existence.
166: .El
167: .Pp
168: Depending on the circumstances, other files may exist in the
169: .Pa CVS
170: directory:
171: .Bl -tag -width Ds
172: .It Pa CVS/Base
173: If pseudo-lock mode is enabled in client-server mode,
174: the
175: .Pa Base
176: directory contains a copy of the file on which the
177: .Ic edit
178: command has been issued.
179: This allows the
180: .Ic unedit
181: command to operate even if the CVS server is unreachable.
182: .It Pa CVS/Baserev
183: File listing the revisions for each file contained in the
184: .Pa Base
185: directory under the following format:
186: .Pp
187: .Dl name/revision/
188: .It Pa CVS/Baserev.tmp
189: Temporary file used to write
190: .Pa CVS/Baserev
191: content then atomically renamed to
192: .Pa Baserev .
193: .It Pa CVS/Checkin.prog
194: File containing the path to the command specified with the
195: .Fl i
196: option in the
197: .Pa CVSROOT/modules
198: file.
199: .It Pa CVS/Entries.Backup
200: Temporary file used to write
201: .Pa CVS/Entries
202: content then atomically renamed to
203: .Pa Entries .
204: .It Pa CVS/Entries.Static
205: Tells
206: .Nm
207: to not add files to the directory unless the
208: .Ic update
209: command is issued with the
210: .Fl d
211: option.
212: .It Pa CVS/Notify
213: File containing the notifications that could not be sent to the
214: CVS server but will be sent at the next successful connection.
215: .It Pa CVS/Notify.tmp
216: Temporary file used to write
217: .Pa CVS/Notify
218: content then atomically renamed to
219: .Pa Notify .
220: .It Pa CVS/Tag
221: File containing the symbolic revision that was used at checkout.
222: The first character of the line is a single letter indicating the
223: type of tag:
224: .Sq D ,
225: .Sq N ,
226: or
227: .Sq T ,
228: for date, non-branch tag, or branch tag, respectively.
229: The rest of the line is the tag or date itself.
230: The
231: .Pa Tag
232: file should not be removed manually:
233: instead, use
234: .Dq update -A .
235: .It Pa CVS/Template
236: File containing the template specified by the
237: .Pa CVSROOT/rcsinfo
238: file.
239: It is only used in client-server mode.
240: Locally,
241: .Nm
242: uses the
243: .Pa rcsinfo
244: file directly.
245: .It Pa CVS/Update.prog
246: File containing the path to the command specified with the
247: .Fl u
248: option in the
249: .Pa CVSROOT/modules
250: file.
251: .It Pa CVS/<name>,t
252: File containing the description of the file
253: .Pa file
254: that has been added with the
255: .Ic add
256: command.
257: This description is used by
258: .Nm
259: when archiving this file with the
260: .Ic commit
261: command.
262: .It Pa $HOME/.cvsignore
263: This file provides a list of files (or
264: .Xr sh 1
265: file name patterns) that should be ignored by
266: .Xr cvs 1
267: during the
268: .Ic import ,
269: .Ic release ,
270: and
271: .Ic update
272: commands.
273: .Pp
274: The syntax of the
275: .Nm
276: file consists of a series of lines, each of which contains a
277: space-separated list of filenames.
278: There is currently no way of using comments in this file.
279: .Pp
280: Default patterns that are ignored by
281: .Xr cvs 1
282: are as follows:
283: .Bd -filled
284: CVS,
285: RCS,
286: RCSLOG,
287: SCCS,
288: TAGS,
289: tags,
290: core,
291: cvslog*,
292: *.o,
293: *.so,
294: *.a,
295: *.bak,
296: *.orig,
297: *.rej,
298: *.old,
299: *.exe,
300: *.depend,
301: *.obj,
302: *.elc,
303: *.ln,
304: *.olb,
305: *.core,
306: .#*,
307: *~,
308: _$*,
309: *$,
310: #*,
311: ,*.
312: .Ed
313: .Pp
314: The list can be modified using the methods described below:
315: .Pp
316: .Bl -enum -compact
317: .It
318: The
319: .Pa $CVSROOT/CVSROOT/cvsignore
320: file appends patterns to ignore for the whole repository.
321: .It
322: The
323: .Pa $HOME/.cvsignore
324: file appends patterns to ignore for user only.
325: .It
326: The content of the
327: .Ev CVSIGNORE
328: variable is appended to the list.
329: .It
330: Options to the command line
331: .Fl I
332: flag, available for the
333: .Ic import
334: and
335: .Ic update
336: commands, appends patterns for the current command line action only.
337: .It
338: .Pa .cvsignore
339: files placed in the repository directories allow to add patterns to
340: ignore locally.
341: They do not take effect on sub-directories.
342: .El
343: .Pp
344: The
345: .Sq !\&
346: character can be used to reset the list of patterns using any of these
347: five methods.
348: .Pp
349: For the
350: .Ic update
351: command,
352: .Xr cvs 1
353: handles files that are already present in the repository even if they
354: are in the list to ignore.
355: Files that are in the list to ignore but not in the repository will not
356: be listed.
357: This way, files preceded by the
358: .Sq ?\&
359: character will not appear even if they should.
360: .It Pa $HOME/.cvsrc
361: This file provides a way to give the
362: .Xr cvs 1
363: program implicit global options and command-specific options.
364: Unless the
365: .Fl f
366: option is specified,
367: .Xr cvs 1
368: reads its startup configuration file
369: .Pa .cvsrc
370: from the home directory of the user who invoked it.
371: .Pp
372: The format of each line is as follows:
373: .Pp
374: .Dl command [arg ...]
375: .Pp
376: where
377: .Ar command
378: is either the
379: .Sq cvs
380: keyword to specify global options, one of the supported
381: .Xr cvs 1
382: commands or a command alias.
383: Arguments following
384: .Ar command
385: will be added implicitly to the appropriate command's argument vector if it is
386: run.
387: Lines whose
388: .Ar command
1.3 ! tobias 389: argument is not a valid command will generate a warning when running with
1.1 jmc 390: the
1.3 ! tobias 391: .Fl V
! 392: flag.
1.1 jmc 393: .Pp
394: Empty lines and lines specifying no optional arguments are ignored.
395: A line beginning with a hash character
396: .Pq Sq #
397: is considered a comment and ignored.
398: .Pp
399: For example, to specify that
400: .Xr cvs 1
401: should always run in quiet mode and the
402: .Ic diff
403: internal command should always produce unified output:
404: .Bd -literal -offset indent
405: cvs -q
406: diff -u
407: .Ed
408: .It Pa $HOME/.cvswrappers
409: This file, located in
410: .Pa $CVSROOT/CVSROOT
411: and/or
412: .Pa $HOME/.cvswrappers ,
413: provides a way to configure filters for
414: .Xr cvs 1
415: based on file type (name).
416: This works by specifying a pattern to match for varying file types.
417: .Pp
418: The format of each line is as follows:
419: .Pp
420: .Dl pattern [option 'value'] [option 'value'] ...
421: .Pp
422: The following options are supported:
423: .Bl -tag -width Ds
424: .It Fl f Ar filter
425: Execute
426: .Ar filter
427: when the file is extracted from the repository (for the
428: .Ic checkout ,
429: .Ic export ,
430: and
431: .Ic update
432: commands).
433: .It Fl k Ar mode
434: Specify the keyword substitution mode.
435: See the
436: .Sx KEYWORD SUBSTITUTION
437: section of
438: .Xr rcs 1
439: for more information.
440: .It Fl m Ar method
441: Specify the merge methodology to be used when a file is updated.
442: .Pp
443: The methods are as follows:
444: .Bl -tag -width Ds
445: .It COPY
446: When the
447: .Ic update
448: command is used,
449: .Xr cvs 1
450: will merely copy one version over another and let the user do the merge
451: by himself.
452: This method is used by default on binary files (see the
453: .Fl k Ar b
454: option).
455: .It MERGE
456: Try to merge the files.
457: This method is the default.
458: .El
459: .It Fl t Ar filter
460: Execute
461: .Ar filter
462: before the file is archived in the repository (for the
463: .Ic commit ,
464: and
465: .Ic import
466: commands).
467: .El
468: .It Pa $TMPDIR/cvs-serv Ns Aq Pa pid
469: Temporary directory created by the server where
470: .Ar pid
471: is the process ID of the server.
472: It is located in the directory specified by the
473: .Ev TMPDIR
474: environment variable or the
475: .Fl T
476: global option.
477: See above for more information.
478: .El
479: .Sh SEE ALSO
480: .Xr cvs 1 ,
481: .Xr cvsintro 7