Re: import

[Greg A. Woods]

[ On Wednesday, July 4, 2001 at 20:15:25 (+0530), kamesh jayachandran wrote: ]
> Subject: import 
>
> I am much interested in knowing the general guidelines in starting the
> real time project not just the example on cvs import.

Apply the attached patch to the documentation and read the resulting
section "Setting up the files", etc.

(I've asked anyone with commit access to check this in, but so far I've
not seen it done....)

-- 
                                                        Greg A. Woods

+1 416 218-0098      VE3TCP      <address@hidden>     <address@hidden>
Planix, Inc. <address@hidden>;   Secrets of the Weird <address@hidden>


Index: cvs.texinfo
===================================================================
RCS file: /home2/cvsroot/ccvs/doc/cvs.texinfo,v
retrieving revision 1.505
diff -c -c -r1.505 cvs.texinfo
*** cvs.texinfo 18 Jan 2001 19:52:49 -0000      1.505
--- cvs.texinfo 4 Jul 2001 17:30:39 -0000
***************
*** 40,46 ****
  @setfilename cvs.info
  @include CVSvn.texi
  @settitle CVS---Concurrent Versions System address@hidden
! @setchapternewpage odd
  
  @c -- TODO list:
  @c -- Fix all lines that match "address@hidden -- "
--- 40,46 ----
  @setfilename cvs.info
  @include CVSvn.texi
  @settitle CVS---Concurrent Versions System address@hidden
! @c @setchapternewpage odd
  
  @c -- TODO list:
  @c -- Fix all lines that match "address@hidden -- "
***************
*** 2925,2954 ****
  @node Setting up the files
  @section Setting up the files
  
! The first step is to create the files inside the repository.  This can
! be done in a couple of different ways.
  
  @c -- The contributed scripts
  @menu
  * From files::                  This method is useful with old projects
                                  where files already exists.
  * From other version control systems::  Old projects where you want to
!                                         preserve history from another system.
! * From scratch::                Creating a directory tree from scratch.
  @end menu
  
  @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  @node From files
! @subsection Creating a directory tree from a number of files
! @cindex Importing files
  
! When you begin using @sc{cvs}, you will probably already have several
! projects that can be
! put under @sc{cvs} control.  In these cases the easiest way is to use the
! @code{import} command.  An example is probably the easiest way to
! explain how to use it.  If the files you want to install in
! @sc{cvs} reside in @address@hidden, and you want them to appear in the
! repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this:
  
  @example
  $ cd @var{wdir}
--- 2925,3072 ----
  @node Setting up the files
  @section Setting up the files
  
! The first step is to create the files inside the
! repository.  This can be done in a couple of different
! ways, depending on what you might have to start with.
  
  @c -- The contributed scripts
  @menu
+ * From scratch::                Creating a directory tree from scratch.
  * From files::                  This method is useful with old projects
                                  where files already exists.
+ * From third-party projects::   This method is useful with third-party,
+                                 or vendor-manged files.
  * From other version control systems::  Old projects where you want to
!                                         preserve existing revision history
!                                         from another system.
  @end menu
  
  @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+ @node From scratch
+ @subsection Creating a directory tree from scratch
+ @cindex Creating a module from scratch
+ 
+ For a new project, the easiest and best thing to do is
+ start with an empty temporary directory and use the
+ @code{import} command to create the corresponding
+ (empty) directory inside the repository:
+ 
+ @example
+ $ mkdir junk
+ $ cd junk
+ $ cvs import -m "new directory for DIR" yoyodyne/@var{dir} yoyo start
+ $ cd ..
+ $ rmdir junk
+ @end example
+ 
+ Check that the permissions @sc{cvs} sets on the
+ directories inside @code{$CVSROOT} are reasonable.
+ You'll generally want the directory to be mode 0775,
+ and owned by the Unix group whos members are to have
+ commit privileges in this new directory.  In general
+ it's irrelevant which user owns the directories and
+ files so long as the directories are group-writable.
+ @xref{File permissions} for more detailed information.
+ 
+ You can now check out the project directory into a
+ working directory.  Note that since you hopefully have
+ specified @samp{checkout -P} in your @file{~/.cvsrc}
+ file (@pxref{~/.cvsrc}), you'll need to specify the
+ @samp{-f} option to prevent @sc{cvs} from immediately
+ removing the new, and empty, working directory:
+ 
+ @example
+ $ cd /work
+ $ cvs -f checkout -d @var{dir} yoyodyne/@var{dir}
+ @end example
+ 
+ If you first define a module (@xref{Defining the module})
+ then you can check out your new working directory using
+ just the module name:
+ 
+ @example
+ $ cd /work
+ $ cvs -f checkout @var{dir}
+ @end example
+ 
+ Now use @code{add} to add files (and new directories)
+ as they are created in your project.  Note that due to
+ a hard-to-fix ``bug'' you must be in the directory
+ where you add new files.
+ 
+ @example
+ $ cd /work
+ $ vi newfile.c
+ $ make test-newfile
+ $ cvs add newfile.c
+ $ cvs commit -m 'first working version' newfile.c
+ @end example
+ 
+ @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  @node From files
! @subsection Creating a directory tree for an existing project
! @cindex Creating a module from existing files
! 
! When you begin using @sc{cvs} you may already have
! several existing projects that can be put under
! @sc{cvs} control.  If the files are your own creation
! (i.e. they are not derived from changes made to files
! still primarily being maintained by some third party)
! then it's best to simply add them to a new project
! directory as if you were creating them from scratch.
! 
! Start by first creating an empty project as in the
! ``From scratch'' examples.  Then after creating a new
! empty working directory simply copy all of the files
! and directories from your existing project into this
! new working directory.  You should first clean out all
! generated files, of course, so that they won't be added
! to @sc{cvs}.
! 
! @example
! $ cd /work/oldprojectdir
! $ make maintainer-clean
! $ pax -rw . /work/@var{dir}
! @end example
! 
! Now go to the newly populated working directory and use
! @code{add} to add all the new files and directories to
! @sc{cvs} as if they were all just newly created.  If
! your project is large you might wish to use a little
! shell script you can type on the command-line to
! eliminate some of the repetitiveness (don't type the
! prompts):
! 
! @example
! $ cd /work/@var{dir}
! $ cvs add *
! $ for subdir in $(find . type d -print); do
! >> cd $subdir;
! >> cvs add *
! >> cd /work/@var{dir}
! >> done
! $ cvs commit -m 'initial commit to CVS'
! @end example
  
! @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
! @node From third-party projects
! @subsection Creating a directory tree for a third-party project
! @cindex Creating a module from a third-party project
! 
! If your project is actually a derivative of some
! third-party project -- i.e. where the local changes
! will be made to source code primarily managed by
! someone else, then you may want to create a
! vendor-branched project.  @xref{Tracking sources}, for
! more information about vendor-branched projects.
! 
! In these cases the easiest way is to use the
! @code{import} command, starting with the original
! third-party files.  An example is probably the easiest
! way to explain how to use it.  If the files you want to
! install in @sc{cvs} reside in @address@hidden, and
! you want them to appear in the repository as
! @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this:
  
  @example
  $ cd @var{wdir}
***************
*** 2958,2986 ****
  Unless you supply a log message with the @samp{-m}
  flag, @sc{cvs} starts an editor and prompts for a
  message.  The string @samp{yoyo} is a @dfn{vendor tag},
! and @samp{start} is a @dfn{release tag}.  They may fill
! no purpose in this context, but since @sc{cvs} requires
! them they must be present.  @xref{Tracking sources}, for
! more information about them.
! 
! You can now verify that it worked, and remove your
! original source directory.
! @c FIXME: Need to say more about "verify that it
! @c worked".  What should the user look for in the output
! @c from "diff -r"?
  
  @example
  $ cd ..
! $ cvs checkout yoyodyne/@var{rdir}       # @r{Explanation below}
! $ diff -r @var{wdir} yoyodyne/@var{rdir}
  $ rm -r @var{wdir}
  @end example
  
  @noindent
! Erasing the original sources is a good idea, to make sure that you do
! not accidentally edit them in @var{wdir}, bypassing @sc{cvs}.
! Of course, it would be wise to make sure that you have
! a backup of the sources before you remove them.
  
  The @code{checkout} command can either take a module
  name as argument (as it has done in all previous
--- 3076,3104 ----
  Unless you supply a log message with the @samp{-m}
  flag, @sc{cvs} starts an editor and prompts for a
  message.  The string @samp{yoyo} is a @dfn{vendor tag},
! and @samp{start} is a @dfn{release tag}.
! @xref{Tracking sources}, for more information about
! them.
! 
! You can now verify that it worked by checking it out,
! and then you can remove your original vendor source
! tree.
  
  @example
  $ cd ..
! $ cvs checkout -d @var{rdir} yoyodyne/@var{rdir}        # @r{Explanation 
below}
! $ diff -r @var{wdir} @var{rdir}
  $ rm -r @var{wdir}
  @end example
  
  @noindent
! Erasing the original sources is a good idea, to make
! sure that you do not accidentally edit them in
! @var{wdir}, bypassing @sc{cvs}.  Of course, it would be
! wise to make sure that you have a backup of the sources
! before you remove them.  You can keep a safe
! unmodifiable backup online if you just keep the
! original vendor distribution archive (@samp{tar} file).
  
  The @code{checkout} command can either take a module
  name as argument (as it has done in all previous
***************
*** 2992,3006 ****
  are reasonable, and that they belong to the proper
  groups.  @xref{File permissions}.
  
! If some of the files you want to import are binary, you
! may want to use the wrappers features to specify which
! files are binary and which are not.  @xref{Wrappers}.
  
  @c The node name is too long, but I am having trouble
  @c thinking of something more concise.
  @node From other version control systems
! @subsection Creating Files From Other Version Control Systems
! @cindex Importing files, from other version control systems
  
  If you have a project which you are maintaining with
  another version control system, such as @sc{rcs}, you
--- 3110,3125 ----
  are reasonable, and that they belong to the proper
  groups.  @xref{File permissions}.
  
! @c If some of the files you want to import are binary, you
! @c may want to use the wrappers features to specify which
! @c files are binary and which are not.  @xref{Wrappers}.
  
+ @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  @c The node name is too long, but I am having trouble
  @c thinking of something more concise.
  @node From other version control systems
! @subsection Importing Revision History From Other Version Control Systems
! @cindex other version control systems, Importing files from
  
  If you have a project which you are maintaining with
  another version control system, such as @sc{rcs}, you
***************
*** 3041,3052 ****
  @c an unlocked state.  Yet another reason for a separate
  @c "import RCS file" command.
  
- @c How many is "many"? Or do they just import RCS files?
  @item From another version control system
! Many version control systems have the ability to export
! @sc{rcs} files in the standard format.  If yours does,
! export the @sc{rcs} files and then follow the above
! instructions.
  
  Failing that, probably your best bet is to write a
  script that will check out the files one revision at a
--- 3160,3170 ----
  @c an unlocked state.  Yet another reason for a separate
  @c "import RCS file" command.
  
  @item From another version control system
! Some version control systems may have the ability to
! export @sc{rcs} files in the standard format.  If yours
! does, export to @sc{rcs} files and then follow the
! above instructions.
  
  Failing that, probably your best bet is to write a
  script that will check out the files one revision at a
***************
*** 3075,3080 ****
--- 3193,3199 ----
  else in contrib it is unsupported (your mileage may
  vary).  See the comments in the script for details.
  @end table
+ 
  @c CMZ and/or PATCHY were systems that were used in the
  @c high energy physics community (especially for
  @c CERNLIB).  CERN has replaced them with CVS, but the
***************
*** 3088,3131 ****
  @c See also:
  @c http://ecponion.cern.ch/ecpsa/cernlib.html
  
- @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
- @node From scratch
- @subsection Creating a directory tree from scratch
- 
- @c Also/instead should be documenting
- @c $ cvs co -l .
- @c $ mkdir tc
- @c $ cvs add tc
- @c $ cd tc
- @c $ mkdir man
- @c $ cvs add man
- @c etc.
- @c Using import to create the directories only is
- @c probably a somewhat confusing concept.
- For a new project, the easiest thing to do is probably
- to create an empty directory structure, like this:
- 
- @example
- $ mkdir tc
- $ mkdir tc/man
- $ mkdir tc/testing
- @end example
- 
- After that, you use the @code{import} command to create
- the corresponding (empty) directory structure inside
- the repository:
- 
- @example
- $ cd tc
- $ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start
- @end example
- 
- Then, use @code{add} to add files (and new directories)
- as they appear.
- 
- Check that the permissions @sc{cvs} sets on the
- directories inside @code{$CVSROOT} are reasonable.
- 
  @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  @node Defining the module
  @section Defining the module
--- 3207,3212 ----
***************
*** 3143,3152 ****
  
  @enumerate
  @item
! Get a working copy of the modules file.
  
  @example
! $ cvs checkout CVSROOT/modules
  $ cd CVSROOT
  @end example
  
--- 3224,3235 ----
  
  @enumerate
  @item
! Get a working copy of the @file{modules} file.  It is
! part of the basic @sc{cvs} administrative module called
! @samp{CVSROOT}.
  
  @example
! $ cvs checkout CVSROOT
  $ cd CVSROOT
  @end example
  
***************
*** 7626,7635 ****
  @file{~/.cvsrc} file:
  
  @example
  log -N
- diff -u
  update -P
- checkout -P
  @end example
  
  @noindent
--- 7709,7719 ----
  @file{~/.cvsrc} file:
  
  @example
+ checkout -P
+ diff -u -N
+ export -kv
  log -N
  update -P
  @end example
  
  @noindent
***************
*** 9872,9878 ****
  
  @item -f
  If no matching revision is found, retrieve the most
! recent revision (instead of ignoring the file).
  
  @item -l
  Local; don't descend subdirectories.
--- 9956,9965 ----
  
  @item -f
  If no matching revision is found, retrieve the most
! recent revision, i.e. the @samp{HEAD} revision (instead
! of ignoring the file).
! @c XXX: '-f' might be necessary if the tag is in a
! @c removed file (i.e. in the Attic)....
  
  @item -l
  Local; don't descend subdirectories.