Subversion Handbook

SUBVERSION HANDBOOK

Siddharth Gandhi Feb 2009

Disclaimer: This handbook has been compiled from various sources for the benefit of KBACE India employees. The text in this document belongs to their respective owners. But I solely take the complete ownership for any typos, erroneous text or steps in this document.

Feel free to share your comments/view/feedback with me

This handbook broadly covers the following topics: 1. 2. 3. 4. 5.

Introduction to Subversion (Why Subversion and version control concepts) Using Subversion (commands, basic usage, branching etc) Integration with tools - Oracle JDeveloper and SQL developer Subversion client configuration Subversion Guidelines (for KTPL employees)

TABLE OF CONTENTS

SUBVERSION HANDBOOK....................................................................................1 INTRODUCTION TO SUBVERSION ................................................................................................................. ...........................3 What is Subversion?.............................................................................................. ...........3 Why Subversion? ........................................................................................................ .....4 VCS Concepts............................................................................................................. ......5 Installing Subversion client(s) .............................................................. ...........................6 Test Drive.......................................................................................................... ...............7 USING SUBVERSION...................................................................................................... ..............10 Using Subversion client(s)................................................................................... ...........10 Basic versioning workflow........................................................................... ...................11 Quick Reference: SVN Commands............................................................................. .....12 Merging and Conflict resolution................................................................................... ...18 SVN with SQL Developer....................................................................... .........................21 SVN with JDeveloper..................................................................................................... ..23 SUBVERSION GUIDELINES................................................................................................ ..............35 REFERENCES ............................................................................................................... ...........................37

Listed Figures

FIGURE 1 [SUBVERSION LEADERSHIP].................................................................4 FIGURE 2 [TORTOISESVN CONTEXT MENU]..............................................7 FIGURE 3 [SVN VIEW-ONLY WEB INTERFACE]...........................................8 FIGURE 4 [TORTOISESVN REPOSITORY URL].........................................................8 FIGURE 5 [TORTOISESVN REPOSITORY BROWSER]................................................9 FIGURE 6 [TORTOISESVN AUTHENTICATION]........................................................9 FIGURE 7 [TORTOISESVN COMPLETE CONTEXT MENU]........................................14

FIGURE 8 [BRANCHING]....................................................................................18 FIGURE 9 [SVN CONFIGURATION IN SQL DEVELOPER].........................................22 FIGURE 10 [SVN WITH SQL DEVELOPER]............................................................23 FIGURE 11 [SVN CONFIGURATION IN JDEVELOPER].............................................23 FIGURE 12 [SVN SETUP IN JDEVELOPER]............................................................24 FIGURE 13 [BROWSING SVN IN JDEVELOPER].....................................................25 FIGURE 14 [SVN DIRECTORY IMPORT IN JDEVELOPER].........................................26 FIGURE 15 [DIRECTORY STRUCTURE OF CHECKOUT FILES IN JDEVELOPER]...........27 FIGURE 16 [PENDING CHANGES WINDOW IN JDEVELOPER]..................................28 FIGURE 17 [COMMIT WORKING COPY FROM JDEVELOPER]...................................29 FIGURE 18 [ADDING NEW FILE TO SVN FROM IN JDEVELOPER]............................30 FIGURE 19 [PENDING CHANGES WINDOW IN JDEVELOPER]..................................31 FIGURE 20 [PREFERENCE SETTING FOR PENDING CHANGES IN JDEVELOPER]........32 FIGURE 21 [ADDING SVN PROPERTY IN JDEVELOPER]..........................................32

INTRODUCTION TO SUBVERSION

WHAT IS SUBVERSION? What will be sufficed to say in here is that Subversion (SVN) is a Version Control Software (VCS) just like Visual SourceSafe (VSS) which we have been using for some time now. But still, here's your Step 0: Google, What is Subversion? A good VCS does the following:

o o o o o o o o

Backup and Restore. Files are saved as they are edited, and you can jump to any moment in time. Need that file as it was on Feb 23, 2007? Synchronization. Let people share files and stay up-to-date with the latest version/changes. Short-term undo. Playing with a file and messed it up? Throw away your changes and go back to the "last known good" version in the database. Long-term undo. Sometimes we mess up bad. Suppose you made a change a year ago, and it had a bug. Jump back to the old version, and see what change was made that day. Track Changes. As files are updated, you can leave messages explaining why the change happened (stored in the VCS, not the file). This makes it easy to see how a file is evolving over time, and why. Track Ownership. A VCS tags every change with the name of the person who made it. Helpful for blame-storming or giving credit. Sandboxing, or insurance against yourself. Making a big change? You can make temporary changes in an isolated area, test and work out the kinks before "checking in" your changes. Branching and merging. A larger sandbox. You can branch a copy of your code into a separate area and modify it in isolation (tracking changes separately). Later, you can merge your work back into the common area.

Now since we know what a good VCS is suppose to do, why should we propose Subversion? What's wrong with current instance of VSS?

Why Subversion?

Figure 1 [Subversion Leadership]

1. Subversion is the market leader. Refer the Figure 1 above from Forrester report 2.

Subversion is free of cost and is open source

3. Subversion works over the Internet (i.e. can be accessed from browser), have a command line interface, and has many choices for GUI clients for working with repositories

4. Subversion supports offline access for many of its operations like diff, status etc. So, you don’t need to be on network! Subversion has atomic commits i.e. committing a group of files succeeds or fails as a group [just like we have in Oracle database transactions] 6. Subversion support 'hooks' like pre-commit, pre-lock etc (just like trigger in Oracle) 7. Subversion supports file renames, deletes, and moves that preserve history. 8. Subversion allows anonymous, read-only access. 9. Subversion is integration with JDeveloper and SQL Developer 10. Efficient...transfer only the 'diffs' across network and not the complete file 5.

11. Faster, our pilot results show it...it works on Dial-up connection! 12. Subversion has better and faster support for branching and tagging. 13. Subversion can be 'hooked' with third-party applications like Checkstyle to automate code reviews etc 14. Many third party products available to generate reports, to build plugins etc 15. Directories, copy, renames everything is versioned 16. Subversion has better support for multiple checkouts 17. Subversion is MIME type-aware (if you check in a binary file, subversion will not mess around with it) 18. Subversion supports file properties meta-data (both arbitrary, like comments, and specified, like the MIME type) 19. Plenty of documentation, huge open community support, hundreds of tutorials etc 20. Works on many operating systems including Unix and Windows Our current VCS, Visual SourceSafe does not have support or is deficient in many of the features mentioned above [Have you ever tried working on VSS from home?] And to top it all, Microsoft itself doesn’t use it and have not made any changes to VSS for last 6 years! Read what it has to say about how VSS can get corrupted: o o o o o o o

Power loss System hangs (stops responding) User terminates a long process Bad network connections Running out of disk space Network problems Operating system problems

VCS CONCEPTS Most version control systems involve the following concepts, though the exact names may be different. Setup

o o o o o

Repository (repo): The database storing the files. Server: The computer storing the repo. Client: The computer connecting to the repo. Working Set/Working Copy: Your local directory of files, where you make changes. Trunk/Main: The "primary" location for code in the repo. Think of code as a family tree — the "trunk" is the main line.

Basic Actions

o o o o o o o o o

Add: Put a file into the repo for the first time, i.e. begin tracking it with Version Control. Revision: What version a file is on (v1, v2, v3, etc.). Head: The latest revision in the repo. Check out: Download a file from the repo. Check in: Upload a file to the repository (if it has changed). The file gets a new revision number, and people can “check out” the latest one. Checkin Message: A short message describing what was changed. Changelog/History: A list of changes made to a file since it was created. Update/Sync: Synchronize your files with the latest from the repository. This lets you grab the latest revisions of all files. Revert: Throw away your local changes and reload the latest version from the repository.

Advanced Actions

o o o o o o o o

Branch: Create a separate copy of a file/folder for private use (bug fixing, testing, etc). Branch is both a verb ("branch the code") and a noun ("Which branch is it in?"). Diff/Change/Delta: Finding the differences between two files. Useful for seeing what changed between revisions. Merge (or patch): Apply the changes from one file to another, to bring it up-to-date. For example, you can merge features from one branch into another (In VSS this is called Reverse Integrate and Forward Integrate) Conflict: When pending changes to a file contradict each other (both changes cannot be applied). Resolve: Fixing the changes that contradict each other and checking in the correct version. Locking: “Taking control” of a file so nobody else can edit it until you unlock it. Some version control systems use this to avoid conflicts (like VSS). Breaking the lock: Forcibly unlocking a file so you can edit it. It may be needed if someone locks a file and goes on vacation! Check out for edit: Checking out an “editable” version of a file. Some VCSes have editable files by default, others require an explicit command.

And like every application, Subversion too has few nuances. Top 3 of these are:

1. Global revision Number- All changes to the repository are atomic; either all parts of a

change go in, or none of them do. As a result, there's a single repository-wide revision number, which describes the state of the entire tree. So when you refer to "version 247 of foo.java," it's really more correct to say "foo.java as it exists in revision 247 of the repository." This is very unlike erstwhile VCS applications where revision numbers were per-file. For instance, you check in MyVoImpl.java and it currently stands at version 12. Assume someone else checkins another file, TheirVOImpl.java. He will be assigned version 13 irrespective of what the file's last revision number was. And now if you checkin MyVoImpl.java, it will be assigned version 14

2. No default locking - A file is not automatically locked when you checkout. You have to

specifically lock it. This is a feature to do away with administrative 'unlock-my-file' issues and not a bug :-) Subversion follows, 'Copy-Modify-Merge' solution unlike VSS which uses 'Lock-Modify-Unlock' approach

3. Check out a single file- Subversion does not support checkout of a single file, it only

supports checkout of directory structures. However, we can use svn export to export a single file. This will retrieve the file's contents; it just won't create a versioned working copy.

INSTALLING SUBVERSION CLIENT(S) Now since we know basic VCS concepts and benefits of Subversion, let’s install a Subversion client. Refer the Software section below to copy the install files for command-line client (Collabnet Subversion) and/or GUI client (TortoiseSVN). Double click the .exe file to install them.

Note: Users are free to use any other SVN clients of their choice. Refer the References section for the same. On successful install of TortoiseSVN GUI client, you will see a new context-menu option (right click on

any file/folder as shown in Figure 2 below)

Figure 2 [TortoiseSVN context menu] To validate the command line client install, type svn help on command prompt. [svn help prints all the primary SVN commands]

TEST DRIVE Now let’s get a feel of Subversion.

ACCESSING SVN REPOSITORIES VIA BROWSER

To view all the existing repositories via browser, kindly access http://ktpl-lt11/websvn/index.php and surf around as desired. Or click here to view a 'Project RATS' repository. The web interface is very intuitive and feature of RSS, Logs, Compare etc are simple to examine. testbed1 and testbed2 are the test/sample repository and users are free to experiment with it [Just don't delete it!] Note: This web interface is view-only and authentication hasn't been enabled

Figure 3 [SVN view-only web interface]

ACCESSING SVN REPOSITORIES VIA GUI CLIENT

You can also access it via TortoiseSVN GUI client by providing the sample repository path, http:\\ktpllt11\svn\testbed1\ after selecting the Repo-browser option in the context menu. {Refer Figure 2 above and Figure 4 below}

Figure 4 [TortoiseSVN repository URL]

Figure 5 below shows one of the Subversion repositories using TortoiseSVN client

Figure 5 [TortoiseSVN Repository Browser]

USERNAME/PASSWORD The username/password are the same as of your Windows login, but prefixed with the DOMAIN_NAME. For instance, user sgandhi will login as bangalore.Bedford.local/sgandhi (case sensitive), providing the associated Windows password. Note: You may be prompted to enter your credentials thrice. To avoid the same you can check the option, Save Authentication on the login prompt window as displayed in the Figure 4 below

Figure 6 [TortoiseSVN Authentication]

ACCESSING SVN REPOSITORIES VIA COMMAND LINE The svn list command will list all the contents of the specific repository

$ svn list http://ktpl-lt11/svn/rats /branches /tags /trunk $

USING SUBVERSION In this section we will look into,

• • • •

Using Subversion clients to perform basic operations Branching and Tagging Merging and conflict resolution Locking

USING SUBVERSION CLIENT(S) Before we look into using the SVN clients, let’s understand two primary parts of SVN commands i.e. repository URL and revision notations.

1. SUBVERSION REPOSITORY URLS Subversion provides several ways to access a repository. Users at KTPL will only be using http:// and svn:// Table below breaks down the components that make up the Subversion URLs.

URL

Laye Host r

Repository

Path

http://ktpllt11/svn/repos/trunk/README.txt®

DAV ktpl-lt11

/repos

trunk/README.txt

svn://ktpl-lt11/repos/sandbox/tags/Rel32/BugFixes

SVN ktpl-lt11

/repos/sandbo tags/Relx 32/BugFixes

Note: /svn/ is the context configured to route it via Apache server. This is not mandatory but configured as per the best practices

2. REVISION SPECIFICATIONS NOTATIONS In most cases, you specify revisions by using the --revision (or -r) keyword, followed by the revision (e.g., svn update --revision 10). If the command refers to a range of revisions, the revisions are separated by colons, as in svn diff --revision 9:10, where you're indicating that the svn diff command should start at revision 9 and end at revision 10. In a few cases, the revision can be associated with the URL directly by appending it and delimiting it with a @. For example, file:///c:/repos/projects/trunk/final@4747 refers to /trunk/final as it existed in revision 4747. Table below highlights the same.

Revision Specification

Meaning

10

Literal revision 10

10:20

A range of revisions from 10 to 20

HEAD

Youngest revision in the repository

BASE

Current revision of the working copy

COMMITTED

Revision in which an entry was last changed

PREV

Revision before the last revision in which the item was changed

{2007-03-25}

Revision the item was at on March 25, 2007

{2007-02-27 10:00}

Revision the item was on at 10:00 on February 27, 2007

BASIC VERSIONING WORKFLOW Let’s see what usually will be the basic flow for any versioned application

REPOSITORY FOR YOUR PROJECT Before we can checkin/checkout files, we need a SVN repository! If it’s already created for you, we just need the repository access URL and if it is not, we need to create a new repository using svnadmin utility. Now since SVN server owner or IT Admin have the privileged access to svnadmin program, we need to raise a new repository-creation request to them. After ensuring that you have the access to the desired repository, create the necessary directories under it (refer Subversion Guidelines section).

Now considering that you’ll have files/folders to be imported to this repository, begin by organizing your local data into a single directory called myproject (or whatever you wish).

IMPORT THE EXISTING DIRECTORY TO SUBVERSION REPOSITORY $ svn import c:/myproject http://ktpl-lt11/svn/myproject/trunk -m "Initial import"

The flag -m is the log message Note: The original c:/myproject directory is unchanged; Subversion is unaware of it. In fact, you can even delete that directory if you wish. To start manipulating repository data, you need to create a new "working copy" of the data, a sort of private workspace. Ask Subversion to "check out” a working copy of the myproject/trunk directory in the repository:

INITIAL CHECKOUT OF A PROJECT

To checkout the main trunk of the project, the following command will do,

svn checkout http://ktpl-lt11/svn/myproject/trunk myproject_svn This will create a subdirectory myproject_svn containing the latest revision of the project. Working Copy

Now we have a personal copy of part of the repository in a new directory named myproject_svn. We can edit the files in our working copy and then commit those changes back into the repository.

1.

Go to your working copy and edit a file's contents in your favourite editor.

2. Run svn diff to see unified diff output of your changes. 3. Run svn commit to commit (i.e. checkin) the new version of your file to the repository. 4. Run svn update to bring your working copy "up to date" with the repository. This concludes the basic workflow of application versioning. Refer the next section for many other SVN commands QUICK REFERENCE: SVN COMMANDS add

Adds files and directories.

blame

(praise, annotate) Shows author and revision information in-line for the specified

files or URLs. cat

Outputs the contents of the specified files or URLs

checko (co) Checks out a working copy from a repository ut cleanup Recursively clean up the working copy. commit (ci) Send changes from your working copy to the repository. copy

(cp) Copy a file or directory in a working copy or in the repository.

delete

(del, remove, rm) Delete an item from a working copy or the repository.

diff

(di) Display the differences between two paths.

export

Exports a clean directory tree.

help

Prints help text.

import

Recursively commit a copy of local dir into a repository.

info

Print information about PATHs.

list

(ls) List directory entries in the repository.

log

Displays commit log messages.

merge

Apply the differences between two sources to a working copy path.

mkdir

Create a new directory under version control.

move

(mv, rename, ren) Move a file or directory.

revert

Undo all local edits.

status

(stat, st) Print the status of working copy files and directories.

switch

(sw) Update working copy to a different URL.

update (up) Updates your working copy.

All the above commands can be ‘executed’ using a TortoiseSVN GUI client by right clicking the file and selecting the specific options (commit, update, diffs etc). In the Figure 7 below we can see the context menu for various available commands. As can also be seen is the file icon with red exclamation mark for ResourceAllocation.jws file as that file has been

modified.

Figure 7 [TortoiseSVN complete context menu]

SVN FILE STATUS FLAGS Subversion command line client displays file status when various commands like svn status or svn update are issued. They are as follows U A D R G C

File was updated File was added File was deleted File was replaced File was merged Conflicting changes

? !

Resource is not under version control Resource is missing or incomplete (removed by another tool than Subversion)

SVN PROPERTIES In addition to versioning our directories and files, Subversion provides interfaces for adding, modifying, and removing versioned metadata on each of our versioned directories and files. We refer to this metadata as properties, and they can be thought of as two-column tables that map property names to arbitrary values attached to each item in your working copy.

Generally speaking, the names and values of the properties can be whatever you want them to be, with the constraint that the names must be human-readable text. And the best part about these properties is that they, too, are versioned, just like the textual contents of your files. You can modify, commit, and revert property changes as easily as committing textual changes. And you receive other people's property changes as you update your working copy. Alongside these user defined properties, SVN also have some pre-defined special properties. And one of the is svn:keywords Special Properties Subversion has seven special pre-defined properties: •

svn:executable

•

svn:mime-type

•

svn:ignore

•

svn:keywords

•

svn:eol-style

•

svn:externals

•

svn:special

The following section below briefs upon one of them, svn:keyword . We can use it to update keywords like $Id$ etc

svn:keywords This property allows Subversion to substitute keywords—pieces of useful, dynamic information about a versioned file—into the contents of the file itself. Subversion defines the list of keywords available for substitution during commit. That list contains the following five keywords, some of which have aliases that you can also use: $Date$ date of the last modification $Rev$ revision number $Author$ the last user who changed the file $URL$ full URL to the latest version of the file in the repository $Id$ compressed combination of keywords above For example, say we have a versioned file named MyVOImpl.java that looks like this:

/** This is the implementation class. $Id$ $Rev$ */ public String getUsername(String userid)

…………………………… ……………………. With no svn:keywords property set on that file, Subversion will do nothing special when you checkin. Now, let's enable substitution of the Id keyword. $ svn propset svn:keywords "Id Author" MyVOImpl.java property 'svn:keywords' set on ‘MyVOImpl.java' $ Now you have made a local property modification on the MyVOImpl.java file. Note: The file contained a keyword anchor for the Rev keyword, yet we did not include that keyword in the property value we set. Subversion will happily ignore requests to substitute keywords that are not present in the file, and will not substitute keywords that are not present in the svn:keywords property value. Immediately after you commit this property change, Subversion will update your working file with the new substitute text. Instead of seeing your keyword anchor $Id$, you'll see its substituted result. /** This is the implementation class. $Id: 2009-01-22 21:42:37 -0700 (Mon, 22 Jan 2009) 24 sgandhi $ $Rev$ */

public String getUsername(String userid) …………………………… ……………………. If someone else now commits a change to MyVOImpl.java, your copy of that file will continue to display the same substituted keyword value as before—until you update your working copy. At that time the keywords in your MyVOImpl.java file will be re-substituted with information that reflects the most recent known commit to that file. Automatic property setting In your SVN client configuration file, which usually is at the location %USERPROFILE%\Application Data\Subversion\config 1) Uncomment the following line and change the value from no to yes, enable-auto-props = yes 2) Insert the following line at the end of configuration file to enable parsing of .java files *.java = svn:keywords=Id Date LastChangedBy Revision Note: SVN values in Windows Registry can also be utilised to do client configurations. Refer here

BRANCHES AND TAGS Branching and tagging are concepts common to almost all version control systems. Actually there's no difference between tags and branches in Subversion. Both are just ordinary directories that are created by copying. The only reason a copied directory is a "tag" (or it is a "branch") is because humans have decided to treat it that way: as long as nobody ever commits to the directory, it forever remains a snapshot. If people start committing to it, it becomes a "branch". Generally, it's not recommended to commit any changes to a tag. If you need to make changes to a tagged release, create a new branch from the tag first and modify the branch. It is generally known that in SVN tags and branches realization is implemented by copying the source code tree to the repository. SVN uses so-called "cheap copies". Instead of making a real copy, the internal link will be created, pointing to a specific tree/revision. As a result branches and tags are very quick to create, and take up almost no extra space in the repository. BRANCHING Branch is a separate line of development that exists independently of another line. It always begins life as a copy of something, and moves on from there, generating its own history. Branches are created mainly for the following purposes: independent development of the current revision with the correction support in the release version, long-term independent work, using of source codes of other developers. The Figure 8 below shows various steps a developer usually perform for branching. Stage 0: No branch exists Stage 1: Branch with a name ‘my-calc-branch’ created copying the latest code from trunk Stage 2: Changes occur in ‘my-calc-branch’ and trunk directory independent of each other

Stage 0: No branches

Stage 1: Branch created

Stage 2: Branch/Trunk modified

Figure 8 [Branching] Branching workflow 1. 2. 3.

4. 5. 6. 7.

The project is developed. At the time of the project release, the branch 'Release1' is created. The project development is continued in trunk. At some moment it becomes necessary to fix bugs in the released version. Now get the branch 'Release1', make corrections, checkin back the modifications. Get the main branch/trunk again. Continue the project development. Point 4 can take place several times. A new release is ready. Merge modifications of the branch "Release1" with the main branch. Create the branch "Release2".

TAGGING A tag is just a "snapshot" of a project in time. In Subversion each revision is a snapshot of the repository filesystem after each commit, and it can be used as a tag. But people often want to give some human-friendly names to tags, like release-1.0. Tag is a named snapshot, a symbolical connection with the specified revision of a project.

MERGING AND CONFLICT RESOLUTION TODO LOCKING As stated previously, with Subversion a file is not automatically locked when you checkout. You have to specifically lock the file using svn lock command. The locking command will fail if the file had already been locked by someone else or if the working copy of the file had been out of date (run svn update first) Note: Subversion does not currently allow locks on directories Remember, Subversion follows 'Copy-Modify-Merge' solution unlike VSS which uses 'Lock-ModifyUnlock' approach When referring to Subversion's locking feature, we’re considering an ability to lock a versioned file (claiming the exclusive right to modify the file), to unlock that file (yielding that exclusive right to modify), to see reports about which files are locked and by whom, to annotate files for which locking before editing is strongly advised, and so on. DISCOVERING LOCKS The easiest way is to run svn status –u

$ svn status -u M M

O

23

bar.java

32

raisin.jpg

*

72

foo.java

Status against revision:

105

$ In this example, we can see not only our copy of foo.java is out of date, but also that one of the two modified files we plan to commit is locked in the repository. The ‘O’ symbol stands for “Other,” meaning that a lock exists on the file and was created by somebody else. If we were to attempt a commit, for instance on raisin.jpg, the lock on this file would prevent it. To know who made the lock, when, and why, we use svn info $ svn info http://ktpl-lt11/svn/repos/myproject/raisin.jpg Path: raisin.jpg Name: raisin.jpg URL: http://ktpl-lt11/svn/repos/myproject/raisin.jpg Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec Revision: 105 Node Kind: file Last Changed Author: sgandhi Last Changed Rev: 32 Last Changed Date: 2006-01-25 12:43:04 -0600 (Sun, 25 Jan 2006) Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b Lock Owner: snarasimhan Lock Created: 2006-02-16 13:29:18 -0500 (Thu, 16 Feb 2006) Lock Comment (1 line): Need to make a quick tweak to this image. $ So in this particular example, sgandhi can see that snarasimhan locked the file on February 16 to “make a quick tweak.” It being June, sgandhi suspects that he probably forgot all about the lock. sgandhi might call snarasimhan to complain and ask him to release the lock. If snarasimhan is unavailable, sgandhi might try to forcibly break the lock himself or ask an administrator to do so. BREAKING AND STEALING LOCKS In Subversion's default configuration state, locks can be released not only by the person who created them, but by anyone. When somebody other than the original lock creator destroys a lock, we refer to this as breaking the lock. The administrator can use svnlook and svnadmin programs to display and remove locks directly from the repository.

$ svnadmin lslocks /var/svn/repos Path: /project2/images/banana.jpg UUID Token: opaquelocktoken:c32b4d88-e8fb-2310-abb3-153ff1236923 Owner: frank Created: 2006-06-15 13:29:18 -0500 (Thu, 15 Jun 2006) Expires: Comment (1 line): Still improving the yellow color.

Path: /myproject/raisin.jpg UUID Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b Owner: snarasimhan Created: 2006-02-16 13:29:18 -0500 (Thu, 16 Feb 2006) Expires: Comment (1 line): Need to make a quick tweak to this image.

$ svnadmin rmlocks /var/svn/repos /myproject/raisin.jpg Removed lock on '/myproject/raisin.jpg'. $ The option to allow users to break each other's locks over the network is to pass the --force to the svn unlock command: $ svn status -u M M

23 bar.java O

32 raisin.jpg *

72

foo.java

Status against revision:

105

$ svn unlock raisin.jpg svn: 'raisin.jpg' is not locked in this working copy $ svn info raisin.jpg | grep URL

URL: http://ktpl-lt11/svn/repos/myproject/raisin.jpg $ svn unlock http://ktpl-lt11/svn/repos/myproject/raisin.jpg svn: Unlock request failed: 403 Forbidden (http://ktpl-lt11) $ svn unlock --force http://ktpl-lt11/svn/repos/myproject/raisin.jpg 'raisin.jpg' unlocked. $ In the above example we can see, user sgandhi initial attempt to unlock failed because he ran svn unlock directly on his working copy of the file, and no lock token was present. To remove the lock directly from the repository, he needs to pass a URL to svn unlock. His first attempt to unlock the URL fails, because he can't authenticate as the lock owner (nor does she have the lock token). But when he passes --force, the authentication and authorization requirements are ignored, and the remote lock is broken. Simply breaking a lock may not be enough. You may wish to acquire the lock yourself after breaking it i.e. to steal the lock. It involves breaking and relocking the file all in one atomic step. To do this, pass the --force option to svn lock: $ svn lock raisin.jpg svn: Lock request failed: 423 Locked (http://ktpl-lt11) $ svn lock --force raisin.jpg 'raisin.jpg' locked by user 'sgandhi'. $ After breaking the lock, the erstwhile lock owner lock token will be defunct. If the repository lock was broken, then svn status -u displays a B (Broken) symbol next to the file. If a new lock exists in place of the old one, then a T (sTolen) symbol is shown.

INTEGRATION WITH TOOLS In this section we will learn how to integrate Subversion with,

• • •

Oracle SQL Developer IDE Oracle JDeveloper, and Checkstyle (client validation)

SVN WITH SQL DEVELOPER From SQL Developer IDE menu, select View>Versioning Navigator

Figure 9 [SVN configuration in SQL Developer] If you are connecting to an existing repository, expand the Subversion node and browse the objects in your repository. If you have just created your repository, populate it by importing files:

1. 2. 3. 4. 5. 6.

In the File Navigator, navigate to a folder you want to bring under version control; for this example, select the c:\myprojects. From the main menu, select Versioning -> Subversion -> Import Files. Using the wizard, select the Repository Connection you created. Click Next to navigate to the Source panel. Click Browse to navigate to c:\myprojects. Click Next to go to the Filters panel, and click Next again to go to the Options panel. Ensure that Perform Checkout is selected. Click Next, review the summary, and click Finish. In the Versioning Navigator, select the newly created connection and click the Refresh icon.

You can now see the files in your Subversion repository. These are read-only files and display the current state of your files. Click the File Navigator tab, click the Refresh button, and review the contents of the c:\myproject folder. These files are now marked as versioned, and the version number is displayed. You can open, edit, and save (commit to check in) these files. You can select any versioned file and select Versioning -> Subversion to review the versioning options available. Now open one of the .sql file you worked on earlier. Make a few changes or add a comment, and select the History tab to review the differences between the original file and any changes you have made. Right-click the file in the History tab, and review the versioning options available to you (as shown in Figure 10). Save the file and the changes. Note the new overlay icon on the file in the File Navigator. Right-click the filename, and select Commit to check the file in

Figure 10 [SVN with SQL Developer]

SVN WITH JDEVELOPER

Note: SVN 1.5 and above is compatible with JDeveloper 11g. Use SVN version 1.4 with JDeveloper 10g

STEP 1) ACTIVATING SUBVERSION IN JDEVELOPER To place the application under version control, ensure that the current application is the current one selected in Oracle JDeveloper; then select from menu, Versioning>Version Application>Subversion

Figure 11 [SVN configuration in JDeveloper]

STEP 2) SVN REPOSITORY CONNECTION From JDeveloper IDE menu, select View>Versioning Navigator>Subversion>New Repository Connection and provide the SVN connection details to the wizard.

Figure 12 [SVN setup in JDeveloper]

If you are working on a new development you may have to create a connection to SVN repository and carry out the initial import/checkout of your application to the SVN repository (Step 3).

STEP 3) IMPORT AND/OR CHECKOUT We import to specify which directory in the repository is to hold the application. As mentioned earlier, since the trunk directory is where the main line of development occurs, that’s the destination of our imported application

In JDeveloper you can use the Versioning Navigator -> Subversion to add a new folder to your repository ready to house your new application directly (see Figure 13 below) or you can create the folder whilst using JDeveloper’s Import Wizard

Figure 13 [Browsing SVN in JDeveloper]

The wizard takes you through the steps to import your initial application into the repository. The easiest way to open the wizard is to select Versioning -> Import Files from the application dropdown menu. Now you can create the folder to hold your source code, comment your import, exclude any files or file patterns from the initial import (see Excluding Files section and Figure 14 below) and automatically checkout the code to your local working copy ready for your development work.

Figure 14 [SVN directory import in JDeveloper]

When you import your application into Subversion, the original files on your local disk remain just a bunch of local files; the local copy has no connection to the repository at all (it’s just a local copy and not a Subversion “working copy”).

Once the import is complete, you should see the progress of the checkout operation (if you checked the check box to automatically perform a checkout after the import). Once the checkout finishes, have a look at Application Navigator (you may need to click the refresh icon first). You should now see a lot more information, as shown here:

If we are new to an existing project, we can checkout the project from the repository by selecting the Checkout option i.e. Versioning Navigator -> Checkout

Figure 15 [Directory structure of checkout files in JDeveloper]

•

Each project shows the repository from which the working copy originated (jstegemalap.cisgi.com in this screen shot).

•

Each file has a “state overlay” icon in the lower left, showing the status of the working copy file. In this case, all the icons are circles, indicating that the files have had no local modifications since they were checked out.

•

Each file shows its version number (2 in this screen shot). The files are at version 2 (and not 1) because the creation of the repository was version 1 and the import of the application was version 2.

WORKING COPY Using JDeveloper’s integrated SVN Navigator and the Application Navigator it is easy to make best use of the SVN concept Working Copy. To work on an application, you check it out from the SVN repository. This copy becomes your working copy. In addition to the standard Commit and Update SVN commands, JDeveloper provides additional commands Commit Working Copy and Update Working Copy. These commands ensure that all the files in your working copy are committed/updated whatever node in the Application Navigator you invoked the command from. Figure 2 shows the Commit Working Copy menu being invoked from the Region2 node in the Application Navigator. After making the change and saving the EO, you’ll notice a few changes reflected in Oracle JDeveloper. First, the state overlay icon for the Regions EO has changed to an asterisk, telling us that we have local changes that have not been saved (or “committed”) to the Subversion repository

Pending Changes consists of three tabs and provides information on individual applications and projects open in your IDE that are under version control.

•

The Outgoing Changes tab shows you all files that have been modified and need committing to the repository. Figure 3 shows 1 file with an outgoing changes in the StoreFrontUI project.

•

The Candidates tab shows you all files that you have added to the working copy of your versioned applications and projects (open in the IDE) since you last committed. These files need to be added to your SVN repository using the Add command – either from the Add button in the Candidates tab or through the Application Navigator (see Excluding Files)

•

The Incoming Changes tab shows you all the files that have been committed to the SVN repository by another member of the development team since you last committed your changes. (See Comparing Versions)

Figure 16 [Pending Changes window in JDeveloper]

Figure 17 [Commit working copy from JDeveloper]

ADDING NEW FILES TO A PROJECT Now that Josephine is part of the team, she wants to add a new Java source code file to the ViewController project. Just because the team is using Subversion, she does not have to do anything special to create the new .java file and add it to her project; she simply works in Oracle JDeveloper as usual. Josephine creates a new .java file and creates a few methods in it:

Figure 18 [Adding new file to SVN from in JDeveloper]

When Josephine looks at the new file in the Application Navigator window, she will see a blue x icon overlaid on her file, indicating that the file is not yet associated with the Subversion repository:

Furthermore, when she looks at the Pending Changes window (Versioning -> Subversion -> Pending Changes on the OracleJDeveloper menu), she’ll see her new Hello.java file listed in the Candidates tab, indicating that she has a file that is a candidate to be added to version control:

Figure 19 [Pending Changes window in JDeveloper]

Setting Preferences for Pending Changes

Figure 20 [Preference setting for Pending Changes in JDeveloper]

DEPENDENT LIBRARIES What if I need to check out other code not in my application? This might occur if your development organization has read only ‘standard’ code or libraries. Rather than each developer checking this code out and adding it to their application by hand you can use the svn:externals property. The advantage of this is that once you set the property on your application everyone who checks out the application from SVN will also get exactly the same set of code and associated libraries. SVN Properties are exhaustively covered in the SVN book detailed earlier.

Figure 21 [Adding SVN property in JDeveloper]

Figure 21 shows the JDeveloper Add Subversion Property dialog. In this example the Value String field shows a value pair entered to indicate that the library adflibStoreFrontService.jar is to be checked out of its URL in an SVN repository to a folder called external_jars. The folder external_jars will be created in the Resource File indicated in the dialog. Invoking the dialog on this node in the Application Navigator set this. The correct URL of the library was obtained by using the Copy URL command on the node in the Subversion Navigator (see Figure 1) EXCLUDING FILES FROM VERSION CONTROL

There are a couple of ways that files are excluded from the SVN Repository. You can exclude files during the Initial Import, ensure that certain file name patterns are never added to the repository or mark specific files for exclusion. JDeveloper recognizes certain file types as not needing to be controlled and additionally provides functionality for you to use the Subversion property svn:ignore. During Initial Import As mentioned earlier, it is possible to add filters to exclude files during the Initial Import of an application. JDeveloper uses its Global Ignore List to provide a pre-populated list of those files/file types that you are not likely to need versioned such as compiled Java classes (.class files). The Global Ignore List is displayed in Step 5 of the Import wizard. You can add filters to this list. Note that these additional filters are not added to the Global Ignore List and are not persisted between JDeveloper sessions. If you find that there is a specific pattern that your development teams always filter then you should document this in your development process to ensure that any team member doing an Initial Import of code is aware of it. Imagine this scenario: You create a new application containing some compiled Java classes. The Global Ignore List is also used by the Application Navigator to restrict the items displayed there. Hence, you do not see the compiled classes in the navigator but, of course, they exist on the file system. Now you Import the application into SVN and the same filter is applied to the application. As part of the Import wizard you choose to Check Out the imported application. Your original application location on the file system will by default now contain your checked out application – minus the excluded files. In fact, your original files have been backed up by JDeveloper so it is possible to return to them. But from this point on you should be working with your repository to maintain all your required code. Excluding New Files During application development it might be that you want to exclude certain file types or specific files from the repository, whilst still maintaining them in your working copy. To do this you use the svn:ignore property. There are a number of places to do this:

•

• •

Candidates Tab, Pending Changes o This tab shows all the files you have not yet added to version control. You can select files here and use the context menu to invoke the Add Subversion Property dialog. The dialog is populated with the files you selected and you can either choose to specifically ignore those files or edit the dialog to add file patterns. Specific file in the Application Navigator o By invoking the Add Subversion Property dialog on a specific file you can again add that file or a file pattern to svn:ignore. Folder node in the Application Navigator o svn:ignore is always set on a folder so you can invoke the Add Subversion Propery dialog from any folder node. Even when following the first two options above, the property is set on the owning folder of the selected files

RESOLVING CODE CONFLICTS As with all development projects there are a multitude of ways to resolve code conflicts between developers. No tool can ensure that conflicts do not occur. Much of the onus is on the development process of the team, its methodology and, as always, communication between developers. Some development teams where the developer who has the ‘lock’ on the main code wears a ‘lock’ hat to indicate to other team members that no one else should be updating the code (doesn’t work so well with distributed teams). JDeveloper's development process and methodology minimize conflicts but developers talk regularly to each other and are pro-active in informing and discussing potential conflicts that might arise through new feature development, refactoring or any of the other myriad of reasons that conflicts arise. Having

said that, SVN and JDeveloper can help to minimize these and provide strategies and answers to resolve them COMPARING VERSIONS In a team environment it is inevitable that other developers change code. These changes may or may not conflict with code that you are changing. Using the Pending Changes Incoming tab it is possible to see what files have being changed by other developers. Figure 5 shows that another team member has checked in a new version of home.jspx. At this stage it is not known if the changes are likely to conflict with your working copy changes.

SUBVERSION CLIENT CONFIGURATION Note: Refer SVN server configuration(s) and administration document for server configurations. It covers,

• • • • • • •

Enabling Windows Authentication Authorization Hooks [commit mandatorily requires log message] Checkstyle [automating code review] Installing web interface Third party products for Reports and Search Taking backup

CLIENT CONFIGURATIONS

When you run SVN for the first time a new directory is created for you, $(HOME)/.subversion. We will update this configuration file. Enabling auto update of keyword values like $Header$ or $Id$ fields. Automatic Property Setting In your Subversion client configuration file, 1) Uncomment the following line and change the value from no to yes, enable-auto-props = yes 2) Insert the following line at the end of configuration file to enable parsing of .java files *.java = svn:keywords=Id Date LastChangedBy Revision Now for instance, if you had the following text in your .java file, $Id$ it will be updated to, $Id: Readme.txt 43 2009-01-23 13:44:43Z sgandhi $ when you commit the file to repository Note: SVN values in Windows Registry can also be utilised to do client configurations. Refer here

For mandatory configuration options, refer Subversion Guidelines section below SUBVERSION GUIDELINES Before we discuss about them, remember

• •

For us, each repository constitutes a project The directory structure adopted for the project must always contain these three directories at root level o trunk - latest code, all work happen in this directory o branches - copies/offshoots of trunk. Trunk can be branched every time we work on something major, bug fixes etc o tags - frozen/snapshot copies of trunk, no updates happen here. Releases can be tagged

1. Update early, update often - This primarily saves the trouble of conflicting merges 2. Commit early, commit often - Ensuring that source code will compile. But please refrain from submitting frequent small irrelevant changes like white spaces etc

3. A single commit (changeset) must not be so large so as to discourage peer-review. 4. Always provide the commit message. Use the following text/symbols to better denote the

changes: a. + ..... if you have added something b. - ..... if you have removed something c. o .... modified something d. Example : + Comments introduced as requested by review team (bug 1234) e. TAG.... When creating a new tag f. BRANCH..... When creating a new branch g. MERGE.... X to Y from A to B i. X … Revision number of the last time the copies were in sync (start of branch or last merge) ii. Y … Revision number to which the merge applies (typically the latest revision) iii. A … Source directory (typically a directory from /branches) iv. B … Target directory (typically trunk). 5. Use the relevant tag name to keep track of important events. 6. Treat tags as read-only copies. 7. Each tag is a copy of /trunk into /tags. 8. All tags have a prefix DD-MON-YY. For e.g., 12-Feb-09_no_security_module 9. Don't use space while creating files/folders/tags/branches etc 10. Do not check in personal debug code into the main trunk - If you must check in personal debug code, create your own branch and keep this branch and the main trunk in sync 11. Use the $Id$ keyword to identify files -For all textual files we modify and maintain, we must add $Id$ near the top of the file for easy identification of the file and its latest revision change. If you set up a proper subversion configuration file this requirement becomes trivial. The only thing needed then is to add $Id$ into source files. 12. Never make commits in the tag directory, it exists only for keeping track of tags. 13. There two ways to set your favourite text editor for log message editing. Either you define it in the config file, or set one of the environment variables SVN_EDITOR to point at your preferred editor (for instance, Textpad). svn will use the first one it finds in the order we described the different possibilities here. 14. If we realize that a change committed to the repository is unwanted we can reverse these by reversing the order of revisions; svn merge -r 303:302 svn://ktpl-lt11/repos/calc/trunk Check the changes, and commit if you are happy with them. Magic! 15. For resurrecting deleted items use svn copy as svn copy -r 807 svn://ktpl-lt11/repos/calc/trunk/real.java ./real.java The added bonus with this is that subversion will also remember the files history.

16. Use DDL scripts to store your object definitions. Once the database schema is relatively stable,

you can then start creating "alter" scripts that modify database objects when going from one version to another. 17. Set up proper subversion config file. Refer Configuration options section below 18. Two components in ADF with maximum conflicts (chokepoints) are Application Modules in the Model layer and the faces-config.xml file in the View layer. The suggested approach is that if a conflict occurs when committing or a merge occurs when updating, the developer who experiences the conflict/merge then reverts the component back to the latest version of the component from the repository (in the process, reverting any changes he/she made to the object) and re-applies/re-codes his/her changes to the component. This method avoids the possibility of having a Subversion merge operation create an unusable object at the expense of requiring developers to do more work in the case of a merge/conflict. 19. To avoid developers using different version of third part libraries, you should include the external components in your version tracking approach. Create an Oracle JDeveloper project to contain all of the third-party JAR files; this project can then be added to the Subversion repository and controlled in the same manner as your application's source code. 20. In a team environment with version control, we need to agree on common standards up front to avoid formatting/code style kinds of problems. JDeveloper has an option for specifying coding style preferences, Preferences>Code Style

CONFIGURATION OPTIONS When you run svn for the first time a new directory is created for you, $(HOME)/.subversion. In this directory you find the configuration file, config that is used by the subversion programs. We provide a configuration for you with mandatory options and recommended options. Copy these into your configuration file. -----------------------------[miscellany] # recommended options global-ignores = *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store # mandatory option enable-auto-props = yes # all auto-props setting below are mandatory [auto-props] *.ldt = svn:eol-style=native;svn:keywords=Id *.html = svn:eol-style=native;svn:keywords=Id Date *.java = svn:eol-style=native;svn:keywords=Id *.jar = svn:mime-type=application/x-java-archive *.js = svn:eol-style=native;svn:keywords=Id *.jsp = svn:eol-style=native;svn:keywords=Id *.jpg = svn:mime-type=image/jpeg *.m4 = svn:eol-style=native;svn:keywords=Id *.pl = svn:eol-style=native;svn:executable;svn:keywords=Id *.pm = svn:eol-style=native;svn:keywords=Id *.png = svn:mime-type=image/png *.sh = svn:eol-style=native;svn:executable;svn:keywords=Id *.tex = svn:eol-style=native;svn:keywords=Id *.txt = svn:eol-style=native;svn:keywords=Id *.xml = svn:eol-style=native;svn:keywords=Id *.xsd = svn:eol-style=native;svn:keywords=Id *.xsl = svn:eol-style=native;svn:keywords=Id AUTHORS = svn:eol-style=native;svn:keywords=Id bootstrap = svn:eol-style=native;svn:executable;svn:keywords=Id ChangeLog = svn:eol-style=native;svn:keywords=Id configure.ac = svn:eol-style=native;svn:keywords=Id

INSTALL = svn:eol-style=native;svn:keywords=Id Makefile = svn:eol-style=native;svn:keywords=Id Makefile.am = svn:eol-style=native;svn:keywords=Id NEWS = svn:eol-style=native;svn:keywords=Id README = svn:eol-style=native;svn:keywords=Id references.bib = svn:eol-style=native;svn:keywords=Id TODO = svn:eol-style=native;svn:keywords=Id -----------------------------Note: The global-ignores define file patterns that is to be ignored when a svn status is issued. The auto-props patterns are only used when you add files and directories, i.e. using svn add or svn import.

REFERENCES

General The Subversion project Version Control with Subversion || a book on Subversion SCM tool comparison chart Oracle white paper on Subversion A Visual Guide to Version Control

Setup Tips and Tricks WebSVN

Tools Links to many other clients, tools etc

JDeveloper integration with Subversion http://www.oracle.com/technology/products/jdev/11/how-tos/subversion/teamdevsubversion.html http://www.oracle.com/technology/pub/articles/adf-development-essentials/part1.html http://www.oracle.com/technology/pub/articles/adf-development-essentials/part2.html http://www.oracle.com/technology/pub/articles/adf-development-essentials/part3.html

SQL Developer integration with Subversion http://www.oracle.com/technology/oramag/oracle/08-jul/o48sql.html

SOFTWARE Collabnet Subversion command line client Local file location: file://kbace/users/sgandhi/Shared/softwares/CollabNetSubversion-client-1.5.51.win32.exe

TortoiseSVN is a Windows GUI client for Subversion Local file location: file://kbace/users/sgandhi/Shared/softwares/TortoiseSVN-1.5.6.14908-win32-svn1.5.5.msi JDeveloper 11g Local file location: file://kbace\users\sgandhi\software\ SQL Developer Local file location: file://kbace\Softwares\Sql developer\sqldeveloper-5783