ViewVC logotype

Contents of /meta-cvs/F-8F7DAF614BB613A14BEA23D9E52482F5.latex

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.6 - (show annotations)
Mon Jul 29 00:51:34 2002 UTC (11 years, 8 months ago) by kaz
Branch: MAIN
CVS Tags: mcvs-1-0, mcvs-0-24, symlink-branch~branch-point, mcvs-0-22, mcvs-0-23, mcvs-0-21, mcvs-0-95, mcvs-0-99, mcvs-0-98, mcvs-1-0-branch~branch-point, mcvs-0-97, mcvs-0-96, symlink-branch~merged-to-HEAD-0, mcvs-1-0-5, mcvs-1-0-4, mcvs-1-0-7, mcvs-1-0-6, mcvs-1-0-1, mcvs-1-0-3, mcvs-1-0-2
Branch point for: symlink-branch, mcvs-1-0-branch
Changes since 1.5: +46 -10 lines
File MIME type: application/x-latex
* docs/meta-cvs.latex: Rewrote most of Introduction.
1 \documentclass{article}
2 \usepackage{makeidx}
3 \usepackage[margin=1.0in]{geometry}
5 \def\cvsrelease$#1: mcvs-#2-#3 ${#2.#3}
6 \def\cvsdate$#1: #2/#3/#4 #5 ${#2-#3-#4}
8 \def\indexcommand#1
9 {\index{#1@{\tt #1} command}
10 \index{commands!#1@{\tt #1}}}
12 \def\indexglobalopt#1
13 {\index{#1@{\tt #1} option}
14 \index{global options!#1@{\tt #1}}}
16 \def\indexcommandopt#1#2
17 {\index{#2 option@{\tt #2} option!of #1@of {\tt #1}}
18 \index{#1 command@ !#2 option@{\tt #2} option}}
20 \title{Version Control with Meta-CVS \cvsrelease$Name: $}
21 \date{\cvsdate$Date: 2002/07/29 00:51:34 $}
22 \author{Kaz Kylheku}
23 \makeindex
25 \begin{document}
26 \maketitle
27 \tableofcontents
29 \section{Introduction}
30 Greetings, reader! You are about to become a user of version control software
31 called Meta-CVS. The primary function of version control software is to store
32 multiple versions of a group of documents, such as the source files of a
33 computer program. As programmers make changes to the program, they generate
34 new versions of source files, which are retained in the version control system.
35 They may also add files, delete files, rename files, reshape the directory
36 structure of the project; the history of these changes is also retained,
37 just are the changes to the contents of the files themselves.
39 In addition, to be useful, a version control system must not only store file
40 versions but it must be able to identify groups of related versions, so that an
41 old version of the entire project can be retrieved as a unit. For example,
42 when the programmers decide to release the program, they must be able to assign
43 a symbolic name to the release, and that name must be associated with a
44 particular version of every file. This will allow the release to be later
45 retrieved using its symbolic name as a retrieval key.
47 Secondly, a version control system must allow developers to make changes in
48 parallel to the same line (or {\it stream}) of development, and merge their
49 changes.
50 \index{stream}
51 It must identify conflicting changes so that they can be resolved. In must also
52 allow for multiple parallel lines of development---independent version
53 histories known as branches. Branches are useful for stabilizing software prior
54 to the current release, while allowing new development to happen on the
55 next release. They are useful for going back to an old release and fixing
56 errors. They are also useful for isolating risky, experimental work. When such
57 work involves many changes or more than one developer, it can take place on its
58 own branch. A good version control system makes it easy to create branches, and
59 to merge new changes from the branch back to the original stream.
61 Meta-CVS is not a fully self-contained version control system. It uses another
62 version control system called CVS to store documents, and also to store
63 additional information about documents which allows it to provide useful
64 behaviors that do not exist in CVS. Effectively, Meta-CVS acts as an agent
65 between you and CVS, which is easier to use and more capable than CVS.
67 I wrote Meta-CVS because I was frustrated by the inability of CVS to treat the
68 directory structures of my projects as a versioned entity. At the same time, I
69 did not want to rewrite everything that already works well in CVS, such as
70 client-server operation, maintaining file version histories, and branching,
71 merging and conflict identification. Instead, I decided to write a software
72 layer which uses CVS as a foundation. That software layer would not only do
73 completely new things, like directory structure versioning, but also to
74 automate certain tedious tasks which are normally performed with great
75 difficulty by the users of CVS.
77 Meta-CVS does not, and is not intended to, entirely shield you from knowing
78 anything about CVS. Firstly, Meta-CVS requires the CVS software and a CVS
79 repository. Users who want to use Meta-CVS have to know how to obtain and
80 install CVS and create a repository. Moreover, from time to time it is useful
81 or necessary to bypass Meta-CVS and invoke a CVS operation directly. This
82 guide does not teach CVS; you are strongly encouraged to read {\it Version
83 Management with CVS\/} by Per Cederqvist et al. \index{Cederqvist}
85 If you do not have a CVS repository to experiment with, please read enough of
86 the Cederqvist manual to find out how to create one. Set your {\tt CVSROOT}
87 environment variable to point to your repository and you are ready to
88 explore Meta-CVS.
89 \index{CVSROOT@{\tt CVSROOT}}
91 In this guide, a few typographic conventions are used. Text which
92 is stored into or produced by the computer is written in {\tt typewriter}
93 font. The first mention of any special terms is {\it italicized}. Such terms
94 are, for your convenience, gathered into a glossary in the appendix.
96 \section{Tutorial}
98 In this section, you will learn how to place a directory tree of files under
99 version control, check out that tree to create a working copy (also called a
100 {\it sandbox}), make changes in the sandbox and store the changes in the
101 repository. A directory of files independently versioned under Meta-CVS
102 is called a {\it module}, because it is represented as a CVS
103 module.\footnote{But note that unlike CVS, Meta-CVS does not support
104 the model of combining modules.}
105 \index{sandbox}
106 \index{module}
107 \index{mcvs program@{\tt mcvs} program}
108 \index{working copy|see {sandbox}}
110 Meta-CVS has a command line interface which is deliberately similar to that of
111 CVS. The program's name is {\tt mcvs}. The {\tt mcvs} program takes a
112 variety of arguments. The first argument is usually a word which specifies
113 a command. Oft used commands have two-letter abbreviations. For example the
114 {\tt update} command, whose abbreviation is {\tt up},
115 causes material in the repository to be integrated into the working copy.
117 Before the first argument, one may type special options. These are called
118 global options, and they influence the behavior of many commands in a similar
119 way. For example, when communicating with a remote repository over a slow
120 network, the {\tt -z} option may be used to specify a compression level.
121 \indexglobalopt{-z}
123 \subsection{Creating a Module}
124 \indexcommand{create}
126 The only way to create a module is to start with an existing directory
127 containing files and subdirectories, and invoke the {\tt create} command.
128 Suppose that your project is a compiler for a scripting language called Blorg,
129 and you want your module to be called {\tt blorg}. First, change to
130 the directory containing your latest Blorg sources:
131 \index{Blorg}
132 \begin{verbatim}
133 cd blorg-devel
134 \end{verbatim}
135 Then, invoke the command:
136 \begin{verbatim}
137 mcvs create blorg blorg-initial-version
138 \end{verbatim}
139 The {\tt create} command requires two additional arguments: the name of
140 the module, and a symbolic name which will identify the baseline of
141 newly versioned files. This name is known as a {\it tag}: more specificaly, a
142 {\it version tag}. Here, we have chosen the tag {\tt blorg-initial-version}.
143 Tags are very useful when one makes a module from a specific version of an
144 existing program. Suppose that you didn't write Blorg yourself; rather, you
145 have a copy of the Blorg 2.3 sources and would like to begin your own
146 independent stream of development. It would then behoove you, when creating the
147 module, to use a tag like {\tt blorg-2-3}. This tag could prove to be very
148 important later on; for example, when you want to create a branch from the 2.3
149 baseline, which will accept a new snapshot from the Blorg developers.
150 \index{tag}
151 \index{baseline}
153 The first action that the {\tt create} command takes is to scan the current
154 working directory, and, recursively, all of its subdirectories. It forms
155 a list of all regular files, ignoring any device special files, symbolic links
156 and the like. Having thus gathered a list of the files, it identifies all
157 of their {\it suffixes} and collates them to form a list.
159 If none of the files have suffixes, the creation procedure skips to the next
160 step. Otherwise, a text editor is invoked in order to allow you to make
161 alterations to a specification which tells how files having these various
162 suffixes are to be treated when they are stored into and retrieved from CVS.
163 The specification is written in the {\it Lisp\/} language, and may look
164 something like this:
165 \index{Lisp}
166 \begin{verbatim}
167 (("c" :DEFAULT)
168 ("lisp" :DEFAULT)
169 ("png" :DEFAULT)
170 ("txt" :DEFAULT))
171 \end{verbatim}
172 This is the notation for a list of four elements, as indicated by the
173 outermost parentheses which enclose the whole thing. Each of the four
174 elements is itself a list containing a string like {\tt "c"} and the
175 symbol {\tt :DEFAULT}. The string represents a file suffix, and the
176 symbol indicates how files having that suffix are to be treated.
177 In the text editor, you should see instructions which explain the
178 various keywords which are supported. The greatest concern is to
179 identify what files are binary. For example, in the above definition,
180 the treatment of the suffix {\tt .png} should be modified to {\tt :BINARY}
181 \index{binary@{\tt :binary}}
182 \index{default@{\tt :default}}
183 because most likely this suffix indicates a computer graphics image
184 in the Portable Network Graphics format, which is a binary format
185 that must not be subject to line ending conversions, nor to keyword expansion.
186 When you are done editing, save and quit; Meta-CVS will then proceed.
187 If you create a syntax error, for example by introducing an unbalanced
188 parenthesis, Meta-CVS will prompt you with an error message, and you will
189 be given an opportunity to correct the error in a new text editing session.
190 \index{png files@{\tt png} files}
192 Note that the symbols may be typed in any mixture of upper and lower
193 case---{\tt :Binary}, {\tt :binary}, {\tt :BiNaRy}, and so forth. These
194 all mean the same thing. However, the leading colon is required.\footnote{In
195 case you are interested, that colon is a special Lisp notation which indicates
196 that the following name refers to a symbol in the {\tt KEYWORD} package.}
198 Finally, Meta-CVS invokes CVS to create a new module in the repository.
199 CVS again, brings up a text editor. This time you are expected to enter
200 a log message which will be added to version 1.1 of every new document.
201 You are, in fact, interacting with {\tt cvs import}.
202 \index{CVS!import command@{\tt import} command}
204 \subsection{Checking out a Module}
206 Like CVS, and some other version control systems, Meta-CVS is based on sandbox
207 model. Under this model, documents are copied from a central repository, and users
208 work with copies of documents. Obtaining a copy is called checking out.
209 The Meta-CVS command for checking out is {\tt checkout}, abbreviated {\tt co}.
210 \indexcommand{checkout}
211 It takes one argument. Continuing with our Blorg example:
212 \begin{verbatim}
213 mcvs co blorg
214 \end{verbatim}
215 After a log of messages scrolls by in the terminal window, there should
216 now exist the subdirectory {\tt blorg}, and in that subdirectory there
217 should appear the project's source files. This is a working copy, or a sandbox.
218 You can check out more than one sandbox; sometimes that is convenient to do
219 when one needs to work on several completely unrelated tasks in the same
220 project. The CVS repository doesn't know anything about your sandbox; rather,
221 each sandbox contains information which points back to the repository from
222 which it was checked out. It is safe to move the sandbox by applying the {\tt
223 mv} command to its root directory.
224 \index{moving!a sandbox}
226 \subsection{Anatomy of a Sandbox}
228 In the root directory of the sandbox, as you will probably notice, there is a
229 subdirectory called {\tt MCVS}. This is where Meta-CVS stores its local
230 administrative files as well as versioned metadata. It is also where your
231 documents are checked out from CVS; effectively, this directory doubles as a
232 CVS sandbox.
233 \index{MCVS subdirectory@{\tt MCVS} subdirectory}
235 All your files have been assigned machine-generated names by Meta-CVS.
236 These names begin with the characters {\tt F-} followed by thirty-two
237 hexadecimal digits and an optional suffix. In Meta-CVS jargon, they are called
238 {\it F-files}. These files are connected to the directory structure of
239 the sandbox through {\it hard links}.
240 \index{hard link}
241 That is to say, each of the F-files
242 which appear under the {\tt MCVS} directory also exist in some other
243 directory within your sandbox. This arrangement is possible because your
244 operating system allows a file object to be referenced by more than one
245 directory entry. Directories are nothing more than lists which link names to
246 file objects. The same file can be known as {\tt
247 MCVS/F-0AA69D7C8A0A864345D90F45C18B8B58} as well as {\tt source/lib/hash.c}. In
248 order to delete the file from your filesystem, you have to delete both
249 directory entries.\footnote{This is why the POSIX system function for doing
250 this is called {\tt unlink}. Deleting a directory entry doesn't necessarily
251 mean that a file is gone, only that a link, possibly not the last remaining
252 link, has been erased. \index {unlink system function@{\tt unlink}
253 system function}}
254 \index{F-file}
256 When you check out a module, Meta-CVS calls upon CVS to retrieve
257 copies of F-files from the repository. Then it re-creates the directory
258 structure of the sandbox, inserting these files in the appropriate places
259 in that structure under their familiar names. This insertion is not done
260 by copying the F-files, but rather by creating links to them, which
261 is very efficient.
263 How does Meta-CVS remember the familar names of the F-files so that it can
264 construct the sandbox? This association is recorded in a file called {\tt MAP}
265 under the {\tt MCVS} directory, represented in Lisp notation. You are going
266 to have to understand the {\tt MAP} file sooner or later, because at times it
267 is necessary to manually edit that file. For example, it can happen that
268 several programmers independently change the mapping in a way that creates a
269 conflict. Resolving the conflict means loading the file into a text editor, and
270 manually sorting out the problem.
271 \index{MAP file@{\tt MAP} file}
273 Why does Meta-CVS assigns its own internal names to files, and stores
274 the user-assigned names in a special versioned document? The reason
275 is to make it possible to perform directory structure versioning,
276 which means that the directory structure of a module is versioned just
277 like the contents of its files. Changing the name or location of
278 a file is effectively just another edit that is commited to the repository.
280 \subsection{Making Changes}
282 Now that you have a working copy checked out, you are probably eager
283 to make some changes. This is quite easy; simply edit any of the
284 files to your satisfaction. The version control system knows that you
285 have edited the files; when you are ready, you can instruct
286 the software to publish your changes to the repository. Publishing
287 changes is known as {\it committing\/} and is performed using the {\tt commit}
288 command, abbreviated {\tt ci}:\footnote{This stands for check in,
289 which means the same thing as commit in the jargon of the RCS version control
290 system. RCS has a {\tt ci} command, and this abbreviation survived into
291 CVS.\index{RCS}}
292 \indexcommand{commit}
293 \begin{verbatim}
294 mcvs ci
295 \end{verbatim}
296 A text editor starts up, and you are expected to enter a commit comment.
297 You are interacting with CVS at this point; the procedure is exactly the
298 same as for CVS commits. However, there is one notable difference. The file names
299 you see listed in the usual comment lines which begin with {\tt CVS:} and which
300 will be removed are the F-file names, rather than the human-readable
301 names. Alas, CVS doesn't know about the mapping, and this text
302 is prepared within the innards of CVS! Meta-CVS has a solution, though not an entirely
303 satisfactory one, in the form of a text filtering command which
304 reads arbitrary text on standard input, and copies it to standard output,
305 filtering F-file names to their human-readable counterparts. This command
306 is {\tt filt}, abbreviated~{\tt fi}.
307 \indexcommand{filt}
308 Decent text editors allow portions of the text to be easily filtered through
309 an external command. For example, in the vi editor, the command
310 {\tt :\%!mcvs fi} command will apply the Meta-CVS filter to the entire edit
311 buffer. It's trivial to bind this this command to a control character, and
312 store this definition in the editor's personal configuration file, so that the
313 action can be repeated by typing one or two keystrokes.
315 \subsection{Adding Files}
317 Some kinds of changes require special steps to inform Meta-CVS of
318 your intent. For example, if you decide to add some files, Meta-CVS
319 will not automatically incorporate them into the module. For obvious
320 reasons, a sandbox is allowed to contain a mixture of local files and
321 versioned files; there is no certain way to tell which local files ought
322 to be versioned. An object file which results from compiling source
323 code almost certainly does not belong under version control, whereas a
324 new source file probably does. Or does it? It may be a temporary module
325 introduced for debugging, or some experimental code. Only the programmer
326 knows whether it ought to be published to the repository. Every file that
327 is added under version control initially starts out as a local file. An
328 explicit {\tt add} command must be invoked to cause a local file to become
329 versioned. This is a local change until it is committed to the repository,
330 at which point the newly added file becomes visible to other sandboxes.
332 \indexcommand{add}
333 Adding files is accomplished using the {\tt add} command. The add command
334 requires additional arguments which specify what files are to be added.
335 For exaple, to add the local files {\tt macros.lisp} and {\tt README},
336 issue the command:
337 \begin{verbatim}
338 mcvs add macros.lisp README
339 \end{verbatim}
340 Unlike CVS, Meta-CVS allows you to add entire subdirectories at a time.
341 The arguments can be any mixture of files and subdirectories; however,
342 subdirectories are only added if the {\tt -R} option is specified.
343 For example, to add the directories {\tt sources}, {\tt documentation}
344 and the file {\tt INSTALL}.
345 \begin{verbatim}
346 mcvs add -R sources documentation INSTALL
347 \end{verbatim}
348 \indexcommandopt{add}{-R}
349 Like the {\tt create} command, the {\tt add} command scans the
350 files to be added, and computes a list of their suffixes. If there
351 are any hitherto unknown suffixes in the added set, a text editor
352 will be invoked to allow you to specify the treatment of these
353 files.
354 The effect of {\tt mcvs add} is local; the files aren't incorporated
355 into the repository until a commit takes place.
357 \subsection{Reviewing Changes}
359 Before committing local changes, one usually wants to review what those changes
360 are; to find out what files have been added, removed, moved or modified, and to
361 view the differences in modified files. The {\tt status}, or {\tt stat}
362 command, invoked without any arguments, produces a listing of all modified
363 files in the current directory and its subdirectories. To include the
364 meta-data files such as {\tt MAP}, use the {\tt --meta} global option.
365 \indexglobalopt{--meta}
366 \indexcommand{status}
367 \index{MAP file@{\tt MAP} file}
368 The output of {\tt status} contains F-file names, so the {\tt filt} command
369 comes in handy. And of course the {\tt grep} utility is useful in reducing
370 the output to include information only about locally modified files:
371 \index{grep}
372 \begin{verbatim}
373 mcvs --meta status | grep Modified | mcvs fi # list modified files
374 mcvs status | grep Added | mcvs fi # list added files
375 \end{verbatim}
376 The {\tt status} command takes optional filename and directory arguments.
377 The status of a directory means all of the files in its tree.
379 Another useful command is {\tt diff} which views differences between revisions,
380 or between the locally modified files and their closest repository revisions.
381 Like {\tt stat}, {\tt diff} responds to the {\tt --meta} global option,
382 works on the current directory by default, and takes optional file name or
383 directory arguments. It supports a large number of options which affect
384 the way the differences are computed and presented. The two most useful are
385 {\tt -u} which produces a more readable, so-called ``unified'' diff,
386 and {\tt -b} which suppresses differences in whitespace, which is particularly
387 useful when a few small coding changes in a program gives rise to a big
388 change in indentation. For example,
389 \indexcommand{diff}
390 \indexcommandopt{diff}{-u}
391 \indexcommandopt{diff}{-b}
392 \begin{verbatim}
393 mcvs diff -ub driver.c
394 \end{verbatim}
395 shows the modifications in driver.c as a unified diff, treating lines
396 that differ only in the amount of whitespace as identical.
398 \subsection{Error Recovery}
402 \appendix
404 \section{Glossary}
406 \paragraph{baseline} A crosscut through a collection of version-controlled
407 documents, which selects a specific version of each document.
408 \index{baseline}
410 \paragraph{basename} The short name of a file, excluding the fullp path,
411 if any. For example, the basename of {\tt src/lib/lexer.c} is {\tt lexer.c}.
412 \index{basename}
414 \paragraph{commit} To publish local changes to the repository, thereby
415 permanently integrating them into the project history. Commited changes
416 can be picked up in other sandboxes by {\it update}.
418 \paragraph{CVS} Concurrent Versions System. A popular freeware version control
419 suite widely used by free software projects. CVS started as a set of shell
420 scripts written by Dick Grune, who posted the software to Usenet in 1986.
421 Grune's CVS scripts used RCS; they provided higher-level functionality over
422 RCS, automating and simplifying the use of RCS by for instance applying version
423 control operations such as merging to entire sets of files at once.
424 Eventually, CVS was rewritten in C, and directly incorporated the algorithms
425 from RCS while remaining compatible with the RCS file format.
426 \index{CVS}
428 \paragraph{F-file} A user document stored by Meta-CVS, in CVS, having a
429 machine-generated name consisting of the characters {\tt F-} followed
430 by thirty-two hexadecimal digits and an optional suffix.
431 \index{F-file}
433 \paragraph{hard link} An association connecting a directory entry to a file
434 object.
435 \index{hard link}
437 \paragraph{Lisp} {\bf 1.} The standard computing language {\it ANSI Common
438 Lisp}. {\bf 2.} Printed notation, conforming to the ANSI Common Lisp syntax,
439 expressing a potentially complex, nested data structure. {\bf 3.} Program code
440 resulting from the reinterpretation of Lisp data structures as programming
441 language constructs.
442 \index{Lisp}
444 \paragraph{module} An independent set of documents managed as a unit using
445 Meta-CVS.
446 \index{module}
448 \paragraph{sandbox} The working copy of your project.
449 \index{sandbox}
451 \paragraph{stream} An independent line of development, represented in
452 the version control system as an independent history of changes.
453 In Meta-CVS, there is a main history known as the trunk. Secondary histories
454 are called branches.
455 \index{stream}
457 \paragraph{suffix} The trailing portion of a {\it basename} which is separated
458 from the rest of the name by a period (.) character. If there are two or
459 more such characters, then it is the longest such portion. If the basename
460 contains no periods, then it has no suffix. If the basename begins with a
461 period, the rest of that entire name is a suffix. Examples:
462 the suffix of {\tt lint.tar.gz} is {\tt tar.gz}; that of {\tt .xshell.rc}
463 is {\tt xshell.rc}; the suffix of {\tt foo.} is the empty string; and neither
464 {\tt .clisprc} nor {\tt README} have a suffix.
465 \index{suffix}
467 \paragraph{tag} A symbolic revision which identifies a {\it baseline}. Tags
468 are used by disciplined developers, or configuration managers, to label
469 software releases so that it is possible to later retrieve the exact baseline
470 of any given release.
471 \index{tag}
473 \paragraph{update} In CVS parlance, to retrieve a version of one or more
474 documents from the repository, merge it with local changes made to the sandbox
475 copy, if any, and then replace that copy. Updating is not only used to
476 incorporate the latest changes from the repository into a sandbox, while
477 preserving any outstanding local modifications, but it is also used for
478 ``navigating'' to old versions and switching among branches.
480 \index{renaming|see {moving}}
481 \printindex
482 \end{document}

  ViewVC Help
Powered by ViewVC 1.1.5