/[meta-cvs]/meta-cvs/F-8F7DAF614BB613A14BEA23D9E52482F5.latex
ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log


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

  ViewVC Help
Powered by ViewVC 1.1.5