sccs.me

早期freebsd实现

.\" Copyright (c) 1986, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)sccs.me	8.1 (Berkeley) 6/8/93
.\"
.eh '\fRPSD:14-%\fP''\fRAn Introduction to the Source Code Control System\fP'
.oh '\fRAn Introduction to the Source Code Control System\fP''\fRPSD:14-%\fP'
.ds S \s-1SCCS\s0
.ds I \s-1SID\s0
.nr bi 8n
.ev 1			\" only for keeps
.ss 16
.ev
.\".he '\*S Introduction''%'
.+c
.(l C
.sz 14
.b
An Introduction to the
Source Code Control System
.sz
.r
.sp
Eric Allman
.i "Project Ingres"
.i "University of California at Berkeley"
.)l
.sp 3
.pp
.(f
This is version 1.21 of this document.
It was last modified on 12/5/80.
.)f
This document gives a quick introduction
to using the Source Code Control System
(\*S).
The presentation is geared to programmers
who are more concerned with
what
to do to get a task done
rather than how it works;
for this reason some of the examples
are not well explained.
For details of what the magic options do,
see the section on
.q "Further Information" .
.(l F
This is a working document.
Please send any comments or suggestions
to [e-mail].
.)l
.sh 1 "Introduction"
.pp
\*S is a source management system.
Such a system maintains a record of versions of a system;
a record is kept with each set of changes
of what the changes are,
why they were made,
and who made them and when.
Old versions can be recovered,
and different versions can be maintained simultaneously.
In projects with more than one person,
\*S will insure that two people are not
editing the same file at the same time.
.pp
All versions of your program,
plus the log and other information,
is kept in a file called the
.q "s-file" .
There are three major operations
that can be performed on the s-file:
.np
Get a file for compilation (not for editing).
This operation retrieves a version of the file
from the s-file.
By default, the latest version is retrieved.
This file is intended for compilation, printing, or whatever;
it is specifically NOT intended to be edited
or changed in any way;
any changes made to a file retrieved
in this way will probably be lost.
.np
Get a file for editing.
This operation also retrieves a version of the file
from the s-file,
but this file is intended to be edited and then
incorporated back into the s-file.
Only one person may be editing a file at one time.
.np
Merge a file back into the s-file.
This is the companion operation to (2).
A new version number is assigned,
and comments are saved explaining why this change was made.
.sh 1 "Learning the Lingo"
.pp
There are a number of terms that are worth learning
before we go any farther.
.sh 2 "S-file"
.pp
The s-file
is a single file that holds all the different versions
of your file.
The s-file is stored in
differential format;
.i i.e. ,
only the differences between versions are stored,
rather than the entire text of the new version.
This saves disk space
and allows selective changes to be removed later.
Also included in the s-file
is some header information for each version,
including the comments given by the person who
created the version explaining why the changes were made.
.sh 2 "Deltas"
.pp
Each set of changes to the s-file
(which is approximately [but not exactly!] equivalent
to a version of the file)
is called a
.i delta .
Although technically a delta only includes the
.i changes
made,
in practice
it is usual for
each delta to be made with respect to
all the deltas that have occurred before\**.
.(f
\**This matches normal usage, where the previous changes are not saved
at all,
so all changes are automatically based on all other changes
that have happened through history.
.)f
However,
it is possible to get a version of the file
that has selected deltas removed out of the middle
of the list of changes \*-
equivalent to removing your changes later.
.sh 2 "\*I's (or, version numbers)"
.pp
A \*I
(\*S Id)
is a number that represents a delta.
This is normally a two-part number
consisting of a
.q release
number and a
.q level
number.
Normally the release number stays the same,
however,
it is possible to move into a new release
if some major change is being made.
.pp
Since all past deltas are normally applied,
the \*I of the final delta applied
can be used to represent a version number of the file
as a whole.
.sh 2 "Id keywords"
.pp
When you get a version of a file
with intent to compile and install it
(\c
.i i.e. ,
something other than edit it),
some special keywords are expanded inline
by \*S.
These
.i "Id Keywords"
can be used to include the current version number
or other information into the file.
All id keywords are of the form
.b % \c
.i x \c
.b % ,
where
.i x
is an upper case letter.
For example,
.b %\&I\&%
is the \*I of the latest delta applied,
.b %\&W\&%
includes the module name,
\*I,
and a mark that makes it findable by a program,
and
.b %\&G\&%
is the date of the latest delta applied.
There are many others,
most of which are of dubious usefulness.
.pp
When you get a file for editing,
the id keywords are not expanded;
this is so that after you put them back in to the s-file,
they will be expanded automatically on each new version.
But notice: if you were to get them
expanded accidently,
then your file would appear to be the same version
forever more,
which would of course defeat the purpose.
Also,
if you should install a version of the program
without expanding the id keywords,
it will be impossible to tell what version it is
(since all it will have is
.q %\&W\&%
or whatever).
.sh 1 "Creating \*S Files"
.pp
To put source files
into
\*S
format, run the following shell script from csh:
.(b
mkdir SCCS save
foreach i (*.[ch])
	sccs admin \-i$i $i
	mv $i save/$i
end
.)b
This will put the named files
into s-files
in the subdirectory
.q SCCS
The files will be removed from the current directory
and hidden away in the directory
.q save ,
so the next thing you will probably want to do
is to get all the files
(described below).
When you are convinced that
\*S has correctly created the s-files,
you should remove the directory
.q save .
.pp
If you want to have id keywords in the files,
it is best to put them in before you create the s-files.
If you do not,
.i admin
will print
.q "No Id Keywords (cm7)" ,
which is a warning message only.
.sh 1 "Getting Files for Compilation"
.pp
To get a copy of the latest version
of a file,
run
.(b
sccs get prog.c
.)b
\*S will respond:
.(b
1.1
87 lines
.)b
meaning that version 1.1 was retrieved\**
.(f
\**Actually,
the \*I of the final delta applied was 1.1.
.)f
and that it has 87 lines.
The file
.i prog.c
will be created
in the current directory.
The file will be read-only
to remind you that you are not
supposed to change it.
.pp
This copy of the file
should not be changed,
since \*S is unable
to merge the changes
back into the s-file.
If you do make changes,
they will be lost the next time
someone does a
.i get .
.sh 1 "Changing Files (or, Creating Deltas)"
.sh 2 "Getting a copy to edit"
.pp
To edit a source file,
you must first get it,
requesting permission to edit it\**:
.(f
\**The
.q "edit"
command is equivalent to using the \-e
flag to
.i "get" ,
as:
.(l
sccs get \-e prog.c
.)l
Keep this in mind when reading other documentation.
.)f
.(b
sccs edit prog.c
.)b
The response will be the same as with
.i get
except that it will also say:
.(b
New delta 1.2
.)b
You then edit it,
using a standard text editor:
.(b
vi prog.c
.)b
.sh 2 "Merging the changes back into the s-file"
.pp
When the desired changes are made,
you can put your changes into the
\*S
file using the
.i delta
command:
.(b
sccs delta prog.c
.)b
.pp
Delta will prompt you for
.q "comments?"
before it merges the changes in.
At this prompt you should type a one-line description
of what the changes mean
(more lines can be entered by ending each line
except the last with a backslash\**).
.(f
\**Yes, this is a stupid default.
.)f
.i Delta
will then type:
.(b
1.2
5 inserted
3 deleted
84 unchanged
.)b
saying that delta 1.2 was created,
and it inserted five lines,
removed three lines,
and left 84 lines unchanged\**.
.(f
\**Changes to a line are counted as a line deleted
and a line inserted.
.)f
The
.i prog.c
file will be removed;
it can be retrieved
using
.i get .
.sh 2 "When to make deltas"
.pp
It is probably unwise to make a delta
before every recompilation or test;
otherwise,
you tend to get a lot of deltas with comments like
.q "fixed compilation problem in previous delta"
or
.q "fixed botch in 1.3" .
However,
it is very important to delta everything
before installing a module for general use.
A good technique is to edit the files you need,
make all necessary changes and tests,
compiling and editing as often as necessary
without making deltas.
When you are satisfied that you have a working version,
delta everything being edited,
re-get them,
and recompile everything.
.sh 2 "What's going on: the info command"
.pp
To find out what files where being edited,
you can use:
.(b
sccs info
.)b
to print out all the files being edited
and other information such as the name of the user
who did the edit.
Also,
the command:
.(b
sccs check
.)b
is nearly equivalent to the
.i info
command,
except that it is silent if nothing is being edited,
and returns non-zero exit status if anything is being edited;
it can be used in an
.q install
entry in a makefile
to abort the install
if anything has not been properly deltaed.
.pp
If you know that everything being edited should be deltaed,
you can use:
.(b
sccs delta \`sccs tell\`
.)b
The
.i tell
command is similar to
.i info
except that only the names of files being edited
are output,
one per line.
.pp
All of these commands take a
.b \-b
flag
to ignore
.q branches
(alternate versions, described later)
and the
.b \-u
flag to only give files being edited by you.
The
.b \-u
flag takes an optional
.i user
argument,
giving only files being edited by that user.
For example,
.(b
sccs info \-ujohn
.)b
gives a listing of files being edited by john.
.sh 2 "ID keywords"
.pp
Id keywords can be inserted into your file
that will be expanded automatically by
.i get .
For example,
a line such as:
.(b
static char SccsId[] = "%\&W\&%\et%\&G\&%";
.)b
will be replaced with something like:
.(b
static char SccsId[] = "@\&(#)prog.c	1.2	08/29/80";
.)b
This tells you
the name and version
of the source file
and the time the delta was created.
The string
.q "@\&(#)"
is a special string
which signals the beginning
of an
\*S
Id keyword.
.sh 3 "The what command"
.pp
To find out what version of a program
is being run,
use:
.(b
sccs what prog.c /usr/bin/prog
.)b
which will print all strings
it finds that
begin with
.q "@\&(#)" .
This works on all types of files,
including binaries and libraries.
For example, the above command will output something like:
.(b
prog.c:
	prog.c	1.2	08/29/80
/usr/bin/prog:
	prog.c	1.1	02/05/79
.)b
From this I can see
that the source that I have in prog.c
will not compile into the same version
as the binary in /usr/bin/prog.
.sh 3 "Where to put id keywords"
.pp
ID keywords can be inserted anywhere,
including in comments,
but
Id Keywords that are compiled into the object module
are especially useful,
since it lets you find out what version of
the object is being run,
as well as the source.
However,
there is a cost:
data space is used up to store
the keywords,
and on small address space machines
this may be prohibitive.
.pp
When you put id keywords into header files,
it is important that you assign them to different variables.
For example, you might use:
.(b
static char AccessSid[] = "%\&W\&%	%\&G\&%";
.)b
in the file
.i access.h
and: