################################################################################
# $Id: HELP.CVS,v 1.3 2001/07/15 00:03:35 zyrnix Exp $
#
# SAStk documentaion - or how we made the SAStk CVS tree and use it
#
# Author: Doug's notes mainly based on http://cvsbook.red-bean.com/cvsbook.html
# Doug Hogan zyrnix@users.sourceforge.net
################################################################################
# More documentation on CVS:
# (CVS bible) http://durak.org/cvswebsites/doc/
# (FAQs) http://www.loria.fr/cgi-bin/molli/fom.cgi
# GUIs for CVS http://www.cvshome.org/dev/addons.html
# http://www.loria.fr/cgi-bin/molli/wilma.cgi/doc
# http://www.cvshome.org/cvslinks.html
# Shell scripts for CVS http://www.ibiblio.org/pub/Linux/docs/HOWTO/\
# other-formats/html_single/CVS-RCS-HOWTO.html#Shell Scripts
# After you installed CVS, there should be an info page too 'info cvs'
################################################################################
# SAStk links:
# Project homepage http://SAStk.sourceforge.net
# Project site http://sourceforge.net/projects/sastk
# FTP location ftp://sastk.sourceforge.net/pub/sastk
# CVS repostiory cvs.sastk.sourceforge.net/cvsroot/sastk
# Web browsable CVS tree:
# http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/SAStk/?cvsroot=sastk
################################################################################
# ASSUMPTIONS:
# Installed OpenSSH
# Installed CVS
# username = zyrnix # Change for your user account if a developer.
# your shell = bash. Modify 'export' commands for csh/tcsh using 'setenv'.
################################################################################
# Based on version 1.21 of the GPL'd http://cvsbook.red-bean.com/cvsbook.html
#
# cvs.help
# Copyright (C) 2000 Doug Hogan
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
################################################################################
# Where to get CVS (binaries or source)
http://www.cvshome.org/dev/codes.html
# Where to get OpenSSH (you need it if you are a developer)
http://www.openssh.com
# Currently, you only need to do this to get our CVS tree if you are a SAStk
# developer:
mkdir -p $HOME/sourceforge/working
cd $HOME/sourceforge/working
export CVS_RSH=ssh
export CVSROOT=:ext:zyrnix@cvs.sastk.sourceforge.net:/cvsroot/sastk
cvs checkout SAStk
# If you are not an official SAStk developer (i.e. you don't have access to our
# CVS tree to commit changes) but would like to track the CVS tree, here's
# how you would do that:
# ('co' is a synonym for 'checkout'. When prompted for a password, hit enter.
mkdir -p $HOME/sourceforge/working
cd $HOME/sourceforge/working
export CVSROOT=:pserver:anonymous@cvs.SAStk.sourceforge.net:/cvsroot/sastk
cvs login
cvs -z3 co SAStk
# In these examples, assume the project we're using is sastk.
# Making a change to the working copy. I edited sastk.sh
#
# Now go to /home/zyrnix/sourceforge/working so that you update the whole tree
# If I made any other changes, those would be updated too
# Note: update only affects your working copy, not the master repository
# that everyone uses. You need to use 'commit' (see below) to affect
# the main repository.
#
# If you enter this command at the top directory where you executed the
# cvs checkout for sastk, then you don't need to use any arguments. CVS
# assumes you mean everything in the current working directory. If you want
# to update just sastk or sasrc, then do: 'cvs update sasrc' for example.
cvs update
# Now you can diff the files to see what has changed
# This will show you all changes
cvs diff
# This is boring output and has some excess info at the top so we'll use a
# more concise version. I like unified diffs so I'll do that.
# There's context diff which is -c, unified is -u and plain is no option.
cvs -Q diff -u
# CVS assumes we mean all files and directories unless we tell it so.
# If we wanted to import sastk.sh only, and ignore any other altered files
# we could have done (assuming sastk.sh is in our current directory):
cvs update sastk.sh
# Or diff a file version
cvs -Q diff -u sastk.sh
# Committing files to the repository. Again, assuming I'm in the same directory
# as the file...
#
# Watch it when you use commit. If you have any changes in files and forget
# to name a specific file, CVS assumes you mean all files so it will look
# through all of your files for any changes and commit them to the main
# repository.
cvs commit -m 'changed escape chars to stty -echo/echo' sastk.sh
# Note: When you checkout a project, you get the latest version of everything.
# Getting status on files. This will display the version numbers and working
# numbers. It will also show you if you modified the repository version.
cvs status sastk.sh
# Getting the log on who did what to the file:
cvs log sastk.sh
# Conflicts. Let's say that mRgOBLIN updates a file to revision 1.4. I haven't
# synced my source against the repository in a while, so my revision is 1.3.
# If I try to do something that conflicts (i.e. change the same line), then
# there will be a conflict and CVS will tell you that.
# You should check the status first to see if you are using an older version of
# the file
cvs status sastk.sh
# Then do a cvs update and CVS will try to merge in your local changes.
cvs update sastk.sh
# CVS tells you about a conflict. It will also put in '<<<<<<<' and
# '>>>>>>>>' indicating where the conflicts are.
# So you should edit the file, remove the markers, and then try to commit.
cvs commit -m "new version" sastk.sh
# Looking at different versions. This will produce the diff output between
# revisions 1.1 and 1.2. If you only give one number, CVS uses the highest
# revision in your local working copy against the named repository version.
cvs diff -u -r 1.1 -r 1.2 sastk.sh
# Fast method of reverting back versions. The -j flag is for joining.
# This will mrege differences between the two into a new revision 1.3
cvs update -j 1.2 -j 1.1 sastk.sh
# Adding files to the repository (files which did not exist when the repository
# was built. It will be build whereever your current directory is
touch newsastk.sh
cvs add newsastk.sh
cvs commit -m "added newsastk.sh" newsastk.sh
# Adding directories - just one step
mkdir sas-subdirectory
cvs add sas-subdirectory
# Add revision numbers. We should add revision tags to all of our files.
# CVS will expand this tag to the current revision of that file when it's
# committed.
#
# Add '$Id $' (without the space inbetween 'd' and '$') to your files.
# So we can get this output automatically:
# $Id: HELP.CVS,v 1.3 2001/07/15 00:03:35 zyrnix Exp $
# See http://cvsbook.red-bean.com/cvsbook.html#List%20Of%20Keywords
# if you are interested in the other expansion keywords.
# Adding a file that's not plain text. If you add some binary file to the
# repository, you have to turn off keyword expansion (see above) and
# line conversions. The -kb option does this. There are lots of other ways
# to filter out keyword expansion, but we don't really need it for this project
# since ours is all source code.
cvs add -kb sastk.jpg
cvs commit -m "added JPG of tux the pengiun" sastk.jpg
# You can also just disable keyword expansion:
cvs add -ko this_doc
cvs commit -m "added instructions" this_doc
# Removing files from the project. Please do this with care.
# First remove the file on the operating system level, then symbolically
# in the repository. Note: This will affect all users, not just your working
# copy.
rm test.sh
cvs remove test.sh
cvs commit -m "removed test.sh" test.sh
# Removing directories from the repository. CVS doesn't keep revisions on
# directories, only files. So you need to remove all files first.
# Then update in the directory above to prune empty directories.
cd dir
rm file1 file2 file3
cvs remove file1 file2 file3
cvs commit -m "removed file1-3" file1 file2 file3
cd ..
cvs update -P
# Renaming files in the repository. We want to rename oldname to newname.
mv oldname newname
cvs remove oldname
cvs add newname
cvs commit -m "renamed oldname to newname" oldname newname
# Renaming directories in the repository. Make sure to remove all files
# from olddir because the -P option deletes empty directories.
mkdir newdir
cvs add newdir
mv olddir/* newdir
cd olddir
cvs remove file1 file2 file3
cd ../newdir
cvs add file1 file2 file3
cd ..
cvs commit -m "moved file1, file2, and file3 from olddir to newdir"
cvs update -P
# Personalized cvs experience.
# If you know you want to always use context or unified diffs, then you can
# create a file in your home directory $HOME/.cvsrc that lists this.
echo "diff -c" >> $HOME/.cvsrc
# Getting snapshots. Useful for if you are away on vacation and come back
# and need to catch up. Or you know you liked the implementation done on
# a particular date. This command will update all of your files as if you
# had executed it on that date. -D retrieves the highest revision available
# on that date. The time is just saying give me the latest by the end of that
# day. By default, it means the midnight of the day.
# By default, it also gets the local time zone. We should always do things
# according to GMT since our time zones are so different.
cvs -q update -D "1999-04-19 23:59:59 GMT"
# Tags: These are important. When we do an official release, we need to tag
# that point in time as release 1.0 or so. That way we always have that
# stable base to go from.
# So let's set a tag for our 1.0 release
# Make sure you have another directory for official releases so we can easily
# checkout the source. Below, I checked out our official source when 1.0
# was released in a directory that doesn't have any of my local changes.
# Note: you cannot use periods in your tag name.
cd /home/zyrnix/sourceforge/working/release
cvs checkout sastk
# The reason for -c is that if we have any locally modified files, CVS will
# abort which is just what we want. We want this tag to be on the checked-in
# versions, not on any of our locally modified versions.
cvs -q tag -c Release_1_0-2000-12-19
# Here's how to checkout the source tree for that specific tag
# Make sure you don't do it in the same directory as all your local changes
mkdir -p /home/zyrnix/testing/release-1.0
cd /home/zyrnix/testing/release-1.0
cvs checkout -r Release_1.0-2000-12-19
# You can also diff based on the tag
cvs diff -c -r Release_1_0-2000-12-19 sastk.sh
# Or even revert to it
cvs update -r Release_1_0-2000-12-19 sastk.sh
# Retreiving a snapshot of all files (will merge any local changes you have.
# If you don't want that, then do a checkout instead).
cvs update -r Release_1_0-2000-12-19
# Deleting a tag
# To delete a tag, just specify the -d option to tag or rtag
# This deletes the tag from sastk.
cvs tag -d Release_1_0-2000-12-19 sastk
# However, if you want to commit a file based on a tag, you need to remove the
# tag property to the file. A tagged file is considered static and should
# never change. Here's how you remove the Tag status and then commit it
# back to the tree as a new revision.
cvs -q update -A sastk.sh
cvs commit -m "changed sastk.sh based on tag revision" sastk.sh
# Then you can run status on it to see if it worked
cvs -q status sastk.sh
# If you deleted a file, how to retreive it from a CVS repository:
# Let's say I deleted 'sastk.sh' and I want it back. CVS never really deletes
# your files. Instead, it stores them in an 'Attic' directory so you can
# get them back.
cvs -Q update -p -r 1.1 sastk.sh > sastk.sh
cvs add sastk.sh
cvs commit -m "revived sastk.sh" sastk.sh
cvs status sastk.sh
# Get to know the CVS commands, but there are a few shell scripts to make
# it easier.
# Lock CVS
# To lock cvs (say we want to back up the repository) you have to create a
# '#cvs.rfl' files in each repository directory.
# Safe/easy editing
# If you want to be safe, do 'cvs edit files' when you want to work on files.
# If you ever need to revert back to their original state, then you can
# issue 'cvs unedit files'.
# This also allows others to have watches (you can get notified when someone
# puts a file into edit mode so you know that there could be conflicts if you
# both change the same part of the file).
cd /home/zyrnix/sourceforge/working
cvs edit
# To make everyone put files into edit mode first, use:
cvs watch on
# To watch a file for commit. If the file(s) are committed, then you
# will get notified on the server machine. If you setup a CVSROOT/notify
# with username:email then it will use that email instead of the local machine.
cvs watch add commit file
# To display a list of who is watching what, do:
# (you can also leave out the file part for all files in pwd).
cvs watchers -l file
# To display a list of who is editing what, do:
# (you can also leave out the file part for all files in pwd).
cvs editors -l file
# Get rid of modules for modules no longer in use
# Use the release command, but use with care. This tells CVS you no longer
# wish to track these files in the repository.
cvs release file
# Setting up read-only access
# We should setup a CVSROOT/writers file that only allows the core SAStk
# team to access it. I assume sourceforge does this if we have to
# register who has access.
# In any event, a writers file just has a list of 1 username per line of
# people who can write to the repostiroy.
# You can bring all files up to a certain revision, but this is not recommended.
# We should use tags for any releases and let CVS keep track of internal
# numbering. Tags are a much better way to do this kind of tracking.
# However, if you do want to bring all files up to a certain revision:
# cvs commit -r 3.0 # to bring them all up to 3.0
###############################################################################
# Remote access - server specific to sourceforge for SAStk
###############################################################################
# Connect to the CVS server over SSH
# Then import the code. This only needs to be done once by one of us.
# For example, when you're ready to import
# 'SAStk' = module name, second 'SAStk' = vendor
export CVS_RSH=ssh
export CVSROOT=:ext:zyrnix@cvs.sastk.sourceforge.net:/cvsroot/sastk
cvs import -m "Initial CVS version" SAStk SAStk start
# To update your working copy with the CVS tree
# -z = compress level, -P = prune empty, d = current directory
cvs -z3 update -Pd
# However, if you are already logged onto the shell account at sourceforge
ssh -l zyrnix sastk.sourceforge.net
# Then you need to do this to checkout your local working copy:
# You can export CVSROOT=:ext:zyrnix@cvs1:/cvsroot/sastk
# if you are going to use several commands in this session.
# The reason for this is that they have an external firewall for the cvs
# server, but cvs1 doesn't since you are already in the network via ssh.
cvs -d:ext:zyrnix@cvs1:/cvsroot/sastk -z3 checkout sastk
# Here's how to put your public key on the server so you don't have to do
# password authentication (from the FAQ)
# If you wish to use your ssh keys with CVS/Shell accounts, simply copy your
# identity.pub file to "~zyrnix/.ssh/authorized_keys" on shell1. Also,
# cut and paste it into the web based account manager to have it synced across
# to the CVS server.
###############################################################################
# Below is stuff we'll probably never use unless we had a huge source tree
###############################################################################
# Branches. I'll go over branches, but I highly doubt we'll use them in
# this project. We don't really have a need for branching.
#
# Okay, create a branch from a previous revision. Assume we tagged the
# release 'Release_2000-12-19'.
# NOTE: CVS is sensitive to where options are placed. At the top of this
# document, I used '-d /path' to denote the path to the repository. In
# this case, it's used to store the checkout. The difference is where the
# action is. If an argument is before the action (here the action is checkout)
# then it has one meaning, and if it's after the action it has another.
# This is just getting the old source...
cvs -q checkout -d sastk_old_release -r Release_2000-12-19 sastk
# That will create a directory 'sastk_old_release' with the full checkout
# from 12/19/2000. Now we need to branch this. You would normally do this
# in a large release where you don't want to fix the bug in the current
# version because it's unstable since it's in development, but you need to
# provide people with a patch. The branch is called
# 'Release-2000-12-19_bugfix-branch'. We do this because otherwise we cannot
# tell the difference between a normal tag and a branch.
cd sastk_old_release
cvs -q tag -b Release-2000-12-19_bugfix-branch
# Now, we've created a branch, but we aren't currently using it yet.
# We need to checkout a new working copy on the branch or switch over an
# existing copy. (only need to do one of two). First we'll do a new copy
# since that's what you should probably use. If you do the second option,
# your local changes can cause problems when importing.
cvs checkout -d sastk_branch -r Release-2000-12-19_bugfix-branch sastk
# And here's how to switch over the existing copy assuming we're in sastk
# directory already.
cvs update -r Release-2000-12-19_bugfix-branch
# Now assume you change a file, say 'sastk_undo.sh'.
cvs -q update sastk_undo.sh
cvs commit -m "fixed program logic" sastk_undo.sh
# Now your revision number will have two more digits: a branch number and
# finally a per file number. The branch number will be the first unused even
# nonzero integer. It will end in a one since our trunk (1.x) is a one.
# Merging changes from a branch to the trunk.
# After you commit the change above, you need to switch over the working copy
# over to the highest trunk revisions and see if the bug fix needs to be
# done there too.
# By using '-A', you move the working copy off of the branch since -A removes
# tags (just like previously for the release tag). The -d means the pwd.
cvs -q update -d -A
# Now we need to merge the changes into the current working copy. -j = join
cvs -q update -d -j Release-2000-12-19_bugfix-branch
# And now update the working source
cvs -q update
# And finally commit it to the repository
cvs -q commit -m "merged from branch Release-2000-12-19_bugfix-branch"
# Multiple Merges
# The problem was that in the branch, the problem was fixed and the working
# copy also has it. By running this command, you only update these whatever
# differences these two have
cvs -q update -d -j "Release-2000-12-19_bugfixes-branch: 2 days ago" \
-j Release-2000-12-19_bugfixes
# Better way to merge multiple branches
# If you can, tag each fix number so that it's easier to merge changes
cvs -q tag Release-2000-12-19_bugfix-branch-number-1
# Then when it's time to merge the second change into the trunk, you can use
# the name of the other tag
cvs -q update -d -j Release-2000-12-19_bugfix-branch-number-1 \
-j Release-2000-12-19_bugfix-branch
# More important than the branch, remember that tagging affects the
# repository, not your local copy.
# Rtags - for repository tags, there's no need to do anything with a working
# copy
cvs rtag -b -r Release-2000-12-19 Release-2000-12-19-bugfix sastk
################################################################################
# Directions on creating your own CVS repository.
#
# We used these directions while sourceforge was being rebuilt and the CVS
# tree couldn't be accessed.
#
# This does not pertain to SAStk any longer. We have a working CVS tree online
# now. But if you want to create your own CVS repository for other projects,
# here's how you would do it:
################################################################################
# Make a directory for the source code -- just a temporary spot. We'll never
# use this directory again after we import the code.
mkdir /home/zyrnix/projects/src
# Copy the source tree there
cp SAStk-0.0.4.tar.gz /home/zyrnix/projects/src
# Go to the temporary directory
cd /home/zyrnix/projects/src
# Extract the source here
tar -zxvf SAStk-0.0.4.tar.gz
# Create a new repository, the directory does not currently exist
# Never work on any files in here. They will all have 'file.sh,v' for instance.
# The ,v means that it's holding all of the prior changes. You should
# commit changes from a working copy if you want to make changes to the current
# file.sh. Remember, you do your work on a checked out copy, not the repository
cvs -d /home/zyrnix/projects/repository init
# This sets the CVSROOT variable so you don't need to do -d from now on.
# Note: We actually are going to have two projects going on at the same time
# (sasrc and sastk) but they have the same CVSROOT directory so we don't
# have to worry about changing this variable.
export CVSROOT=/home/zyrnix/projects/repository
# Go to where the source is for both projects
cd /home/zyrnix/projects/src/SAStk
# Import the source code to the repository
# When you import, it will create a directory with the name 'sastk' so make
# sure you don't end up with 'sastk/sastk' by being one directory above this.
cvs import -m "initial SAStk import to CVS" sastk SAStk start
# You can now safely delete /home/zyrnix/projects/src
rm -rf /home/zyrnix/projects/src
# Make a directory for your working copy
mkdir /home/zyrnix/projects/working
# Go there
cd /home/zyrnix/projects/working
# Checkout a copy of the source from the main repository. This will checkout
# both sasrc and sastk since they part of the same project.
cvs checkout sastk
# Now you can use the same commands as above, 'update, diff, status' etc. on
# your own repository.