Code Maintenance with Revision Control System

 

• Manage multiple revisions files:
  • store, retrieve, log, identify, and merge revisions
  • use for frequently revised text:
    • programs, documentation, graphics, papers, form letters, WWW pages
• Simple user interface:

  ci

  check in RCS revisions 

  co

  check out RCS revisions 

A simple use of RCS:

• Create a subdirectory RCS in the directory in which you have saved the module file euler.f90.
• Edit the module file as follows:

  1.

  Right at the beginning of the file, even before the word module insert the following:

  ! $Id$
  ! $Log$
  

  RCS will convert $Id$  into an identification string, and it will convert $Log$  into a history of edits. The text generated automatically by RCS will be commented out using F90 comment character, !. RCS knows about F90 files.

  2.

  After the statement contains insert the following definition:

    subroutine euler_version()
       write(*,*) '$Id$'
    end subroutine euler_version
  

• Having saved the changes check the module file into the RCS system with the command:

  $ ci euler.f90
  

  RCS will respond with something like:

  RCS/euler.f90,v  <--  euler.f90
  new revision: 1.4; previous revision: 1.3
  enter log message, terminated with single '.' or end of file:
  >>
  

  Enter a string that describes this version, e.g., ``Initial Revision'', go to the next line and terminate it with a single dot in the first column. Press return again.
• The file will vanish from your directory, but a new file called euler.f90,v will appear in the RCS directory.
• To check out the file, i.e., to get it back into your source directory, issue the command:

  $ co euler.f90
  

• Observe the way RCS will have expanded on your abbreviations: $Id$ and $Log$.

I have gone through 4 revisions of euler.f90 and this is what the top of my module source file looks like now:

! $Id: euler.f90,v 1.4 1998/09/28 22:55:49 gustav Exp $
! $Log: euler.f90,v $
! Revision 1.4  1998/09/28 22:55:49  gustav
! changed the name of subroutine "version" to "euler_version"
!
! Revision 1.3  1998/09/28 22:43:18  gustav
! Deleted the definition of rcsid and added a verbatim write in
! subroutine "version" instead.
!
! Revision 1.2  1998/09/28 22:40:16  gustav
! Added the definition of subroutine version
!
! Revision 1.1  1998/09/28 22:10:09  gustav
! Initial revision
!

module euler

  integer, parameter :: long = selected_real_kind(9,99)

contains

  subroutine euler_version()
     write(*,*) '$Id: euler.f90,v 1.4 1998/09/28 22:55:49 gustav Exp $'
  end subroutine euler_version

  real(kind=long) function goodness(a, x)
    real (kind=long), intent(in) :: a, x

...

• Recompile program chi:

  gustav@blanc:../src 18:05:00 !939 $ make -f Makefile.chi clobber
  rm -f *.o *.M core
  rm -f chi
  gustav@blanc:../src 18:08:01 !940 $ make -f Makefile.chi
  f90 -g -c euler.f90
  f90 -g -c chi.f90
  f90 -g -o chi chi.o euler.o
  gustav@blanc:../src 18:08:15 !941 $
  

• Now observe the following: 

  gustav@blanc:../src 18:08:15 !941 $ ident chi
  chi:
       $Id: euler.f90,v 1.4 1998/09/28 22:55:49 gustav Exp $
  gustav@blanc:../src 18:08:54 !942 $ ident euler.o
  euler.o:
       $Id: euler.f90,v 1.4 1998/09/28 22:55:49 gustav Exp $
  gustav@blanc:../src 18:08:57 !943 $
  

• The RCS command ident searches the binary, this works both with the linked binary and with the object file, and retrieves the Id string that is explicitly embedded in the write statement of subroutine euler_version.
• We never have to call that subroutine explicitly in order to find about the version of module euler that program chi has been linked with.

• To edit the file, once it's been checked in, check it out with locking: 

  gustav@blanc:../src 17:55:03 !927 $ co -l euler.f90
  

• To check what changes you've made to the file since the last time it's been checked in with RCS, issue the command: 

  gustav@blanc:../src 17:55:27 !928 $ rcsdiff euler.f90
  

• After you've made the changes, you should check the file back in with:

  gustav@blanc:../src 17:55:44 !929 $ ci euler.f90
  RCS/euler.f90,v  <--  euler.f90
  new revision: 1.4; previous revision: 1.3
  enter log message, terminated with single '.' or end of file:
  >> changed the name of subroutine "version" to "euler_version"
  >> .
  done
  gustav@blanc:../src 17:56:04 !930 $
  

• If you haven't locked the file yourself and try to check it in, you'll get the following error message:

  ci error: no lock set by gustav
  

  Locking ensures that while the file is out you're the only person that can make changes to it and check them back in.

• If you have read only versions of your .f90 files, i.e., versions that have been checked out without locking you can clean them away with: 

  gustav@blanc:../src 18:28:23 !945 $ ls -l euler.f90 
  -r--r--r--   1 gustav   ovpit        5626 Sep 28 17:56 euler.f90
  gustav@blanc:../src 18:28:29 !946 $ rcsclean
  rm -f euler.f90
  gustav@blanc:../src 18:28:35 !947 $ ls -l euler.f90
  ls: euler.f90: No such file or directory
  gustav@blanc:../src 18:28:40 !948 $
  

• GNU make knows about RCS . If it does not find file euler.f90 in its working directory, but detects an RCS directory with euler.f90,v in it, it will check that file out automatically:

  gustav@blanc:../src 18:28:40 !948 $ make -f Makefile.chi
  co  RCS/euler.f90,v euler.f90
  RCS/euler.f90,v  -->  euler.f90
  revision 1.4
  done
  f90 -g -c euler.f90
  f90 -g -c chi.f90
  f90 -g -o chi chi.o euler.o
  gustav@blanc:../src 18:29:03 !949 $
  

• In order to retrieve an earlier revision of the code use the -r option when calling co and specify the revision you want: 

  gustav@blanc:../src 18:37:47 !952 $ co -r1.2 euler.f90
  RCS/euler.f90,v  -->  euler.f90
  revision 1.2
  done
  gustav@blanc:../src 18:38:01 !953 $ head -5 euler.f90
  ! $Id: euler.f90,v 1.2 1998/09/28 22:40:16 gustav Exp $
  ! $Log: euler.f90,v $
  ! Revision 1.2  1998/09/28 22:40:16  gustav
  ! Added the definition of subroutine version
  !
  gustav@blanc:../src 18:39:25 !954 $
  

  Compare this with:

  gustav@blanc:../src 18:39:25 !954 $ rcsclean
  gustav@blanc:../src 18:40:01 !955 $ co euler.f90
  RCS/euler.f90,v  -->  euler.f90
  revision 1.4
  done
  gustav@blanc:../src 18:40:06 !956 $ head -5 euler.f90
  ! $Id: euler.f90,v 1.4 1998/09/28 22:55:49 gustav Exp $
  ! $Log: euler.f90,v $
  ! Revision 1.4  1998/09/28 22:55:49  gustav
  ! changed the name of subroutine "version" to "euler_version"
  !
  gustav@blanc:../src 18:40:10 !957 $
  

• You can accomplish many other wondrous deeds with RCS, but you don't have to: ci, co, ident, rcsdiff, and rcsclean are quite sufficient for every-day use.
• There are detailed man entries describing the whole RCS system. See rcsintro(1), ci(1), co(1), ident(1), rcs(1), rcsdiff(1), rcsintro(1), rcsmerge(1), rlog(1), and rcsfile(5) for more information.