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

Revision 1.4 - (hide annotations)
Sat Jul 13 15:46:42 2002 UTC (11 years, 5 months ago) by kaz
Branch: MAIN
CVS Tags: mcvs-0-20, mcvs-0-19
Changes since 1.3: +45 -3 lines
File MIME type: application/x-latex
New macros; tutorial sections on stat and diff.

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