Single-User Subversion
Pages: 1, 2
Basic Commands
Most svn commands don't use repository URIs, acting directly on a local
working copy. The most general form of an svn command is:
$ svn <command> [<options>] [<targets>]where targets is the list of files or directories to operate on, and
options is an optional list of flags, in the familiar fashion of most
Unix command-line interfaces. For most svn commands,
targets defaults to the current directory, and the command operates
recursively on each directory it processes.
The first command we'll see is svn commit (also known as
svn ci, which should look familiar to CVS users). This commits the
modifications of the local files into the repository. For example,
$ svn commit *.c includewill check all .c files in the current directory, and all files in the include subdirectory, recursively for modifications and incorporate them into the repository. Only modified files will be included in the change set. As a consequence of this, a simple
$ svn commitcommits all modified files in the current directory and its subdirectories.
Note that Subversion requires a log message when committing changes. You can
specify the message via the -m command-line option, as in the
import and mkdir examples above. Lacking this
option, svn will fire up the editor specified by one of the
environment variables SVN_EDITOR, VISUAL, or
EDITOR.
Log messages can be retrieved by the svn log command, which
presents a formatted list of changes for its targets. It accepts a
-v (verbose) option to include in the changelog the list of files
that were modified at each revision. The common -r option limits
the list to a revision or a range of revisions. For example, updating a
ChangeLog file with all changes since revision #42 is as simple as:
$ cd ~/frobwork/trunk
$ svn log -r42:HEAD >> ChangeLog
$ svn commit ChangeLog -m 'Update ChangeLog'Here, HEAD is a keyword that can be used in place of any revision number.
It refers to the last revision number that was checked in the repository.
If you're unhappy with your changes, the svn revert command
will undo all local edits you've done to its targets. Unlike other
svn commands, revert doesn't operate recursively on
directories, unless you pass the -R option to it.
To add or to remove files, use the svn add and svn
remove commands. They mark files or directories to be added or removed
into and from the repository at the next commit. Similarly, svn
mkdir creates a new directory under version control in the working
copy.
As a rule of thumb, the set of changes included in a commit should address a
specific problem or implement a well-defined functionality. Thinking about your
log message before making the changes can help you to focus. A single-purpose
commit is easily examined (as a diff), so any bugs it may have
introduced are appear more clearly. Tracking down regressions is more
difficult with several unrelated changes in a single commit.
Examining Your Changes
At some point in development, you will probably ask yourself which files
have I modified, and what changes did I make? The svn status
and svn diff commands provide answers.
svn status scans the specified targets of your working copy for
files that have changed since the last checkout or commit. For each file,
it reports its status -- modified, added, deleted, or unknown to the
versioning system.
svn diff produces a diff file applicable by the
patch(1) program. By default, it uses the unified diff format.
It's possible to pass additional options to the underlying diff(1)
utility via the -x switch. By default, it compares the current
working copy with the latest checked-out revision, but it's also able to
produce a patch between two arbitrary revisions in the repository, or between
your working copy and an older revision with the -r switch:
$ svn diff -r14:18 *.c *.h > /tmp/r14-to-r18.patchTags and Branches
A simpler way of retrieving any previous state of a file within your working
copy is to use svn update. This command updates its targets to
their state at a specified revision (defaulting to the HEAD revision). For
example,
$ svn update -r42 includereverts the include directory (and its contents) to the 42nd
revision. (update is also used when you want to integrate changes
from another working copy into your working copy, but we'll cover this in
another article.) Subversion provides a more powerful mechanism to track the
release points of your projects: tags and branches. There is
no difference, from Subversion's viewpoint, between tags and branches; the
difference is in how you use them.
To create a tag or a branch, use the svn copy command.
svn copy makes a copy of a versioned resource (a file or a
directory), while retaining history. In other words, it doesn't add a file (or
a whole tree) -- it only marks a new entry in the repository as being
indentical to another one, at a specified revision. Thus, copies occur
done in constant time, although they may logically create huge parallel
trees.
Let's take an example. Suppose I've just released a new frobnizer, version
2.0, and I want Subversion to remember for me that frobnizer v2 corresponds to
revision 42. Assuming the current revision level of directory trunk in
my working copy is 42, I'll say:
$ cd ~/frobwork
$ svn copy trunk frobnizer-2.0
$ svn commit -m 'Release v2.0'My repository has now two main subdirectories: /frobnizer/trunk and /frobnizer/frobnizer-2.0. They branch from the same revision, but can now evolve separately.
If I decide to not commit any changes to the
/frobnizer/frobnizer-2.0 subdirectory, it's called a
tag. Otherwise, it's a branch.
The advantage of a tag is obvious. It's possible to check out
/frobnizer/frobnizer-2.0 to get the source for the frobnizer v2.
Branches are mainly useful when a team of developers have commit access to a
same repository. If a long, experimental development has to be made, it's
better to create a branch, make the changes in it, and reintegrate them into
the trunk when the development is finished. This avoids interferences.
Subversion provides a mechanism (the svn merge command) to report
the changes made in one branch into another. Branches may not be very useful
to you if you're the only Subversion user on your system, and that's why I won't
elaborate on this subject. However, the Subversion developers recommend to
create two subdirectories, branches/ and tags/, along the
trunk/, to store branches and tags. (This is how the Subversion repository is
organized.)
Distribution
Now that you've fixed many bugs, you've decided to release another version of your project as a source tarball.
You can't just tar+gzip your working copy: it contains hidden Subversion
files and probably also some other temporary files (backups, object files,
etc.). The svn export command is here to help you. It checks out a
specified version without including metadata.
$ svn export file:///home/rafael/svn/frobnizer/frobnizer-2.0
$ tar cf frobnizer-2.0.tar frobnizer-2.0
$ gzip -9 frobnizer-2.0.tarDon't Forget ...
... to make backups! Your repository holds important information. It's possible to dump the contents of the repository (including all revisions) into a dumpfile. This format is portable, and you can use it to reconstruct a repository if necessary.
For example, it's useful to have, in a crontab, something like :
svnadmin dump /home/rafael/svn | gzip -9 > dump.gzThis way, the repository can be restored via
gunzip -c dump.gz | svnadmin load /home/rafael/svnHints and Links
The most useful svn subcommand, at least for beginners, is
help. svn help gives a summary of all subcommands
available, and svn help foo describes the subcommand
foo. Read also the svn(1) and
svnadmin(1) manpages. svnadmin is for administrative
commands.
The Subversion home page holds a substantial amount of information. The Subversion Book, a work in progress, is also useful, containing far more information than possible to put in a small article.
Rafael Garcia-Suarez is a French software engineer and Unix system administrator.
Return to ONLamp.com.
You must be logged in to the O'Reilly Network to post a talkback.
Showing messages 1 through 11 of 11.
-
New Subversion Community Websites
2004-06-16 10:42:49 AForgue [Reply | View]
Two new Subversion related community websites have just recently opened up. These may serve as a good resource for anyone looking for help with Subversion:
Subversion Forums: http://www.svnforum.org
Subversion Wiki: http://www.subversionary.org
-
cvs or subversion
2003-10-20 05:37:54 anonymous2 [Reply | View]
In terms of security, which one soars ?
-
Spanish translation
2003-04-10 03:36:01 anonymous2 [Reply | View]
Raphael Garcia-Suarez gave me permission to translate it to Spanish and publish it in my website :-)
Et voilą the translated tutorial:
Subversion personal
-
Wow
2003-03-09 14:16:03 anonymous2 [Reply | View]
This is pretty cool... sed 's/cvs/svn/g' your source management stuff cause alot of the commands use the same syntax as cvs.
-
Re: Server setup sounds difficult
2003-02-09 22:34:22 anonymous2 [Reply | View]
Huh? Subversion and Apache2 both has binaries for Win32. Just install them and you'll have Subverion running under Windows.
-
Server setup sounds difficult
2003-01-01 08:03:45 anonymous2 [Reply | View]
I was dissapointed to read that it requires Apache and BerkelyDB. The HTTP based protocol is one of the best uses of HTTP I've heard of in a while. Just a great idea that allows almost any client to access the source base. What bothers me is that the server seems to be restricted to just Unix. Wished it were servlet based, perhaps a .war file that you just place under Tomcat's web root, and walla, revision control system on Windows.
Taylor
-
re: Difference from RCS?
2002-11-10 00:23:15 anonymous2 [Reply | View]
Probably the most significant difference from RCS (from a single-user perspective) is that RCS does versioning per-file, while svn versioning includes directories.
Thus svn can record file name changes, file deletions and additions, and also file properties (e.g., permissions). There are other differences, but being able to version files through name changes is a big deal.
I created an article which provides a guide to setting up a source control server with Subversion on the Windows platform. Aimed at beginners, the article takes a how to, step-by-step tutorial based approach.
http://www.clearmud.homeip.net/subversion.html