Return to USING_CVS CVS log

Jump to this file's LXR Page

Up to [CENS] / emstar

"a fascinating document" -- LA Times CVS Review
"two thumbs up" -- Broken Build Suicide Hotline
"i laughed.. then i couldn't stop crying" -- emstar-users mailing list

Subject: Information about using CVS
X-Mailer: mh-e 6.1; nmh 1.0.4+dev; Emacs 21.2
Date: Thu, 16 Sep 2004 15:08:54 -0700
From: Lewis Girod <girod@lecs.cs.ucla.edu>

you should be able to find info on cvs via "man cvs" and other sources on
the web.

To add a file,

  cvs add <filename> ...

When adding new source code to the emstar repository, it's a good idea
to add it to somewhere in the 'devel' directory, unless you are certain
about where it belongs in the main tree and that it's ready for release.
we are trying to keep the main tree very organized, which is difficult
with CVS because once defined, you cannot change directory structures.
thus we are only very carefully adding new directories to the main tree.
if you are in doubt, add it to devel.. we can always move it later into
the main tree

To commit changes you MUST first

  * update the repository, resolving any conflicts
  * if anything was patched, make sure it builds

    NOTE: if you are making changes to EmTOS, or moving files around, 
    it's a good idea to rm -rf obj.* to clear out any existing state 
    and get a fresh build.  EmTOS code does not automatically rebuild
    in the current make system.

  * check to see what you're about to commit by doing a cvs diff
  * then commit, and write a useful log message.
  * for total safety, do a clean checkout and rebuild from scratch
    to verify the build AFTER checkin

First, update to the latest revision:

  cvs update -d | less
  control-L

This will show all files you have modified with 'M', any files that
you have added with 'A', and any you have removed with 'R'.  Any files
that were patched from later versions in the repository will be marked
'P'.  Any files marked 'C' are conflicts and must be manually resolved
or deleted and re-updated.  

Pay special attention to '?' files -- these are files that exist in
your checkout that are not known to CVS.  If files that are needed for
the build are marked '?', it will break for other users.  Typically
these files are random junk you may have left lying around, output
files, and TinyOS build directories.  If you're sure that the files
are harmless, you can leave them, but if you're not sure, move them to
another location outside of the repo.  Or do a followup checkout after
you commit (described below).

If any patches or conflicts occurred during the update, resolve them
and make sure that your repository still builds before going on to
commit.  NOTE: If you are using EmTOS, be aware that it won't
automatically rebuild EmTOS images.  So, if your changes might have
changed a library inside TOS, please rm -rf obj.* and make sure your
repo builds clean.

After it builds, do a cvs diff to find out what changes you will be
committing:

  cvs diff | less
  control-L

This will show you all the changes you are about to commit.  once you
are sure you want to commit them, then do the cvs commit.  If there are
a lot of changes, it's goot to take some notes about that changed so that
you can create a good log message.

Finally, after updating, building, and diffing, you can commit:

  cvs commit <filename> ...

You can commit on individual files, or directories.  If you commit on a
directory it will process directories recursively.  When you commit, it
will ask you to write a log message that describes the nature of the
changes you are committing.

For extreme safety, when you have made lots of changes or done unusual
things like moved files around or added lots of files, it's sometimes 
a good idea to do a followup checkout of a clean repo and rebuild from 
scratch.  Be sure the enable BUILD_EMTOS.  This will ensure that other
users who do a clean checkout will get all the files they need to build
(e.g. that your repo doesn't have any files that make it work only for
you).  


=====================================================================
=====================================================================
=====================================================================

A note on CVS orderliness
-------------------------

One of the drawbacks to CVS is that moving/renaming and deleting
directories is not generally possible.  For this reason we try to
commit experimental stuff into devel/ (a big sandbox for new projects)
and the migrate it to the main tree after it is more mature.

CVS Administrators can move or rename these files while keeping
complete revision history.  The procedure is to copy the files to
their new locations on the server, and then cvs remove the originals
via normal CVS.

It is also possible to rename or remove directories from the CVS
server so that empty directories are not left sitting around.
However, this should only be done in extreme cases, and when no tags
will break.  Thus if a directory is checked in accidentally, it's OK
to immediately delete it.  The other times when this is OK are left to
the judgement of administrators -- but generally this should be
avoided if it will break important tags, or if it doesn't involve
whole directories.  In general, it should not be done.