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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1 by kaz, Mon Jul 8 15:57:47 2002 UTC revision 1.2 by kaz, Thu Jul 11 17:45:50 2002 UTC
# Line 1  Line 1 
1  \documentclass{article}  \documentclass{article}
2  \begin{document}  \usepackage{makeidx}
3    \usepackage[margin=1.0in]{geometry}
4    
5    \def\cvsrelease$Name${#1.#2}
6    \def\cvsdate$Date${#1-#2-#3}
7    
8  \def\release$#1: #2-#3-#4 ${#3.#4}  \def\indexcommand#1
9    {\index{#1@{\tt #1} command}
10     \index{commands!#1@{\tt #1}}}
11    
12  % $Date$  \def\indexglobalopt#1
13    {\index{#1@{\tt #1} option}
14     \index{global options!#1@{\tt #1}}}
15    
16  \title{Version Control with Meta-CVS \release$Release: mcvs-0-18 $}  \title{Version Control with Meta-CVS \cvsrelease$Name$}
17  \date{release }  \date{\cvsdate$Date$}
18  \author{Kaz Kylheku}  \author{Kaz Kylheku}
19    \makeindex
20    
21    \begin{document}
22  \maketitle  \maketitle
23    \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    
402    \index{renaming|see {moving}}
403    \printindex
404  \end{document}  \end{document}

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2

  ViewVC Help
Powered by ViewVC 1.1.5