Subversion Cheat Sheet
Create a Repository
To store projects in Subversion, first you must create a repository. This must be done to a local drive on a local machine. Creating a repository on a network drive is not supported. To create a repository type:
UNIX
svnadmin create /path/to/repository
Windows
svnadmin create d:/path_to_repository
By default this sets up a Berkeley database to store the repository. Individual projects should be created as subdirectories of the repository directory (see the next section). Notice that the Windows version includes a drive letter, but also uses forward slashes instead of back slashes. The forward slashes are required even on Windows.
Add a New Project - svn import
To add a project, the Subversion documentation suggests that you create a directory structure like the following:
A root project directory contains three subdirectories, branches, tags, and trunk. Your files and directories are stored under the trunk directory.
Create the directories as described. Assuming the project directory is a subdirectory of the current directory, you would enter the following command
UNIX
svn import project file:///repository_name/project -m "First Import"
Windows
svn import project file:///d:/repository_name/project -m "First Import"
Network
svn import project http://host_name/svn_dir/repository_name/project -m "First Import"
Notice the Network example includes an svn_dir. This assumes you are using Apache 2.0 and the Subversion modules. When setting up Subversion on Apache, a virtual directory is created on the server that points to your repository directory. More information on Apache 2 setup is described later in this document.
This creates the initial project which you can work from. To get the files under version control, you must checkout a project to begin working on it.
Checking Out a Project - svn checkout
To start using the version control features check out a project into your local working directory. This is done with the following command:
UNIX
svn checkout file:///repository_name/project/trunk project
Windows
svn checkout file:///d:/repository_name/project/trunk project
Network
svn checkout http://host_name/svn_dir/repository_name/project/trunk project
In these examples, project is the name of the directory where you want to store the checked out project on your local file system.
Getting a List of Projects - svn list
To get a list of the current projects stored in a repository, you can use the following command.
UNIX
svn list --verbose file:///repository_name/project
Network
svn list --verbose http://host_name/svn_dir/repository_name/project
This will show you a list of each project directory in that repository.
Reviewing Changes - svn status
To see what files you have changed or added to your checked out work, use the update command:
UNIX
svn status
This command will give you a listing of new files, files that have been changed, and files that have been deleted. New files or deleted files must be added or removed using the add and delete commands (see more below.)
Adding New Files and Directories - svn add
When you add a new file or directory to a project that has been checked out, you must tell Subversion to include that file or directory in its version control.
UNIX
svn add file_or_dir_name
Adding a directory will add the directory and all the files and directories in it. However, this does not add the file or directory to the repository, you must still issue a commit to update the repository.
Deleting Files and Directories - svn delete
If you can add, you can also delete. If you wish to remove a file your directory from be versioned, you use the delete command:
UNIX
svn delete file_or_dir_name
Like add, you must perform a commit before the file is actually deleted from the repository.
However, the delete command does have another option not found in add. With the delete command you can remove files or directories from the repository. For example, the following command would remove a project and all the files under it.
Network
svn delete -m "Deleting project dir" http://localhost/svn_dir/repository/project_dir
This version of the command comes in particulary useful if someone has accidently imported files into the wrong place (I wouldn't know about that myself of course.)
Committing Changes - svn commit
Once you have added, deleted, or changed files or directories, you can then commit those changes to the repository. This command is pretty straightforward:
Network
svn commit -m "Saving recent changes" http://localhost/svn_dir/repository/project_dir
Updating Your Local Files - svn update
If you have a set of files checked out and would like to update them to the most recent version of files in the repository, use the update command.
Network
svn update
If there are newer files in the repository, they will overwrite any files you have locally. Before using this command, you may want to use the svn diff command to find out what the differences are between your local files and the repository.
Tagging Projects or Creating Project Specific Versions
Subversion does not track the version numbers for individual projects automatically. Instead, it tracks each update to the repository and tracks the versions of these updates. To create interim project releases, you must create "Tags" which identify a specify version of a project. This is done by making a virtual copy of a project in the tags directory. For example:
svn copy http://host_name/repos/project/trunk http://host_name/repos/project/tags/0.1.0 -m "Tagging the 0.1.0 release of the project"
This creates a sort of bookmark or snapshot which records the current state of the project. Then, you can checkout the project in this state at any time by simply referring to that release number.
To get a list of the releases for a project.
svn list http://192.168.0.4/svn/repos/prj1/tags
0.1.0/
Then to check out a release you would type:
svn list http://192.168.0.4/svn/repos/prj1/tags/0.1.0
A 0.1.0\dir1
A 0.1.0\dir1\file3
A 0.1.0\dir1\file4
A 0.1.0\file1
A 0.1.0\file2
A 0.1.0\textfile.txt
A 0.1.0\file3
Checked out revision 13.
Since the project has been saved in the tags directory. Release 0.1.0 can be retrieved at any time in the future.
Basic Apache Setup
You must use Apache 2.0 to install Subversion. Just compile and copy or copy the Subversion Apache module into the Apache modules directory. The following two files must be uncommented or added to the httpd.conf file:
LoadModule dav_module modules/mod_dav.so
LoadModule dav_svn_module modules/mod_dav_svn.so
Next, you must setup a location directive in the httpd.conf file to associate a directory with Subversion repositories. This example uses the SVNParentPath setting to point to a parent directory which contains repository subdirectories. This is convenient as it allows you to add as many repositories as you need without having to restart Apache or modify the httpd.conf file.
<Location /svn>
DAV svn
# All repos subdirs of d:/svn
SVNParentPath D:/svn
</Location>
Note:When using Fink to install Subversion on Mac OS X, the Subversion Apache module is stored in the Fink package listing with the prefix: libapache2. The package full name is libapache2-mod-svn. If you are using Fink, it will automatically install the modules into the correct directory.
General Notes
Below are a list of notes from initial setup and testing.
· Subversion versions the repository, not individual projects. For example, I have two projects, project 1 and project 2, and check out each project when the current repository version is 3. I make changes to each project and commit those changes back to the repository. For each change, the revision number is incremented in the repository and its current version is now 5. The current revision of each project will also be 5 as they have no separate revision number.
· To setup the Subversion module on Apache for Windows, I had to give the Apache Service access to the local file system. This is done on Windows by setting up a login account for the service. Setup an account in the Users application in Control Panel, make sure to set the password. Once this is done, go to the Services tool in Control Panel. Change the login for the Service to the account you created. XP will automatically give the Login as a Service privilege to the account (the OS must do this as the tools are not available XP Home, only in XP Pro). Once you do this and start and stop the Apache Service, you should be able to read and write to the repository directories. Note: Setting up a log in account for a Service can create a security hole. Consider your security requirements before doing this.
· Individual files and directories that did not exist during the initial import, must be added individually using the svn add command.
Source: http://www.sunsource.net/scdocs/ddUsingSVN_command-line
Getting started with command-line Subversion
If you are participating in a development project that is using Subversion for version control, you will need to use Subversion to access and change project source files. You can browse the source code online to view a project's directory structure and files by clicking on the Subversion link in the left navigation pane for the project.
The Subversion page displays with three subdirectories: branches/, tags/, trunk/ and one README file. The README file gives a top level view of the Subversion repository. You can click on Access options to view the Subversion client setup instructions. You must have a Subversion client installed on your local machine.
Getting a local working copy for your project: svn checkout
To get a "working copy" of the latest source files, you must check out the source files, a process which copies the files onto your system from the repository. In your shell or terminal client, type:
svn checkout https://(projectname).(domain)/svn/(projectname)/(DIR) (projectname) --username [type-user-name-here]
Enter your user password when prompted. This should be the same password associated with your user account on this site. Not specifying the directory will checkout the entire project source code. You may want to checkout the 'trunk/' directory as it has the working 'www/' folder.
Switches: --revision (-r) REV, --quiet (-q), --non-recursive (-N), --username USER, --password PASS, --no-auth-cache, --non-interactive, --config-dir DIR
See Basic Work Cycle, Initial Checkout, Working Copies
Note: If your site is not SSL (Secured Socket Layer) enabled, use http instead of https to perform a Subversion operation. For example, to checkout the latest source code from a project's repository, use this command:
svn checkout https://(projectname).(domain)/svn/(projectname)/(DIR) (projectname) --username [type-user-name-here]
Working with files in the Subversion repository
Once you have checked out a local copy of the project repository, you can edit the existing files, create new files and directories, and delete files locally. Any changes you make affect only your local copies of the project files until you commit your changes back to the Subversion repository.
Adding files/directories from your working copy to the repository: svn add
You can add a new file to the repository after you have first created and edited it in your working directory or add a directory with or without it's contents using
svn add FILENAME/DIR.
This will add files/directories to your working copy and schedule them for addition to the repository. They will be uploaded and added to the repository on your next commit. If you add something and change your mind before committing, you can unschedule the addition using svn revert.
Switches: --targets FILENAME, --non-recursive (-N), --quiet (-q), --config-dir arg, --auto-props, --no-auto-props
See Examples on adding files/directories
Viewing the content of specific files with revision and author information: svn blame
You can view the author and revision information in-line for the specified files by typing:
svn blame FILENAME
Each line of text is annotated at the beginning with the author (username) and the revision number for the last change to that line.
Switches: --revision (-r) REV, --username USER, --password PASS, --no-auth-cache, --non-interactive, --config-dir DIR
Viewing the content of specific files: svn cat
At times, your working copy may be obsolete as compared to the repository or you may have modified your local working copy. In such cases, you will want to see the differences in the content of a specific file before you commit your changes or decide edit your working copy. Running svn cat FILENAME will automatically fetch the HEAD revision from the repository. This subcommand is mainly used to retrieve a file as it existed in an older revision number and display it on your screen. Alternatively, you can browse the source code of your project on this site to do the same.
Switches: --revision (-r) REV, --username USER, --password PASS, --no-auth-cache, --non-interactive, --config-dir DIR
Cleaning up the working copy: svn cleanup
Sometimes, you may get a "working copy locked" error. To remove the locks and recursively clean up the working copy, use svn update.
Switches: --diff3-cmd CMD, --config-dir DIR
See svn cleanup
Copying file or directory in a working copy or in the repository: svn copy
Your project may require you to make use of legacy documents. For example, you may want to use an already existing HTML file and use its code as reference to maintain the look and fee' of the product while creating fresh content. Instead of creating a file from scratch, you can simply copy this file using svn copy, save it under a different name and change the content. You can copy a file from the repository to your local working copy or vice versa. You can also copy files from within your local working copy. Subversion does not support cross repository copying. Use svn copy SRC DST to achieve this.
Switches: --message (-m) TEXT, --file (-F) FILE, --revision (-r) REV, --quiet (-q), --username USER, --password PASS, --no-auth-cache, --non-interactive, --force-log, --editor-cmd EDITOR, --encoding ENC, --config-dir DIR
See svn copy
Deleting a file or a directory from your local working copy: svn delete
You may want to delete unwanted files from your local working copy. Using svn delete FILENAME schedules it to be deleted. The actual deletion of the file in the repository takes place only when you commit.
Switches: --force, --force-log, --message (-m) TEXT, --file (-F) FILE, --quiet (-q), --targets FILENAME, --username USER, --password PASS, --no-auth-cache, --non-interactive, --editor-cmd EDITOR, --encoding ENC, --config-dir DIR
Viewing the differences between files: svn diff
You can use svn diff to display local modifications in a specified file in your working copy against the one in the repository. In the command prompt, type: