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 -P 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 -P MITgcm
</pre>

    <p>using the "-P" option to check-out ("<i>cvs co -P</i>") prevents
    to download unnecessary empty directories.</p>
    
    <p>A large amount of additional (optional!) content is available
    from the <i>MITgcm_contrib</i> directory; 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 ...).
    But rather than checking out the full content of MITgcm_contrib
    ("<i>cvs co -P MITgcm_contrib</i>"), which takes a long time to download
    (particularly from remote locations), we recommend to download only the
    specific part of interest, e.g.: "<i>submesoscale</i>" directory,
    which can be checked out using:</p>

<pre>
  $ cvs co -P MITgcm_contrib/submesoscale
</pre>

    <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>

    <p>Also note that it is possible to checkout code without "cvs login" and
      without setting any shell environment variables by specifying the
      pserver name and password in one line, for example:</p>

<pre>
  $ cvs -d :pserver:cvsanon:cvsanon@mitgcm.org:/u/gcmpack co -P MITgcm
</pre>

    <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 but occasionally useful)
      information within the "<i>MITgcm_contrib</i>" 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 -P 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 -P -r release1_p5 MITgcm
  $ cvs co -P -r checkpoint52a_post MITgcm
</pre>

    <p>By default (that is, when no tag is specified), CVS will retrieve the
      latest version of all files. To download an older version corresponding
      to a specific time, e.g., May 1rst, 2008, at 5pm, one can use the "-D"
      CVS option as follows: </p>

<pre>
  $ cvs co -P -D "2008-05-01 17:00" MITgcm
</pre>

    <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	edhill	1.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	jmc	1.15
25	edhill	1.1	<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	edhill	1.3	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	jmc	1.14
38	edhill	1.1	<pre>
39	edhill	1.3	$ export CVSROOT=':pserver:cvsanon@mitgcm.org:/u/gcmpack'
40	jmc	1.14	$ cvs login
41	edhill	1.3	( enter the CVS password: "cvsanon" )
42	jmc	1.14	$ cvs co -P MITgcm
43	edhill	1.3	</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	jmc	1.14	$ cvs co -P MITgcm
52	edhill	1.9	</pre>
53
54	jmc	1.14	<p>using the "-P" option to check-out ("<i>cvs co -P</i>") prevents
55			to download unnecessary empty directories.</p>
56	dimitri	1.16
57	jmc	1.14	<p>A large amount of additional (optional!) content is available
58			from the <i>MITgcm_contrib</i> directory; much of it is specific to certain
59			setups (eg. high-res setups, in-development material that is not yet part
60			of the "main" code, etc ...).
61			But rather than checking out the full content of MITgcm_contrib
62			("<i>cvs co -P MITgcm_contrib</i>"), which takes a long time to download
63			(particularly from remote locations), we recommend to download only the
64			specific part of interest, e.g.: "<i>submesoscale</i>" directory,
65			which can be checked out using:</p>
66	edhill	1.9
67			<pre>
68	jmc	1.14	$ cvs co -P MITgcm_contrib/submesoscale
69	edhill	1.9	</pre>
70
71	edhill	1.1	<p>Note that you will only need to perform the "cvs login" once. And for
72			convenience, you may want to add the CVSROOT variable to your shell's
73			environment (that is, define it within your "~/.bashrc" or "~/.chsrc"
74			files).</p>
75
76	dimitri	1.17	<p>Also note that it is possible to checkout code without "cvs login" and
77			without setting any shell environment variables by specifying the
78			pserver name and password in one line, for example:</p>
79
80			<pre>
81			$ cvs -d :pserver:cvsanon:cvsanon@mitgcm.org:/u/gcmpack co -P MITgcm
82			</pre>
83	edhill	1.1
84			<h4>Getting Parts of the Source "Tree"</h4>
85
86			<p>The above commands demonstrate how to check out all of the MITgcm code
87	jmc	1.14	and the "contributed" (that is, unsupported but occasionally useful)
88			information within the "<i>MITgcm_contrib</i>" directory. In many cases,
89			this is overkill and can result in long download times.
90			To reduce the volume of information downloaded and thereby speedup the
91			download times, one can select one of the following pre-defined "aliases"
92			that will provide a sub-set of the entire MITgcm source "tree":</p>
93	edhill	1.1
94			<table align="center" border="0" cellpadding="10" width="90%" summary="CVS
95			aliases">
96			<tr bgcolor="#00cccc">
97			<td width="25%">Alias Name</td>
98			<td>Information (directories) Contained</td>
99			</tr>
100			<tr bgcolor="#bbffdd">
101			<td width="25%">MITgcm_code</td>
102			<td>Only the source code -- none of the verification examples.</td>
103			</tr>
104			<tr bgcolor="#bbddff">
105			<td width="25%">MITgcm_verif_basic</td>
106	edhill	1.2	<td>Source code plus a small set of the verification examples
107	jmc	1.11	("aim.5l_cs", "hs94.128x64x5", "ideal_2D_oce", "lab_sea",
108			"tutorial_baroclinic_gyre", "tutorial_global_oce_latlon"
109			and "tutorial_plume_on_slope").</td>
110			</tr>
111			<tr bgcolor="#bbffdd">
112			<td width="25%">MITgcm_tutorials</td>
113			<td>Source code plus all of the tutorials examples.</td>
114			</tr>
115			<tr bgcolor="#bbddff">
116			<td width="25%">MITgcm_verif_all</td>
117			<td>Source code plus all of the verification examples.</td>
118			</tr>
119			<!--
120	edhill	1.1	<tr bgcolor="#bbffdd">
121			<td width="25%">MITgcm_verif_atmos</td>
122			<td>Source code plus all of the atmospheric examples.</td>
123			</tr>
124			<tr bgcolor="#bbddff">
125			<td width="25%">MITgcm_verif_ocean</td>
126			<td>Source code plus all of the oceanic examples.</td>
127			</tr>
128			<tr bgcolor="#bbddff">
129			<td width="25%"></td>
130			<td></td>
131			</tr>
132			<tr bgcolor="#bbffdd">
133			<td width="25%"></td>
134			<td></td>
135			</tr>
136			-->
137			</table>
138
139	edhill	1.6	<p>It is important to note that the CVS aliases above cannot be used in
140	edhill	1.7	conjunction with the CVS <i>-d DIRNAME</i> option. However, the MITgcm
141	edhill	1.6	directories they create can be changed to a different name following the
142			check-out:</p>
143			<pre>
144	jmc	1.14	$ cvs co -P MITgcm_verif_basic
145	edhill	1.6	$ mv MITgcm MITgcm_verif_basic
146			</pre>
147	edhill	1.1
148			<h4>Getting Specific Releases or "Checkpoints"</h4>
149	jmc	1.15
150			<p>As shown within the
151	jmc	1.12	<!-- <a href="http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index">CVS Code Browser</a> -->
152			<a href="http://mitgcm.org/viewvc/MITgcm/MITgcm/doc/tag-index">CVS Code Browser</a>
153			, the MITgcm code is continuously undergoing updates. At
154	edhill	1.1	points during the development (typically, after work has been done and the
155	jmc	1.12	source code has passed the <a href="./testing.html">verification
156	edhill	1.1	tests</a>), a release or checkpoint "tag" is created. These tags are a
157			convenient mechanism for referring to different times or points within the
158			development. One can check out these versions using the "-r TAG_NAME" CVS
159			option such as: </p>
160
161			<pre>
162	jmc	1.14	$ cvs co -P -r release1_p5 MITgcm
163			$ cvs co -P -r checkpoint52a_post MITgcm
164	edhill	1.1	</pre>
165
166			<p>By default (that is, when no tag is specified), CVS will retrieve the
167	jmc	1.15	latest version of all files. To download an older version corresponding
168			to a specific time, e.g., May 1rst, 2008, at 5pm, one can use the "-D"
169			CVS option as follows: </p>
170	edhill	1.1
171	jmc	1.15	<pre>
172			$ cvs co -P -D "2008-05-01 17:00" MITgcm
173			</pre>
174	edhill	1.1
175			<h4>Show changes that YOU have made</h4>
176
177			<p>If you are running into difficulties it is very useful to see the changes
178			that you yourself have made since obtaining the code. From within
179			your working directory:</p>
180
181	edhill	1.3	<pre>
182			cvs diff
183			</pre>
184
185	edhill	1.1
186			<p>will show the differences between your version and the version that you
187			checked out. It acts recursively on all directories below your current
188			directory. You can limit the operation to just one file or directory by
189			specifying those as arguments:</p>
190
191	edhill	1.3	<pre>
192			cvs diff <i>file</i>
193			</pre>
194
195	edhill	1.1
196			<h4>Show changes to the repository that you don't have</h4>
197
198			<p>The source code evolves continuously and you should try to stay up to
199			date. To see what needs to be updated:</p>
200
201	edhill	1.3	<pre>
202			cvs -n update
203			</pre>
204	edhill	1.1
205			<p>behaves just as "cvs update" but doesn't actually change anything. This
206			is a useful way of summarizing the state of your code. The meaning of the
207			output is summarized in the next topic.</p>
208
209			<h4>Getting updates from the repository</h4>
210
211			<p>You can download and merge updates from the repository to bring you
212			working code up to date:</p>
213
214	edhill	1.3	<pre>
215			cvs update -d -P
216			</pre>
217	edhill	1.1
218			<p>will work recursively on all files in the current directory and below.
219			To update just a specific file or directory:</p>
220
221	edhill	1.3	<pre>
222			cvs update <i>file</i>
223			</pre>
224	edhill	1.1
225			<p>You can also update to a specific version, just as you could check out
226			a specific version.</p>
227
228	edhill	1.3	<pre>
229			cvs update -d -P -r release1_p5
230			</pre>
231	edhill	1.1
232			<p>If you checked out a specific version and want to update to the very
233			latest use the -A option will remove associated with a specific version as
234			follows:</p>
235
236	edhill	1.3	<pre>
237			cvs update -d -P -A
238			</pre>
239	edhill	1.1
240			<p>"cvs update" produces output to the terminal with the following
241			meanings:</p>
242	jmc	1.15
243	edhill	1.1	<table align="center" border="0" cellpadding="10" width="90%" summary="CVS
244			update codes">
245			<tr bgcolor="#00cccc">
246			<td width="20%">Return Code</td>
247			<td>Description</td>
248			</tr>
249			<tr bgcolor="#bbffdd">
250			<td width="20%">U <i>file</i></td>
251			<td>indicates that <i>file</i> was brought up to date with the
252			repository or that it exists in the repository but not in your work
253			space</td>
254			</tr>
255			<tr bgcolor="#bbddff">
256			<td width="20%">P <i>file</td>
257			<td>does exactly as above but uses the "patch" method</td>
258			</tr>
259			<tr bgcolor="#bbffdd">
260			<td width="20%">M <i>file</i></td>
261			<td>means the <i>file</i> was modified in your work space. Any
262			additional changes from the repository were merged in
263			successfully</td>
264			</tr>
265			</tr>
266			<tr bgcolor="#bbddff">
267			<td width="20%">C <i>file</i></td>
268			<td>means a merge is necessary because both the your copy and the
269			repository have changed <b>but</b> there is a conflict between the
270			changes</td>
271			</tr>
272			<tr bgcolor="#bbffdd">
273			<td width="20%">? <i>file</i></td>
274			<td>means the file exists in your work space but not on the
275			repository</td>
276			</tr>
277			</table>
278
279			<p>When conflicts arise, the sections of code are both kept and surrounded
280			by <<<<<, ===== and >>>>> indicators. You need to examine
281			these lines of the files and resolve the conflict.</p>
282
283			<h4>Wow! CVS is so good, where can I learn more?</h4>
284
285	jmc	1.15	<p>The <a
286			href="http://web.mit.edu/afs/athena.mit.edu/project/gnu/doc/html/cvs_toc.html">basic
287	jmc	1.13	manual</a> is a good reference.
288			For those who prefer the good old fashioned book there's
289			<a href="http://cvsbook.red-bean.com/">"Open Source Development With CVS"</a>.</p>
290	edhill	1.1
291			</body>
292			</html>
293