Subversion Usage and Administration Bradley W. Kimmel Natural Phenomena Simulation Group University of Waterloo March 23, 2009

Contents 1 Overview

1

2 Usage 2.1 Accessing the Repository . . . . . . . . . . . . 2.1.1 Locations . . . . . . . . . . . . . . . . . 2.1.2 Self-Signed Certificate . . . . . . . . . . 2.1.3 Authentication . . . . . . . . . . . . . . 2.2 Changing Your Password . . . . . . . . . . . . 2.3 Creating a Repository . . . . . . . . . . . . . . 2.4 Configuration Repository Privileges . . . . . . . 2.5 Groups . . . . . . . . . . . . . . . . . . . . . . . 2.6 Client Usage . . . . . . . . . . . . . . . . . . . 2.6.1 The Repository and Your Working Copy 2.6.2 Checking Out a Repository . . . . . . . 2.6.3 Updating Your Working Copy . . . . . . 2.6.4 Adding Files to the Repository . . . . . 2.6.5 Committing Your Changes . . . . . . . 2.6.6 Examining Your Changes . . . . . . . . 2.6.7 Conflict Resolution . . . . . . . . . . . . 3 Administration

1

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

2 2 2 2 2 2 3 4 6 6 7 7 7 8 8 10 11 11

Overview

This document describes how to use and maintain the Natural Phenomena Simulation Group’s subversion server. It does not cover usage of Subversion. For this, please refer to Version Control with Subversion, located at http://svnbook.red-bean.com/,

1

or to the documentation for your preferred Subversion client. Section 2 describes everyday usage of the system. Section 3 provides instructions for the server administrator.

2

Usage

The following describes everyday usage of the group Subversion server.

2.1 2.1.1

Accessing the Repository Locations

Individual Subversion repositories are located at https://boitata.cs.uwaterloo.ca/svn/repository name . Repository maintenance may be performed by accessing SVNManager, located at https://boitata.cs.uwaterloo.ca/svnmanager. 2.1.2

Self-Signed Certificate

Please note that boitata.cs.uwaterloo.ca uses a self-signed SSL certificate. Your browser or Subversion client will warn you about this. The authenticity of the certificate may be determined by verifying that the fingerprint matches the following SHA1 C6:12:BF:A1:D7:2F:0C:F0:CF:90:30:B9:C0:FE:CD:BF:6C:B0:8D:2C MD5 1A:0E:4B:E6:2F:B4:3E:87:A2:F8:B0:71:F2:8D:94:B5 2.1.3

Authentication

To access the repository or SVNManager, you will be required to log in using your UW user id. Your password will be assigned to you by the Subversion repository administrator. You may change your password by following the instructions in Section 2.2.

2.2

Changing Your Password

To change your password: • Log into SVNManager. • In the menu on the left, select User Admin. • Click the Edit button. You will be presented with the screen shown in Figure 1. 2

Figure 1: The SVNManager Change User screen. This dialog is used to change your password. • Enter your new password in the New password field and in the Repeat new password field. • Enter your old password in the Password field. • Click Confirm.

2.3

Creating a Repository

To create a repository: • Log into SVNManager. • In the menu on the left, select Repository Admin. • Click the Create button. You will be presented with the dialog indicated in Figure 2. • Enter a name and a brief description in the fields provided. • Click Confirm. This will create your new repository at. https://boitata.cs.uwaterloo.ca/svn/name .

3

Figure 2: The SVNManager Create New Repository screen. This dialog is used to add new repositories to the subversion server. The repository name and a brief description are required in this dialog. In this example, the new repository will be located at https://boitata.cs.uwaterloo.ca/svn/myrepo. Before your new repository may be used, however, you must set up permissions to make the repository accessible. Click on Go back to Repository Admin menu, or click on Repository Admin in the navigation menu. If this is your first repository, you will now see several additional options, including User Privileges and Group Privileges. Setting up privileges is described in detail in the next section. As a minimum, you will want to grant yourself read and write privileges, as well as read privileges to the npsg group, which includes all Natural Phenomena Simulation Group members.

2.4

Configuration Repository Privileges

Privileges may be assigned to individual users or to pre-configured groups. A listing of available groups is given in Section 2.5 Read or write privileges may be configured for each directory within a repository. By default, the privileges for a directory are inherited from that directories parent. To configure privileges: • Log into SVNManager. • Click on Repository Admin in the navigation menu on the left. • In the Repository administration menu, select either User Privileges or Group Privileges, depending on whether you wish to configure privileges for individual users or for pre-configured groups. • You will be presented with a list of the repositories which you have created, as shown in Figure 3. Click on the select link next to the repository for which you wish to configure privileges. You will now be presented with either the User Privileges or the Group Privileges dialog, as shown in Figure 4.

4

Figure 3: When you select User Privileges from the Repository Admin menu, you are presented with a list of the repositories which you own. A similar list will be presented if you select Group Privileges.

Figure 4: The User Privileges screen. This dialog is used to assign privileges to individual users for specified paths within your repository.

5

• Select the user or group for whom you wish to assign privileges. In the User Privileges dialog, you may also select all users (*). • Select the path for you which you wish the privilege to apply to. If you have just created this repository, you will only be able to assign privileges to the root directory (/). • Check the boxes indicating whether you would like to assign read access or write access. You may also leave both blank to explicitly deny access if the user has access to an ancestor. • Click Add. • Repeat as necessary, then click Done. You may also remove permissions by clicking on the remove link next to an existing permission.

2.5

Groups

Repository privileges may be assigned to individual users or to pre-configured groups of users. For instructions on configuring privileges for a repository, please refer to Section 2.4. The following groups are available for use on the NPSG Subversion server: npsg All Natural Phenomena Simulation Group (NPSG) members. wwwadmin Website administrator(s) for www.npsg.uwaterloo.ca.

2.6

Client Usage

This section provides a brief overview of basic daily usage of Subversion. It is not intended to be a complete guide for Subversion usage. For further information, see http://svnbook.red-bean.com/. Examples will be provided using the Subversion command line client and TortoiseSVN, a Windows client for Subversion. Further information about TortoiseSVN may be found in several languages at http://tortoisesvn.net/support. In particular, Chapter 5 provides an excellent guide to the most commonly used features. If you prefer to use an alternative Subversion client, please refer to the documentation for that client.

6

(a) Right click where you (b) Enter the location of the repository and the local directory would like to create your to create and click OK. working copy and select SVN Checkout.

Figure 5: Checking out a repository. 2.6.1

The Repository and Your Working Copy

To begin using a Subversion repository, you must first create a working copy. A working copy is a local copy of the files and folders in the repository against which you can make changes. In a traditional version control system, changes are serialized. Users must lock a file prior to making changes, preventing other users from making changes to the same file until the lock is released. While this is possible with Subversion, it is not typically done. Users may make changes to their local working copies freely and commit those changes when they are ready. When you update your working copy, Subversion takes care of merging your changes with changes made by others. In the rare event that a conflict occurs, Subversion provides facilities to allow the user to resolve the conflicts. 2.6.2

Checking Out a Repository

To create a working copy, use one of the following commands: svn checkout svn co If you are using TortoiseSVN, right click in the directory in which you would like to store your working copy and select SVN Checkout. Enter the URL of the repository and the local directory to create and click OK (see Figure 5). 2.6.3

Updating Your Working Copy

To receive changes made by others (or changes you have committed from a different machine), you must update your working copy. To update your working 7

Figure 6: To update your working copy, right click on the file or folder to update and select SVN Update. copy, issue the following command svn update where indicates the file or folder to update. If this argument is omitted, everything under the current folder will be updated. If you are using TortoiseSVN, right click on the folder or file you wish to update and select SVN Update (Figure 6). 2.6.4

Adding Files to the Repository

For files and folders to be stored in the repository, they must first be added. To add a new file or folder to the repository, issue the following command. svn add If a folder is provided, the entire directory tree rooted at that folder will be added. If you are using TortoiseSVN, right click on the file or folder to be added and select TortoiseSVN → Add. You will be presented with a dialog allowing you to select and deselect files to be added. When you are ready, click OK (see Figure 7). At this point, the files or folder are scheduled to be added to the repository. They will not be added until you commit. Committing changes is described in the next section. 2.6.5

Committing Your Changes

To commit your changes to the repository, issue one of the following commands svn commit svn ci

8

(a) Right click on the file or folder to be added and select tt TortoiseSVN → Add.

(b) Select the files you wish to add and click OK.

Figure 7: Adding files and folders to the repository.

9

(a) Right click on the file or (b) Enter a log message, select the files you wish to commit, folder to commit and select and click OK. SVN Commit.

Figure 8: Committing changes to the repository where indicates the file or folder whose changes to commit to the repository. If the argument is omitted, all files and folders under the current directory will be committed. After issuing this command, your default text editor will be opened. Enter a log message, then save and exit to complete the commit. If you exit without saving, you will be asked whether you wish to abort the commit or continue without a log message. If you are using TortoiseSVN, right click on the file or folder under which you wish to commit changes, and select SVN Commit. You will be presented with a dialog in which you can enter a log message, as well as select and deselect files to be committed. When you are prepared to commit, click OK (see Figure 8). 2.6.6

Examining Your Changes

To view the status of a file or folder, issue one of the following commands. svn status svn st If the argument is omitted, the status will be indicated for all files and folders under the current directory. The output from this command will be a list 10

Indicator A C D M ?

Description Added Conflicted Deleted Modified Unversioned (not in repository)

Table 1: The meaning of the most common status indicators provided by the svn status command.

Figure 9: Overlay icons indicate the status of files and folders. of the files preceeded by a letter indicating the status of the file. Table 1 describes the meaning of the most common status indicators. If you are using TortoiseSVN, the files and folders will have an overlay indicating the status, as shown in Figure 9. More detailed information about the status of the files and folders in your working copy is available by selecting TortoiseSVN → Check for modifications. To view a detailed listing of all the changes to a file or all the files in a folder, issue the following command. svn diff If you are using TortoiseSVN, right click on a changed file and select TortoiseSVN → Diff (see Figure 10). 2.6.7

Conflict Resolution

To be written.

3

Administration

To be written.

11

Figure 10: To view the changes made locally to a file, right click on the file and select TortoiseSVN → Diff.

12