SVN: Learn From Scratch

Preface What is Subversion?

Subversion is a free/open source version control system(VCS). It can be used to manage any collection of files(Not just source code). It manages the changes made to them, over time.

0.1 Is Subversion the right tool?

1. Archive old versions of files and directories, possibly resurrect them, and examine logs of how they’ve changed over time.
2. Collaborate with people on documents and keep track of who made which changes.

0.2 Subversion’s History

The goal is to fix CVS, and the new should match CVS’s features and preserve the same development model, but not duplicate CVS’s most ovbious flaws.

0.3 Subversion’s Architecture

3. Subversion client program which manages locla reflections of portions that versioned data.
4. Multiple routes through a Repository Access(RA) layer, some of which go across computer networks.
5. Subversion repository that holds your versioned data.

0.4 Subversion’s Components

1. svn : The command-line client program
2. svnversion: A program for reporting the state of a working copy.
3. svnlook: A tool for directly inspecting a Subversion reposity.
4. svnadmin: A tool for creating, tweaking, or repairing a Subversion repository.
5. mod_dav_svn: A plug-in module for the Apache HTTP Server, used to make your repository avaiable to others over a network.
6. svnserve: A custom standalone server program, runnable as a daemon process or invokable by SSH; another way to make your repository available to others over a network.
7. svndumpfilter: A program for filtering Subversion repository dump streams.
8. svnsync: A program for incrementally mirroring one reposity to another over a network.
9. svnrdump: A program for performing repository history dumps and loads over a network.

0.5 What’s new in Subversion

Subversion 1.7 (October 2011)
Release 1.7 was primarily a delivery vehicle for two big plumbing overhauls of existing Subversion components. The largest and
most impactful of these was the so-called “WC-NG”—a complete rewrite of the libsvn_wc working copy management library.
The second change was the introduction of a sleeker HTTP protocol for Subversion client/server interaction. Subversion 1.7
delivered a handful of additional features, many bug fixes, and some notable performance improvements, too.

0.6 Audience

To Subversion, all data is just data.

Chapter1 Fundamental Concepts

1.1Version Control Basics

1.1.1 The Repository

A repository is the central store of that system’s data. The repository stores information in the form of a filesystem tree-a hierarchy of files and directories.

A kind of file server. But the files are changed and the repository remembers each version of those files.

1.1.2 The Working Copy

A working copy is, quite literally, a local copy of a particular version of a user’s VCS-managed data upon which that user is free to work.

1.1.3 Versioning Models

To enable collaborative editing and sharing of that data.

(1) The problem of file sharing

(2)The lock-modify-unlock solution

(3)The copy-modify-merge solution

1.2 Version Control the Subversion Way

1.2.1 Subversion Repositories

A Subversion repository is an abstract entity, able to be operated upon almost exclusively by Subversion’s own libraries and tools.

1.2.2 Revisions

A Subversion client commits (that is, communicates the changes made to) any number of files and directories as a single atomic transaction.
Each time the repository accepts a commit, this creates a new state of the filesystem tree, called a revision. Each revision is assigned a unique natural number, one greater than the number assigned to the previous revision. The initial revision of a freshly created repository is numbered 0 and consists of nothing but an empty root directory.
Unlike most version control systems, Subversion’s revision numbers apply to the entire repository tree, not individual files.

1.2.3 Addressing the Repository

Use URL to identify versioned files and directories in repositories.
The Subversion client will automatically encode URLs as necessary, just like a web browser does.If the URL contains spaces, be sure to place it within quotation marks at the command line so that your shell treats the whole thing as a single argument to the program.
In Subversion 1.6, a new caret (^) notation was introduced as a shorthand for “the URL of the repository’s root directory”.

1.2.4 Subversion Working Copies

A Subversion working copy is an ordinary directory tree on your local system, containing a collection of files.Each working copy contains a subdirectory named .svn.

（1）How the working copy works

• What revision your working file is based on (this is called the file’s working revision)
• A timestamp recording when the local copy was last updated by the repository
Four stata:

• Unchanged, and current
  svn commit svn update
• Locally changed, and current
  svn commit svn update
• Unchanged, and out of date
  svn commit svn update
• Locally changed, and out of data
  svn update svn commit

(2)Fundamental working copy interactions

$ svn checkout http://svn.example.com/repos/calc**

it simply creates a working copy of the project for you.

$ svn commit exmple.file -m "Add something"
$ svn update // Another Person who has copy the same directory.

(3) Mixed-revision woking copies

1)Updates and commits are separate

One of the fundamental rules of Subversion is that a “push” action does not cause a “pull” nor vice versa.

2) Mixed revisions are normal

To examine your mixture of working revisions,

$ svn status --verbose(-v)

you’ll discover that it’s sometimes nice to forcibly backdate (or update to a revision older thanthe one you already have) portions of your working copy to an earlier revision;

3)Mixed revisions have limitations

• First, you cannot commit the deletion of a file or directory that isn’t fully up to date.
• Second, you cannot commit a metadata change to a directory unless it’s fully up to date.

1.3 Summary

Chapter2 Basic Usage

2.1 Help

$ svn help

2.2 Getting Data into your repository

• svn import
• svn add

2.2.1 Importing Files and Directories

The svn import command is a quick way to copy an unversioned tree of files into a repository, creating intermediate directories as necessary.
svn import doesn’t require a working copy, and your files are immediately committed to the repository.

 $ snv import /path/to/mytree \
 	 http://svn.example.com/svn/repo/some/project \
 	 -m "Initial import"

Note that you didn’t have to create that new directory in repo first.

$ svn list http://svn.example.com/svn/repo/some/project

Note that after the import is finished, the original local directory is not converted into a working copy.

2.2.2 Recommended Repository Layout

• First recommend that each project have a recognizable project root in the repository, a directory under which all of the versionedinformation for that project—and only that project—lives.
• Secondly, we suggest that each project root contain a trunk subdirectory
  for the main development line, a branches subdirectory in which specific branches (or collections of branches) will be created,
• Third a tags subdirectory in which specific tags (or collections of tags) will be created.

$ svn list file:///var/svn/single-project-repo
trunk/
branches/
tags/
$ svn list file:///var/svn/multi-project-repo
project-A/
project-B/
$ svn list file:///var/svn/multi-project-repo/project-A
trunk/
branches/
tags/
$

2.2.3 What’s in a name?

As long as your locale settings are compatible with UTF-8 and you don’t use control characters in path names, you should have no trouble communicating
with Subversion.

2.3 Creating a working copy

By performing a checkout of your project.(most recently created or modified)

$ svn checkout http://svn.example.com/svn/repo/trunk
A trunk/README
A trunk/INSTALL
A trunk/src/main.c
A trunk/src/header.h
…
Checked out revision 8810.
$

In the working copy, copy or move an item to tell Subversion about everything else that you do.

$ svn copy
$ svn move

$ svn checkout http://svn.example.com/svn/repo/trunk my-working-copy
A my-working-copy/README
A my-working-copy/INSTALL
A my-working-copy/src/main.c
A my-working-copy/src/header.h
…
Checked out revision 8810.
$

If the local directory you specify doesn’t yet exist, that’s okay—svn checkout will create it for you.

2.4 Basic work cycle

2.4.1 Update your working copy

Use svn update to bring your working copy into sync with the latest revision in the repository:

$ svn update
Updating '.':
U foo.c
U bar.c
Updated to revision 2.
$

2.4.2 Make your changes

• file change
• tree change

$ svn add FOO

Use this to schedule the file, directory, or symbolic link FOO to be added to the repository.(file or directory, if FOO is a directory, everything underneath FOO will be scheduled for addition unless you pass the --depth=empty option).

$ svn delete FOO

Use this to schedule the file, directory, or symbolic link FOO to be deleted from the repository. If FOO is a file or link, it is immediately deleted from your working copy. If FOO is a directory, it is not deleted, but Subversion schedules it for deletion. When you commit your changes, FOO will be entirely removed from your working copy and the repository.

$ svn copy FOO BAR

Create a new item BAR as a duplicate of FOO and automatically schedule BAR for addition. When BAR is added to the repository on the next commit, its copy history is recorded (as having originally come from FOO). svn copy does not create intermediate directories unless you pass the --parents option.

$ svn move FOO BAR

This command is exactly the same as running svn copy FOO BAR; svn delete FOO. That is, BAR is scheduled for addition as a copy of FOO, and FOO is scheduled for removal. svn move does not create intermediate directories unless you pass the --parents option.

svn mkdir FOO

This command is exactly the same as running mkdir FOO; svn add FOO. That is, a new directory named FOO is created and scheduled for addition.

2.4.3 Review your changes.

(1) See an overview of your changes

$ svn status
? scratch.c
A stuff/loot
A stuff/loot/new.c
D stuff/old.c
M bar.c
$

• ? item
  The file, directory, or symbolic link item is not under version control.
• A item
  The file, directory, or symbolic link item has been scheduled for addition into the repository.
• C item
  The file item is in a state of conflict. That is, changes received from the server during an update overlap with local changes that you have in your working copy (and weren’t resolved during the update). You must resolve this conflict before committing your changes to the repository.
• D item
  The file, directory, or symbolic link item has been scheduled for deletion from the repository.
• M item
  The contents of the file item have been modified.

If you pass a specific path to svn status, you get information about that item alone:

$ svn status stuff/fish.c
D stuff/fish.c

svn status also has a --verbose (-v) option, which will show you the status of every item in your working copy, even if it has
not been changed:

$ svn status -v
M 44 23 sally README
44 30 sally INSTALL
M 44 20 harry bar.c
44 18 ira stuff
44 35 harry stuff/trout.c
D 44 19 ira stuff/fish.c
44 21 sally stuff/things
A 0 ? ? stuff/things/bloo.h
44 36 harry stuff/things/gloo.c

For this, svn status offers the --show-updates (-u) option, which contacts the repository and adds information about items that are out of date:

$ svn status -u -v
M * 44 23 sally README
M 44 20 harry bar.c
* 44 35 harry stuff/trout.c
D 44 19 ira stuff/fish.c
A 0 ? ? stuff/things/bloo.h
Status against revision: 46

(2) Examine the details of your local modifications

$ svn diff

2.4.4 Fix your mistakes

Undoing your work and starting over from scratch doesn’t require such acrobatics. Just use the svn revert command:

$ svn status README
M README
$ svn revert README
Reverted 'README'
$ svn status README
$

Note that svn revert can undo any scheduled operation, for example add file.

2.4.5 Resolve any conflicts

(1) Viewing conflict differences interactively

The first is the “diff-full” command (df), which displays all the local modifications to the file in question plus any conflict regions:

(2)Resolving conflict differences interactively

(3) Postponing conflict resolution

$ svn update
Updating '.':
Conflict discovered in 'sandwich.txt'.
Select: (p) postpone, (df) diff-full, (e) edit,
(mc) mine-conflict, (tc) theirs-conflict,
(s) show all options: p
C sandwich.txt
Updated to revision 2.
Summary of conflicts:
Text conflicts: 1
$ ls -1
sandwich.txt
sandwich.txt.mine
sandwich.txt.r1
sandwich.txt.r2

$ svn resolve --accept <option>

• If you want to choose the version of the file that you last checked out before making your edits, choose the base argument.
• If you want to choose the version that contains only your edits, choose the mine-full argument.
• If you want to choose the version that your most recent update pulled from the server (and thus discarding your edits entirely), choose the theirs-full argument.
• However, if you want to pick and choose from your changes and the changes that your update fetched from the server, merge the conflicted text “by hand” (by examining and editing the conflict markers within the file) and then choose the working argument.

$ svn resolve --accept working sandwich.txt
Resolved conflicted state of 'sandwich.txt'

(4) Merging conflicts by hand

$ cat sandwich.txt
Top piece of bread
Mayonnaise
Lettuce
Tomato
Provolone
<<<<<<< .mine
Salami
Mortadella
Prosciutto
=======
Sauerkraut
Grilled Chicken
>>>>>>> .r2
Creole Mustard

After changing by hand, then:

$ svn resolve --accept working sandwich.txt
Resolved conflicted state of 'sandwich.txt'
$ svn commit -m "Go ahead and use my sandwich, discarding Sally's edits."

Note that svn resolve, unlike most of the other commands we deal with in this chapter, requires that you explicitly list any filenames that you wish to resolve.
once the temporary files are removed, Subversion will let you commit the file even if it still contains conflict markers.

(5)Discarding your changes in favor of a newly fetched revision

If you get a conflict and decide that you want to throw out your changes, you can run svn resolve --accept theirs-full CONFLICTED-PATH and Subversion will discard your edits and remove the temporary files:

(6)Punting: using svn revert

Throw out your changes and start your edits again;

 $ svn revert sandwith.txt

Note that when you revert a conflicted file, you don’t have to use svn resolve.

2.4.6 Commit your changes

$ svn commit -m "Corrected number of cheese slices."
Sending sandwich.txt
Transmitting file data .
Committed revision 3.

$ svn commit -F logmsg
Sending sandwich.txt

Chapter3 Advanced Topics

Chapter4 Branching and Merging

Chapter5 Repository Administration

Chapter6 Server Configuration

Chapter7 Customizing Your Subversion Experience

Chapter8 Embeddding Subversion

Chapter9 Subversion Complete Reference

Appendix A Subversion Quick-Start Guide

Appendix B Subversion for CVS Users

Appendix C WebDAV and Autoversioning

AppendixD Copyright