mitgcm.org/front_content/using_cvs.xml

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta name="generator" content="HTML Tidy, see www.w3.org" />
    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
    <base href="http:/mitgcm.org" />

    <!-- Hinting for menu generation -->
    <meta name="add_name_0" content="Source Code" />
    <meta name="add_name_1" content="Using CVS" />
    <meta name="add_name_2" content="" />
    <meta name="add_title" content="Using CVS" />
    <!-- Hinting for menu generation -->

<style type="text/css">
 span.c2 {font-size: 110%}
 div.c1 {text-align: center}
</style>
  </head>

  <body>
    
    <center>
      <h3>Obtaining the MITgcm Source using CVS</h3>
    </center>

    <h4>Using CVS "pserver" for Anonymous Access</h4>

    <p>The most convenient way to get local copies of the MITgcm source code is
      to use the CVS "pserver" mechanism.  This method only allows you to "check
      out" (or obtain a local copy) of the source.  It does not provide a
      mechanism for "committing" or "checking in" changes (please see below).
      Using CVS pserver from the command line requires just a three commands.
      Using a Bourne, "bash", or "sh-compatible" shell they are:</p>
    
<pre>
  $ export CVSROOT=':pserver:cvsanon@mitgcm.org:/u/gcmpack'
  $ cvs login 
    ( enter the CVS password: "cvsanon" )
  $ cvs co MITgcm
</pre>

    <p>Using a "C", "csh", or "tcsh" shell the commands are:</p>

<pre>
  $ setenv CVSROOT ':pserver:cvsanon@mitgcm.org:/u/gcmpack'
  $ cvs login
    ( enter the CVS password: "cvsanon" )
  $ cvs co MITgcm
</pre>

    <p>A large amount of additional (optional!) content can be obtained from the
      MITgcm_contrib directory that can be checked out using:

<pre>
  $ cvs co MITgcm_contrib
</pre>

      In general, we do not recommend checking out all of MITgcm_contrib since
      it takes a long time to download (particularly from remote locations) and
      much of it is specific to certain setups (eg. high-res setups,
      in-development material that is not yet part of the "main" code,
      etc.).</p>

    <p>Note that you will only need to perform the "cvs login" once.  And for
      convenience, you may want to add the CVSROOT variable to your shell's
      environment (that is, define it within your "~/.bashrc" or "~/.chsrc"
      files).</p>


    <h4>Getting Parts of the Source "Tree"</h4>

    <p>The above commands demonstrate how to check out all of the MITgcm code
      and the "contributed" (that is, unsupported by occasionally useful)
      information within the "MITgcm_contrib" directory.  In many cases, this is
      overkill and can result in long download times.  To reduce the volume of
      information downloaded and thereby speedup the download times, one can
      select one of the following pre-defined "aliases" that will provide a
      sub-set of the entire MITgcm source "tree":</p>

    <table align="center" border="0" cellpadding="10" width="90%" summary="CVS
      aliases">
      <tr bgcolor="#00cccc">
        <td width="25%">Alias Name</td>
        <td>Information (directories) Contained</td>
      </tr>
      <tr bgcolor="#bbffdd">
        <td width="25%">MITgcm_code</td>
        <td>Only the source code -- none of the verification examples.</td>
      </tr>
      <tr bgcolor="#bbddff">
        <td width="25%">MITgcm_verif_basic</td>
        <td>Source code plus a small set of the verification examples
          ("aim.5l_cs", "hs94.128x64x5", "ideal_2D_oce", "lab_sea",
           "tutorial_baroclinic_gyre", "tutorial_global_oce_latlon"
           and "tutorial_plume_on_slope").</td>
      </tr>
      <tr bgcolor="#bbffdd">
        <td width="25%">MITgcm_tutorials</td>
        <td>Source code plus all of the tutorials examples.</td>
      </tr>
      <tr bgcolor="#bbddff">
        <td width="25%">MITgcm_verif_all</td>
        <td>Source code plus all of the verification examples.</td>
      </tr>
      <!--
      <tr bgcolor="#bbffdd">
        <td width="25%">MITgcm_verif_atmos</td>
        <td>Source code plus all of the atmospheric examples.</td>
      </tr>
      <tr bgcolor="#bbddff">
        <td width="25%">MITgcm_verif_ocean</td>
        <td>Source code plus all of the oceanic examples.</td>
     </tr>
      <tr bgcolor="#bbddff">
        <td width="25%"></td>
        <td></td>
     </tr>
      <tr bgcolor="#bbffdd">
        <td width="25%"></td>
        <td></td>
      </tr>
      -->
    </table>

    <p>It is important to note that the CVS aliases above cannot be used in
      conjunction with the CVS <i>-d DIRNAME</i> option.  However, the MITgcm
      directories they create can be changed to a different name following the
      check-out:</p>
<pre>
  $ cvs co MITgcm_verif_basic
  $ mv MITgcm MITgcm_verif_basic
</pre>

    <h4>Getting Specific Releases or "Checkpoints"</h4>
    
    <p>As shown within the 
      <!-- <a href="http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index">CVS Code Browser</a> -->
      <a href="http://mitgcm.org/viewvc/MITgcm/MITgcm/doc/tag-index">CVS Code Browser</a>
      , the MITgcm code is continuously undergoing updates.  At
      points during the development (typically, after work has been done and the
      source code has passed the <a href="./testing.html">verification
      tests</a>), a release or checkpoint "tag" is created.  These tags are a
      convenient mechanism for referring to different times or points within the
      development.  One can check out these versions using the "-r TAG_NAME" CVS
      option such as: </p>

<pre>
  $ cvs co -r release1_p5 MITgcm
  $ cvs co -r checkpoint52a_post MITgcm
</pre>

    <p>By default (that is, when no tag is specified), CVS will retrieve the
      latest version of all files.</p>


    <h4>Show changes that YOU have made</h4>

    <p>If you are running into difficulties it is very useful to see the changes
      that you yourself have made since obtaining the code.  From within
      your working directory:</p>

<pre>
  cvs diff
</pre>


    <p>will show the differences between your version and the version that you
      checked out. It acts recursively on all directories below your current
      directory. You can limit the operation to just one file or directory by
      specifying those as arguments:</p>

<pre>
  cvs diff <i>file</i>
</pre>


    <h4>Show changes to the repository that you don't have</h4>

    <p>The source code evolves continuously and you should try to stay up to
      date.  To see what needs to be updated:</p>

<pre>
  cvs -n update
</pre>

    <p>behaves just as "cvs update" but doesn't actually change anything. This
      is a useful way of summarizing the state of your code. The meaning of the
      output is summarized in the next topic.</p>

    <h4>Getting updates from the repository</h4>

    <p>You can download and merge updates from the repository to bring you
      working code up to date:</p>

<pre>
  cvs update -d -P
</pre>

      <p>will work recursively on all files in the current directory and below.
        To update just a specific file or directory:</p>

<pre>
  cvs update <i>file</i>
</pre>

    <p>You can also update to a specific version, just as you could check out
      a specific version.</p>

<pre>
  cvs update -d -P -r release1_p5
</pre>

    <p>If you checked out a specific version and want to update to the very
      latest use the -A option will remove associated with a specific version as
      follows:</p>

<pre>
  cvs update -d -P -A
</pre>

    <p>"cvs update" produces output to the terminal with the following
      meanings:</p>
    
    <table align="center" border="0" cellpadding="10" width="90%" summary="CVS
      update codes">
      <tr bgcolor="#00cccc">
        <td width="20%">Return Code</td>
        <td>Description</td>
      </tr>
      <tr bgcolor="#bbffdd">
        <td width="20%">U <i>file</i></td>
        <td>indicates that <i>file</i> was brought up to date with the
          repository or that it exists in the repository but not in your work
          space</td>
      </tr>
      <tr bgcolor="#bbddff">
        <td width="20%">P <i>file</td>
        <td>does exactly as above but uses the "patch" method</td>
      </tr>
      <tr bgcolor="#bbffdd">
        <td width="20%">M <i>file</i></td>
        <td>means the <i>file</i> was modified in your work space. Any
          additional changes from the repository were merged in
          successfully</td>
      </tr>
     </tr>
      <tr bgcolor="#bbddff">
        <td width="20%">C <i>file</i></td>
        <td>means a merge is necessary because both the your copy and the
          repository have changed <b>but</b> there is a conflict between the
          changes</td>
      </tr>
      <tr bgcolor="#bbffdd">
        <td width="20%">? <i>file</i></td>
        <td>means the file exists in your work space but not on the
          repository</td>
      </tr>
    </table>

    <p>When conflicts arise, the sections of code are both kept and surrounded
      by &lt;&lt;&lt;&lt;&lt;, ===== and >>>>> indicators. You need to examine
      these lines of the files and resolve the conflict.</p>

    <h4>Wow! CVS is so good, where can I learn more?</h4>

    <p>The <a 
      href="http://web.mit.edu/afs/athena.mit.edu/project/gnu/doc/html/cvs_toc.html">basic 
      manual</a> is a good reference.
      For those who prefer the good old fashioned book there's
      <a href="http://cvsbook.red-bean.com/">"Open Source Development With CVS"</a>.</p>

  </body>
</html>

1	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
4	<html xmlns="http://www.w3.org/1999/xhtml">
5	<head>
6	<meta name="generator" content="HTML Tidy, see www.w3.org" />
7	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
8	<base href="http:/mitgcm.org" />
9
10	<!-- Hinting for menu generation -->
11	<meta name="add_name_0" content="Source Code" />
12	<meta name="add_name_1" content="Using CVS" />
13	<meta name="add_name_2" content="" />
14	<meta name="add_title" content="Using CVS" />
15	<!-- Hinting for menu generation -->
16
17	<style type="text/css">
18	span.c2 {font-size: 110%}
19	div.c1 {text-align: center}
20	</style>
21	</head>
22
23	<body>
24
25	<center>
26	<h3>Obtaining the MITgcm Source using CVS</h3>
27	</center>
28
29	<h4>Using CVS "pserver" for Anonymous Access</h4>
30
31	<p>The most convenient way to get local copies of the MITgcm source code is
32	to use the CVS "pserver" mechanism. This method only allows you to "check
33	out" (or obtain a local copy) of the source. It does not provide a
34	mechanism for "committing" or "checking in" changes (please see below).
35	Using CVS pserver from the command line requires just a three commands.
36	Using a Bourne, "bash", or "sh-compatible" shell they are:</p>
37
38	<pre>
39	$ export CVSROOT=':pserver:cvsanon@mitgcm.org:/u/gcmpack'
40	$ cvs login
41	( enter the CVS password: "cvsanon" )
42	$ cvs co MITgcm
43	</pre>
44
45	<p>Using a "C", "csh", or "tcsh" shell the commands are:</p>
46
47	<pre>
48	$ setenv CVSROOT ':pserver:cvsanon@mitgcm.org:/u/gcmpack'
49	$ cvs login
50	( enter the CVS password: "cvsanon" )
51	$ cvs co MITgcm
52	</pre>
53
54	<p>A large amount of additional (optional!) content can be obtained from the
55	MITgcm_contrib directory that can be checked out using:
56
57	<pre>
58	$ cvs co MITgcm_contrib
59	</pre>
60
61	In general, we do not recommend checking out all of MITgcm_contrib since
62	it takes a long time to download (particularly from remote locations) and
63	much of it is specific to certain setups (eg. high-res setups,
64	in-development material that is not yet part of the "main" code,
65	etc.).</p>
66
67	<p>Note that you will only need to perform the "cvs login" once. And for
68	convenience, you may want to add the CVSROOT variable to your shell's
69	environment (that is, define it within your "~/.bashrc" or "~/.chsrc"
70	files).</p>
71
72
73	<h4>Getting Parts of the Source "Tree"</h4>
74
75	<p>The above commands demonstrate how to check out all of the MITgcm code
76	and the "contributed" (that is, unsupported by occasionally useful)
77	information within the "MITgcm_contrib" directory. In many cases, this is
78	overkill and can result in long download times. To reduce the volume of
79	information downloaded and thereby speedup the download times, one can
80	select one of the following pre-defined "aliases" that will provide a
81	sub-set of the entire MITgcm source "tree":</p>
82
83	<table align="center" border="0" cellpadding="10" width="90%" summary="CVS
84	aliases">
85	<tr bgcolor="#00cccc">
86	<td width="25%">Alias Name</td>
87	<td>Information (directories) Contained</td>
88	</tr>
89	<tr bgcolor="#bbffdd">
90	<td width="25%">MITgcm_code</td>
91	<td>Only the source code -- none of the verification examples.</td>
92	</tr>
93	<tr bgcolor="#bbddff">
94	<td width="25%">MITgcm_verif_basic</td>
95	<td>Source code plus a small set of the verification examples
96	("aim.5l_cs", "hs94.128x64x5", "ideal_2D_oce", "lab_sea",
97	"tutorial_baroclinic_gyre", "tutorial_global_oce_latlon"
98	and "tutorial_plume_on_slope").</td>
99	</tr>
100	<tr bgcolor="#bbffdd">
101	<td width="25%">MITgcm_tutorials</td>
102	<td>Source code plus all of the tutorials examples.</td>
103	</tr>
104	<tr bgcolor="#bbddff">
105	<td width="25%">MITgcm_verif_all</td>
106	<td>Source code plus all of the verification examples.</td>
107	</tr>
108	<!--
109	<tr bgcolor="#bbffdd">
110	<td width="25%">MITgcm_verif_atmos</td>
111	<td>Source code plus all of the atmospheric examples.</td>
112	</tr>
113	<tr bgcolor="#bbddff">
114	<td width="25%">MITgcm_verif_ocean</td>
115	<td>Source code plus all of the oceanic examples.</td>
116	</tr>
117	<tr bgcolor="#bbddff">
118	<td width="25%"></td>
119	<td></td>
120	</tr>
121	<tr bgcolor="#bbffdd">
122	<td width="25%"></td>
123	<td></td>
124	</tr>
125	-->
126	</table>
127
128	<p>It is important to note that the CVS aliases above cannot be used in
129	conjunction with the CVS <i>-d DIRNAME</i> option. However, the MITgcm
130	directories they create can be changed to a different name following the
131	check-out:</p>
132	<pre>
133	$ cvs co MITgcm_verif_basic
134	$ mv MITgcm MITgcm_verif_basic
135	</pre>
136
137	<h4>Getting Specific Releases or "Checkpoints"</h4>
138
139	<p>As shown within the
140	<!-- <a href="http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index">CVS Code Browser</a> -->
141	<a href="http://mitgcm.org/viewvc/MITgcm/MITgcm/doc/tag-index">CVS Code Browser</a>
142	, the MITgcm code is continuously undergoing updates. At
143	points during the development (typically, after work has been done and the
144	source code has passed the <a href="./testing.html">verification
145	tests</a>), a release or checkpoint "tag" is created. These tags are a
146	convenient mechanism for referring to different times or points within the
147	development. One can check out these versions using the "-r TAG_NAME" CVS
148	option such as: </p>
149
150	<pre>
151	$ cvs co -r release1_p5 MITgcm
152	$ cvs co -r checkpoint52a_post MITgcm
153	</pre>
154
155	<p>By default (that is, when no tag is specified), CVS will retrieve the
156	latest version of all files.</p>
157
158
159	<h4>Show changes that YOU have made</h4>
160
161	<p>If you are running into difficulties it is very useful to see the changes
162	that you yourself have made since obtaining the code. From within
163	your working directory:</p>
164
165	<pre>
166	cvs diff
167	</pre>
168
169
170	<p>will show the differences between your version and the version that you
171	checked out. It acts recursively on all directories below your current
172	directory. You can limit the operation to just one file or directory by
173	specifying those as arguments:</p>
174
175	<pre>
176	cvs diff <i>file</i>
177	</pre>
178
179
180	<h4>Show changes to the repository that you don't have</h4>
181
182	<p>The source code evolves continuously and you should try to stay up to
183	date. To see what needs to be updated:</p>
184
185	<pre>
186	cvs -n update
187	</pre>
188
189	<p>behaves just as "cvs update" but doesn't actually change anything. This
190	is a useful way of summarizing the state of your code. The meaning of the
191	output is summarized in the next topic.</p>
192
193	<h4>Getting updates from the repository</h4>
194
195	<p>You can download and merge updates from the repository to bring you
196	working code up to date:</p>
197
198	<pre>
199	cvs update -d -P
200	</pre>
201
202	<p>will work recursively on all files in the current directory and below.
203	To update just a specific file or directory:</p>
204
205	<pre>
206	cvs update <i>file</i>
207	</pre>
208
209	<p>You can also update to a specific version, just as you could check out
210	a specific version.</p>
211
212	<pre>
213	cvs update -d -P -r release1_p5
214	</pre>
215
216	<p>If you checked out a specific version and want to update to the very
217	latest use the -A option will remove associated with a specific version as
218	follows:</p>
219
220	<pre>
221	cvs update -d -P -A
222	</pre>
223
224	<p>"cvs update" produces output to the terminal with the following
225	meanings:</p>
226
227	<table align="center" border="0" cellpadding="10" width="90%" summary="CVS
228	update codes">
229	<tr bgcolor="#00cccc">
230	<td width="20%">Return Code</td>
231	<td>Description</td>
232	</tr>
233	<tr bgcolor="#bbffdd">
234	<td width="20%">U <i>file</i></td>
235	<td>indicates that <i>file</i> was brought up to date with the
236	repository or that it exists in the repository but not in your work
237	space</td>
238	</tr>
239	<tr bgcolor="#bbddff">
240	<td width="20%">P <i>file</td>
241	<td>does exactly as above but uses the "patch" method</td>
242	</tr>
243	<tr bgcolor="#bbffdd">
244	<td width="20%">M <i>file</i></td>
245	<td>means the <i>file</i> was modified in your work space. Any
246	additional changes from the repository were merged in
247	successfully</td>
248	</tr>
249	</tr>
250	<tr bgcolor="#bbddff">
251	<td width="20%">C <i>file</i></td>
252	<td>means a merge is necessary because both the your copy and the
253	repository have changed <b>but</b> there is a conflict between the
254	changes</td>
255	</tr>
256	<tr bgcolor="#bbffdd">
257	<td width="20%">? <i>file</i></td>
258	<td>means the file exists in your work space but not on the
259	repository</td>
260	</tr>
261	</table>
262
263	<p>When conflicts arise, the sections of code are both kept and surrounded
264	by <<<<<, ===== and >>>>> indicators. You need to examine
265	these lines of the files and resolve the conflict.</p>
266
267	<h4>Wow! CVS is so good, where can I learn more?</h4>
268
269	<p>The <a
270	href="http://web.mit.edu/afs/athena.mit.edu/project/gnu/doc/html/cvs_toc.html">basic
271	manual</a> is a good reference.
272	For those who prefer the good old fashioned book there's
273	<a href="http://cvsbook.red-bean.com/">"Open Source Development With CVS"</a>.</p>
274
275	</body>
276	</html>
277