/[meta-cvs]/meta-cvs/F-F1216688DF5C31C04736DBD403342A77
ViewVC logotype

Contents of /meta-cvs/F-F1216688DF5C31C04736DBD403342A77

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.7 - (hide annotations)
Sun Jun 23 19:18:11 2002 UTC (11 years, 10 months ago) by kaz
Branch: MAIN
CVS Tags: mcvs-0-20, partial-sandbox-branch~branch-point, old-convert-hacking-branch~branch-point, partial-sandbox-branch~merged-to-HEAD-0, mcvs-0-16, mcvs-0-15, mcvs-0-17, mcvs-0-19, mcvs-0-18
Branch point for: partial-sandbox-branch, old-convert-hacking-branch
Changes since 1.6: +18 -17 lines
The ``import'' command is renamed to ``create''.

* mcvs.main (*create-options*): Renamed to *import-options*.
(*mcvs-command-table*): Updated.
(*usage*): Updated.

* import.lisp: File renamed to create.lisp.
(mcvs-import): Renamed to mcvs-create; some arguments renamed.
(mcvs-import-wrapper): Renamed to mcvs-create-wrapper.

* README: Updated.
1 kaz 1.6 A Quick Guide to Using Meta-CVS
2 kaz 1.1
3 kaz 1.6 Kaz Kylheku
4     January 25, 2002
5 kaz 1.1
6 kaz 1.6 "Anything you can do, I can do meta." -- origin unknown
7 kaz 1.3
8 kaz 1.1
9     Contents
10    
11 kaz 1.3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . Line 15
12     2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
13 kaz 1.6 3. Filtering F- Names to Readable Names . . . . . . . . . . . . 65
14     4. Getting Started . . . . . . . . . . . . . . . . . . . . . . .
15     4.1 Creating a Module . . . . . . . . . . . . . . . . . . . . .
16     4.2 Checking Out a Module . . . . . . . . . . . . . . . . . . .
17 kaz 1.1
18     1. Introduction
19    
20 kaz 1.5 This is a guide toward using Meta-CVS. It assumes familiarity with
21 kaz 1.1 version control concepts and in particular with the CVS software.
22 kaz 1.5 In particular, it is assumed that you have hands-on experience
23     with CVS and that you have read the Cederqvist manual.
24 kaz 1.1
25 kaz 1.5 In principle, Meta-CVS could be understood as a version control
26 kaz 1.1 tool independently of CVS; in practice it helps to know CVS,
27 kaz 1.5 particularly because Meta-CVS is relatively new software, and
28     because it is not intended to perfectly hide CVS from the user.
29 kaz 1.1
30 kaz 1.5 It is also assumed that you have successfully installed Meta-CVS.
31 kaz 1.1 For installation instructions see the file INSTALL.
32    
33 kaz 1.5 To gain some understanding of how Meta-CVS represents your data
34     and how it works, read Meta-CVS-PAPER.
35 kaz 1.1
36    
37     2. Overview
38    
39 kaz 1.5 Meta-CVS has a command syntax that is deliberately similar to the
40     CVS command syntax. In general, a Meta-CVS command looks like
41 kaz 1.1 this:
42    
43 kaz 1.6 mcvs [ mcvs-options ] command [ command-options ] [ arguments ]
44 kaz 1.1
45     Most of the options are simply passed through to CVS, when
46     appropriate. So for example,
47    
48 kaz 1.6 mcvs -z 3 update -A
49 kaz 1.1
50 kaz 1.4 will pass through the -z 3 and -A options down to CVS when invoking
51 kaz 1.1 it, so that CVS ends up being called as:
52    
53 kaz 1.6 cvs -z 3 update -A
54 kaz 1.1
55 kaz 1.5 This passing through of options makes it easy to use Meta-CVS for
56 kaz 1.1 users who are familiar with CVS, and is also straightforward to
57 kaz 1.5 deal with in the bowels of Meta-CVS.
58 kaz 1.1
59     Not all options are passed through to CVS, and there are some that
60 kaz 1.5 are entirely Meta-CVS-specific. Think of Meta-CVS as implementing
61     an intelligent filter over the CVS options. For example, if you
62 kaz 1.6 invoke ``mcvs --version'', you don't want ``cvs --version'' to be
63     called. Similarly, if you invoke ``mcvs -Q'', you want Meta-CVS
64     as well as CVS to operate silently, so -Q has to be processed in
65     Meta-CVS as well as passed to CVS.
66 kaz 1.2
67    
68     3. Filtering F- Names to Readable Names
69    
70 kaz 1.5 The Meta-CVS representation brings a readability problem: the
71     cryptic F- names appear in the output produced by CVS, making it
72     difficult to understand what file the output pertains to. For
73     this reason, Meta-CVS includes a filtering command (``mcvs filt'')
74     which can be used in a pipe to filter out the cryptic names and
75     replace them with the paths that they map to. For example:
76 kaz 1.2
77 kaz 1.6 mcvs diff | mcvs filt
78 kaz 1.2
79     produces a human-readable diff.
80    
81 kaz 1.5 The filter works by looking for character sequences consisting of
82     the prefix ``F-'' followed by exactly 32 hex digits. If such a
83     sequence is mapped in the MAP-LOCAL file, then it is replaced by
84     its mapping. Anything which doesn't match or doesn't map is passed
85 kaz 1.6 through unchanged. F- files can also have suffixes after the 32
86     hex digits; there has to be an exact match on a suffix.
87    
88    
89     4. Getting Started
90    
91     4.1 Creating a Module
92    
93     The only way to create a Meta-CVS module is to have an existing set
94 kaz 1.7 of files, or an empty directory, and invoke the create command
95     in the top level directory.
96 kaz 1.6
97     1. Change to the topmost directory of the file tree that you want to
98 kaz 1.7 place under Meta-CVS.
99 kaz 1.6
100     2. Invoke
101    
102 kaz 1.7 mcvs create <module-name> <vendor-tag> <release-tag>
103 kaz 1.6
104     The <module-name> specifies what your module will be called; it
105     need not be the same as the name of the top level directory.
106     When later you check out the module, you will have to specify that
107     name, and by default a directory of that name will be created.
108    
109 kaz 1.7 The <vendor-tag> and <release-tag> are artifacts of cvs import,
110     which is the command that Meta-CVS uses to create the CVS repository for the
111     new project. These arguments must be specified. The vendor-tag is used
112     by CVS to tag the vendor branch on which the import takes place. The
113     release-tag tags all the newly imported file revisions.
114    
115     (!) Note that CVS vendor branches do not work in Meta-CVS;
116     each mcvs create operation creates a new unique set of files, so doing
117     multiple imports over the same Meta-CVS module will *not* work like it
118     does in CVS. As a workaround, if you want to synchronize with third
119     party sources, you can do so manually using ordinary branches.
120 kaz 1.6
121     3. If your file tree contains any files whose names have suffixes,
122     Meta-CVS will gather a list of these suffixes and bring up a text
123     editor. You are expected to edit the information, save it and
124     exit the editor. This gives you an opportunity to set the CVS keyword
125     expansion mode for each file type. The association is represented
126     as Lisp association list. For example, if your file tree contains
127     C source and header files, you will probably see something like this:
128    
129     (("c" :DEFAULT)
130     ("h" :DEFAULT))
131    
132     This is a list of sublists. Each sublists contains two elements,
133     a string representing the file suffix, and a Lisp keyword (a colon
134     followed by identifier). The keyword represents how files of that
135     type will be handled, simply edit the keyword. There is helpful
136     comment text at the top of the file which explains what keywords
137     are available and what CVS expansion modes they correspond to.
138    
139     4. Now CVS is invoked to do the import. CVS will also bring up a text
140     editor so that you can specify an import comment. This part should
141     be familiar to the CVS user.
142    
143 kaz 1.7 5. The module should now be created, and is ready to be checked out.
144 kaz 1.6
145     Note that Meta-CVS does not store empty directories at all. This behavior
146     differs from CVS in a subtle way. With CVS, you can create an empty
147     directory structure, and import it. The corresponding structure will be
148     created in the CVS repository, and you can check out that structure
149     (unless you specify prune with -P, or pruning is otherwise implicit).
150     Under Meta-CVS, a directory is treated a filesystem artifact that arises
151     from multi-part path names. Two files appear in the same directory by
152     virtue of having common path components; that directory only exists
153     because those two files exist. Refer to the Meta-CVS-PAPER.
154    
155     Thus, if you wish to create a new empty project, don't bother making a
156     multi-level directory tree. Just create one empty directory with no
157 kaz 1.7 subdirectories, and invoke mcvs create in that directory. It will be
158 kaz 1.6 easy to add directories later. Under Meta-CVS, the add command is
159     recursive if you specify -R, unlike under CVS which requires directories
160     to be added individually, and then files. The Meta-CVS add command also
161     identifies any new file suffixes and prompts you to edit how they
162 kaz 1.7 will be handled, similarly to the create command.
163 kaz 1.6
164    
165     4.2 Checking Out a Module

  ViewVC Help
Powered by ViewVC 1.1.5