Subversion for VSS Users |
Last Updated March 2007
|
- Introduction
- Part 1: Visual SourceSafe (VSS) versus Subversion (SVN)
- Part 2: Work-flow
- Part 3: Software
- Part 4: Importing a Project
- Part 5: Working Copy
- Part 6: Edit, Diff, and Commit
- Part 7: Adding Files/Folders
- Part 8: Deleting Files/Folders
- Part 9: Move and Rename
- End Notes
Introduction
There isn't a lot of Subversion Tutorials out there, especially for those trying to break away from VSS (Microsoft's Visual SourceSafe). Having worked with VSS for years, it was initially difficult to be sufficiently motivated to move on, even though I was deeply acquainted with all of its failings. It's even more of a challenge when a large team or company has time, training, and space invested. The consensus for those already using Subversion, it seems, is that you want it enough to deal with some pain.
Personally I needed to not only become intimate with Subversion, but convey my knowledge to many others and migrate a lot of projects from Visual Source Safe. Existing documentation isn't lacking in detail, it just isn't comfortable stuff. I'm hoping this tutorial will make a scary transition a bit softer. I'm assuming you're a VSS hold-out ready to move on, but unsure how to do it. I will try my best to relate your prior VSS knowledge to new Subversion concepts.
Part 1: VSS compared to SVN
Pre-requisite(s): Experience using Microsoft Visual SourceSafe.
Goal(s): Show Subversion equivalents of VSS terms and syntax.
This section isn't your typical "VSS versus Subversion" where I debate the pro's and con's of each. Instead, I just want to cover some high-level differences, mostly just in the terms used.
First, VSS is to Microsoft Visual SourceSafe what SVN is to Subversion: short-hand. I tend to write out the term Subversion and abbreviate VSS in this tutorial, because it's intended for beginners.
The phrase "source control" is traded for "version control". These are interchangeable.
VSS has the concept of a database whilst Subversion uses the term repository, sometimes shortened to just "repo". These things are basically equivalent: file stores which track changes.
VSS databases are referred to by file paths (\\server\share\srcsafe.ini, c:\vss\db\srcsafe.ini, etc.) whereas Subversion uses a URL syntax (file:///svn/repo/, http://server/repo/, etc.) to identify repositories.
Goal(s): Show Subversion equivalents of VSS terms and syntax.
This section isn't your typical "VSS versus Subversion" where I debate the pro's and con's of each. Instead, I just want to cover some high-level differences, mostly just in the terms used.
First, VSS is to Microsoft Visual SourceSafe what SVN is to Subversion: short-hand. I tend to write out the term Subversion and abbreviate VSS in this tutorial, because it's intended for beginners.
The phrase "source control" is traded for "version control". These are interchangeable.
VSS has the concept of a database whilst Subversion uses the term repository, sometimes shortened to just "repo". These things are basically equivalent: file stores which track changes.
VSS databases are referred to by file paths (\\server\share\srcsafe.ini, c:\vss\db\srcsafe.ini, etc.) whereas Subversion uses a URL syntax (file:///svn/repo/, http://server/repo/, etc.) to identify repositories.
Part 2: Work-flow Overview
Pre-requisite(s): VSS usage experience.
Goal(s): Demystify the basic Subversion work-flow in comparison to VSS.
In the VSS world, and other Microsoft products continuing to this day [1], you checkout one or more files and then begin working on them. The idea of checking out is that you lock the file, others see that you have it locked, and only you can work on it [2]. In order to even checkout a file you set a working folder, where the files will be located locally on your computer. Those files within your working folder are marked read-only unless you've checked them out, so you know which ones you can edit. Finally when you're finished making your changes, you check them in.
Subversion, on the other hand, uses an entirely different approach. First you'll do a checkout to create a working copy; VSS semi-equivalent: set aWorking Folder and then Get Latest Version. Next you edit the files locally and when you're ready to publish the changes, you commit them. You can continue to make changes and commit each time when you're ready to push them to the repository. To get the latest changes, such as what other people have committed, you must do an update.
You still have to checkout before you can make changes and publish them; the fundamental difference here is that you don't checkout/lock files in order to edit them, the terminology of the word checkout itself is even completely changed. Some other things this brings up is: you can't see what people are working on (only what they've previously committed), you can have multiple working copies as opposed to just one working folder in VSS, you can't do an update until you have checked out a working copy, and you generally won't know if there's a problem until you commit.
Conflicts are the most common issue preventing you from committing, e.g. when someone else has edited the same file and committed it before you. Thus when you try to commit your changes to the same file, Subversion gives you an error, at which point you'll perform an update to merge the latest changes with your own. Finally you indicate to Subversion you've resolved the conflicts and then it will let you commit the finished result [3].
Renaming, adding, deleting, and moving files or folders in VSS is done from the client and effects the database immediately. Subversion, again, differs in that you make these kinds of changes to your working copy and then commit them. You can batch up multiple structure changes and commit them all at the same time.
Commits are the big thing in Subversion. Whenever you're committing, you're making a change to the repository. If you didn't commit, it didn't happen (to the server), and no one else will see it. Before you hit commit, you can revert any one or all of those local changes. Reverting is basically equivalent to Undo Checkout in VSS.
Goal(s): Demystify the basic Subversion work-flow in comparison to VSS.
In the VSS world, and other Microsoft products continuing to this day [1], you checkout one or more files and then begin working on them. The idea of checking out is that you lock the file, others see that you have it locked, and only you can work on it [2]. In order to even checkout a file you set a working folder, where the files will be located locally on your computer. Those files within your working folder are marked read-only unless you've checked them out, so you know which ones you can edit. Finally when you're finished making your changes, you check them in.
Subversion, on the other hand, uses an entirely different approach. First you'll do a checkout to create a working copy; VSS semi-equivalent: set aWorking Folder and then Get Latest Version. Next you edit the files locally and when you're ready to publish the changes, you commit them. You can continue to make changes and commit each time when you're ready to push them to the repository. To get the latest changes, such as what other people have committed, you must do an update.
You still have to checkout before you can make changes and publish them; the fundamental difference here is that you don't checkout/lock files in order to edit them, the terminology of the word checkout itself is even completely changed. Some other things this brings up is: you can't see what people are working on (only what they've previously committed), you can have multiple working copies as opposed to just one working folder in VSS, you can't do an update until you have checked out a working copy, and you generally won't know if there's a problem until you commit.
Conflicts are the most common issue preventing you from committing, e.g. when someone else has edited the same file and committed it before you. Thus when you try to commit your changes to the same file, Subversion gives you an error, at which point you'll perform an update to merge the latest changes with your own. Finally you indicate to Subversion you've resolved the conflicts and then it will let you commit the finished result [3].
Renaming, adding, deleting, and moving files or folders in VSS is done from the client and effects the database immediately. Subversion, again, differs in that you make these kinds of changes to your working copy and then commit them. You can batch up multiple structure changes and commit them all at the same time.
Commits are the big thing in Subversion. Whenever you're committing, you're making a change to the repository. If you didn't commit, it didn't happen (to the server), and no one else will see it. Before you hit commit, you can revert any one or all of those local changes. Reverting is basically equivalent to Undo Checkout in VSS.
- Notes
- Subversion Checkout does not lock files
- Subversion Checkout == VSS: Get Latest Version & Set Working Folder
- Subversion Revert == VSS: Undo Checkout
Part 3: Software
Pre-requisite(s): Get TortoiseSVN from tortoisesvn.tigris.org.
Goal(s): Introduce TortoiseSVN and create a local repository with it.
Goal(s): Introduce TortoiseSVN and create a local repository with it.
TortoiseSVN is a nice, graphical application (with an active development community) for interacting with Subversion repositories; the basic Subversion package is made up only of server modules and command-line tools. This tutorial is geared exclusively towards the use of TortoiseSVN rather than the command-line tools. Either one works fine, though, and later you might even prefer something other than these two. I like to think of TortoiseSVN as my new VSS replacement, because unless you're working with the server-side of Subversion, that's all you'll ever see.
At the same time you may also find TortoiseSVN to be invisible or rather implicit. It integrates itself with Windows Explorer so you will launch various actions/commands by right-clicking files and folders [4]. SourceSafe, on the other hand, is a stand-alone application which you launch to perform all your actions. In case you were wondering, there are ways to integrate Subversion with Visual Studio, but those won't be covered in this tutorial. I find that new users have trouble enough understanding Subversion without Visual Studio trying to do things for them, and thus adding more confusion.
Now let's step through creating a repository on your workstation using TortoiseSVN. You'll be able to use this repository to practice the things I'll be talking about in later sections. If you already have a repository, or at least you think so because someone gave you a URL and said "Start putting your code into Subversion", you can skip this.
First thing you'll want to do is pick a folder where your repository will be located [5]. If you're unsure, create a folder on C:\ called MyRepo. Right-click the folder you've created and select TortoiseSVN > Create repository here.
Now let's step through creating a repository on your workstation using TortoiseSVN. You'll be able to use this repository to practice the things I'll be talking about in later sections. If you already have a repository, or at least you think so because someone gave you a URL and said "Start putting your code into Subversion", you can skip this.
First thing you'll want to do is pick a folder where your repository will be located [5]. If you're unsure, create a folder on C:\ called MyRepo. Right-click the folder you've created and select TortoiseSVN > Create repository here.
The only thing you'll be asked is what type of repository, and there are only two options. Choose Native filesystem (FSFS). This is just how the repository will be represented on disk and FSFS is the best choice in most cases.
Hit OK and voila, you've just created a repository!
Repositories are identified with URL's, as mentioned previously, and thus you won't refer to your new one as C:\MyRepo\ but rather file:///c:/myrepo/. Being that the URL points to a specific file path, realize that you won't be able to use this over the network. Setting up a network-accessible repository, via HTTP[S] for example, is an entirely different tutorial! This will at least give you something to play with to get the hang of using Subversion.
It is a good idea to keep the drive and repository name lower-case in your URL, because you'll have to get in that habit when working with http:// URL's later on.
Repositories are identified with URL's, as mentioned previously, and thus you won't refer to your new one as C:\MyRepo\ but rather file:///c:/myrepo/. Being that the URL points to a specific file path, realize that you won't be able to use this over the network. Setting up a network-accessible repository, via HTTP[S] for example, is an entirely different tutorial! This will at least give you something to play with to get the hang of using Subversion.
It is a good idea to keep the drive and repository name lower-case in your URL, because you'll have to get in that habit when working with http:// URL's later on.
- Notes:
- TortoiseSVN integrates with explorer versus VSS being a stand-alone application.
- Use Repo-browser to verify repository URL and for browsing tree like VSS.
Part 4: Importing a Project
|
Pre-requisite(s): Your Subversion repository URL (my examples based on the file:///c:/myrepo/ created in the previous section) and a project to import.
Goal(s): Steps to get a project, not already under source control, into a Subversion repository. |
| ||
The TortoiseSVN > Import command is one method of putting a new project into a repository, there are others I will get to in later sections. Importing a project copies files and folders from your disk into the Subversion repository of your choice, nothing more. It is intended for projects which you have started without source control and now want to bring them in. At this point, I'm guessing you've never added anything to your repository, so this is exactly what we want to do.
VSS has no equivalent command, generally what you'd do is painstakingly create all the individual nodes of the project and then add files to them. There are ways to migrate a VSS database to a Subversion repository, thereby retaining the history. That's the theory anyway. I recommend against it: the software to do these things is generally poorly supported; your results will vary. If you've moved, renamed, and/or deleted a lot of things in VSS, you've irreparably messed up the history anyway.
Before importing a project you got from VSS into Subversion, make sure to mark all the files as write-able (e.g., not read-only) and remove everyvssver.scc file you can find; these are marked as hidden by default. In any case, setup the hierarchy of files and folders as you would like them to appear in the repository. You must have a folder that represents the root folder of the repository. This is generally where people run into trouble, they'll import a particular folder and its contents go into the repository off the root.
1. Setup project on disk as you want it to be imported into Subversion
To perform the Subversion import of the file structure you've created, right-click the folder representing your root and select TortoiseSVN > Import. Remember that you need to select the folder above your project folder, otherwise the import will pull in the contents of your project but not its folder!
2. Right-click the folder containing your project folder and then select import.
Enter the URL of the destination repository and optionally some comments. When importing a project that was in VSS, I suggest something along the lines of:
Imported from VSS Database: \\server\share\srcsafe.ini) Path: $/Path/To/Project/
Click the OK button to begin the import, but don't walk away just yet. You may be prompted to enter your username and password. Also, if this is the first time you've connected to a repository with a HTTPS URL, you will also be prompted to accept its certificate. Once rolling, the import may take a while, depending on the total size of data and where the repository is located. When it completes, you'll have to click another OK to close the import log window.
Finally, let's use the TortoiseSVN > Repo-browser to view what you've imported, to see how it looks in the repository. The initial dialog is simply: enter the repository URL. If the URL is not pre-populated, click the drop-down arrow and it should be in the Most-Recent URL's list. Click OK and you'll see the Repo-browser. As mentioned in the previous section, the Repo-browser is somewhat like VSS and a comfortable sight for those nervous in new territory. As it is a standard tree-view, there isn't much I should have to tell you about how to use it. You can right-click files/folders to bring up various actions that will be performed directly against the repository.
Back to those files on your disk which you ran the import on. I recommend backing them up if you don't yet trust Subversion and what you've put into it, or deleting them if you do. You can't edit the files in their current location and push the changes to the repository, that's what you'll need a working copy for.
Finally, let's use the TortoiseSVN > Repo-browser to view what you've imported, to see how it looks in the repository. The initial dialog is simply: enter the repository URL. If the URL is not pre-populated, click the drop-down arrow and it should be in the Most-Recent URL's list. Click OK and you'll see the Repo-browser. As mentioned in the previous section, the Repo-browser is somewhat like VSS and a comfortable sight for those nervous in new territory. As it is a standard tree-view, there isn't much I should have to tell you about how to use it. You can right-click files/folders to bring up various actions that will be performed directly against the repository.
Back to those files on your disk which you ran the import on. I recommend backing them up if you don't yet trust Subversion and what you've put into it, or deleting them if you do. You can't edit the files in their current location and push the changes to the repository, that's what you'll need a working copy for.
Part 5: Working Copy
Pre-requisite(s): Subversion repository containing some files/folders.
Goal(s): Get a local copy of a project from a Subversion repository.
In VSS you checkout files in order to work on them, and then you check them in when you're finished. Thus you don't actually edit the files directly in the database, but rather you make the changes to files on your computer and then upload those modified versions into the database. The location of these local files is determined by the Working Folder setting for the VSS project you're working on. The VSS client stores the information about your working folders on the server, basically in the VSS database. So every time you launch VSS with a particular user, it knows where you're working from.
Subversion is the same in that you edit local files before committing those changes to the repository. Instead of a single working folder for a project, however, you create a working copy using the checkout command. TortoiseSVN identifies working copies through hidden folders named .svn [6] which is sort of like SourceSafe's vssver.scc files. Note that TortoiseSVN notes this information locally and not on the server where the repository is. This is generally fine, because there's no stand-alone client to run like VSS and therefore no reason to keep the information on the server.
Alright, now let's get a working copy of a project to play with. Right-click a folder where you'd like to create a working copy and then select SVN Checkout. Enter the URL of the repository and add the name of the project at the end. This will ensure that we get a working copy of just that folder and its contents, not the entire repository. Just like in VSS you will probably only work on certain projects at a time and not want to grab a copy of the entire database. Remember, a Subversion checkout does not lock the files so other developers (if this is a shared repository) may checkout files and edit them locally as well; neither of you would know through TortoiseSVN. This is different from VSS where you can kind of tell when someone is working on something, because you can see if they have it checked out or not.
What you put in the Checkout directory input box will become your working copy. Think of it saying "Working Folder" instead of "Checkout directory". I generally keep this folder named the same as the project so as not to get confusing, so in this case I'm using C:\Work\ExampleProject.
After you click OK, TortoiseSVN will prompt you if the folder doesn't yet exist. Otherwise it will download all the latest files from the repository and plop them down, along with a .svn folder per working copy folder.
Now it's time to explore your working copy. Open up the folder or drive which contains the final project folder you created. It should have a green checkmark overlay. This means that TortoiseSVN recognizes it as a working copy of something in a Subversion repository, and it hasn't been altered.
Opening up the project folder you'll see the .svn folder (if you can see hidden files/folders) and all the other files and folders will have green checkmarks on them as well. My example project is a single text file, so there isn't much to see here.
Finally, right-click on a blank spot inside the folder to bring up the context menu. You'll see SVN Update (VSS: Get Latest Version) and SVN Commit (VSS Checkin) instead of SVN Checkout, and a TortoiseSVN> menu will be available as well. Note, then, that you can't checkout multiple projects from Subversion to the same directory whereas in VSS you can have them share the same working folder.
Goal(s): Get a local copy of a project from a Subversion repository.
In VSS you checkout files in order to work on them, and then you check them in when you're finished. Thus you don't actually edit the files directly in the database, but rather you make the changes to files on your computer and then upload those modified versions into the database. The location of these local files is determined by the Working Folder setting for the VSS project you're working on. The VSS client stores the information about your working folders on the server, basically in the VSS database. So every time you launch VSS with a particular user, it knows where you're working from.
Subversion is the same in that you edit local files before committing those changes to the repository. Instead of a single working folder for a project, however, you create a working copy using the checkout command. TortoiseSVN identifies working copies through hidden folders named .svn [6] which is sort of like SourceSafe's vssver.scc files. Note that TortoiseSVN notes this information locally and not on the server where the repository is. This is generally fine, because there's no stand-alone client to run like VSS and therefore no reason to keep the information on the server.
Alright, now let's get a working copy of a project to play with. Right-click a folder where you'd like to create a working copy and then select SVN Checkout. Enter the URL of the repository and add the name of the project at the end. This will ensure that we get a working copy of just that folder and its contents, not the entire repository. Just like in VSS you will probably only work on certain projects at a time and not want to grab a copy of the entire database. Remember, a Subversion checkout does not lock the files so other developers (if this is a shared repository) may checkout files and edit them locally as well; neither of you would know through TortoiseSVN. This is different from VSS where you can kind of tell when someone is working on something, because you can see if they have it checked out or not.
What you put in the Checkout directory input box will become your working copy. Think of it saying "Working Folder" instead of "Checkout directory". I generally keep this folder named the same as the project so as not to get confusing, so in this case I'm using C:\Work\ExampleProject.
After you click OK, TortoiseSVN will prompt you if the folder doesn't yet exist. Otherwise it will download all the latest files from the repository and plop them down, along with a .svn folder per working copy folder.
Now it's time to explore your working copy. Open up the folder or drive which contains the final project folder you created. It should have a green checkmark overlay. This means that TortoiseSVN recognizes it as a working copy of something in a Subversion repository, and it hasn't been altered.
Opening up the project folder you'll see the .svn folder (if you can see hidden files/folders) and all the other files and folders will have green checkmarks on them as well. My example project is a single text file, so there isn't much to see here.
Finally, right-click on a blank spot inside the folder to bring up the context menu. You'll see SVN Update (VSS: Get Latest Version) and SVN Commit (VSS Checkin) instead of SVN Checkout, and a TortoiseSVN> menu will be available as well. Note, then, that you can't checkout multiple projects from Subversion to the same directory whereas in VSS you can have them share the same working folder.
Part 6: Edit, Diff, and Commit
Pre-requisite(s): Working copy of a project in Subversion.
Goal(s): Make changes to files in a Subversion repository.
Hopefully you're still here, now that we're finally getting to what you'll usually be doing with Subversion; the standard work-flow if you will. Unfortunately it may be disappointing how simple this part is.
Open up a file you want to edit in your working copy using your favored editor. Make some change, any change, and then open the file's parent folder.
Notice the green checkmark is gone and instead there is a red exclamation mark. It is meant to grab your attention and doesn't signify there is a problem. What it does mean is that the file is different than the one you last got from the repository. Move up a folder and you'll see that the containing folder even has this icon. That display will show up at the top-most folder in your working copy. In my example, that means this will be shown on theExampleProject folder, but not on its parent: C:\Work.
Assuming this is a text-based file you can see line-by-line differences by right-clicking it and selecting TortoiseSVN > Diff. For those of us quite used to SourceSafe's visual differences, this will be a treat. Not only can you see line-by-line, but if you roll the mouse over a changed line, it will show you exactly which characters at the bottom. Also, character (as opposed to whole line) differences use a slightly different color. This is helpful if you indent or de-indent a bunch of stuff, because it won't look like a huge block of changed code.
At this point in VSS you'd checkin to publish your changes to the database, assuming you were finished editing locally. With Subversion what you'll do iscommit all your changes to the repository. Do this by right-clicking that file you edited and selecting SVN Commit.
For the most part, the commit dialog (Enter Log Message) dialog is fairly self-explanatory. It looks a lot like Visual SourceSafe's checkin dialog. You can enter a message, like a VSS checkin comment, and there are some wacky checkboxes that I'll get to in a bit. Also notice it has a list of files that are being committed. If you had edited multiple files within the working copy, you can right-click the folder and select commit to publish all these changes at once.
When you've clicked OK TortoiseSVN will contact the repository, build up a transaction for the commit, and then send off all the changes. Depending on the amount of files you're committing changes for, it may take a while and the progress dialog isn't very helpful. Luckily it doesn't copy whole files, but rather only differences between them. This is helpful when working with remote repositories on, for example, http:// URL's.
Because you never did a VSS-style checkout, there was no lock to unlock, and thus you can continue to edit and commit, again and again. You may need to occassionally get the latest versions of files from the repository, however. Get the latest files when other developers have made changes, or maybe you've made changes to another working copy elsewhere, by right-clicking the project folder and selecting SVN Update. As long as you haven't changed the files being updated, this will pull down all the changes without needing input.
It's important to update periodically so your working base is up to date. You may have noticed in the differencing GUI that it shows "working base" on the left and "working copy" on the right. Of course the working copy is the files you've edited, but what is the working base? VSS is always communicating with the server, so doing a diff goes against the latest files in the database. Subversion doesn't require constant communication with a repository, instead the last files you got from it are stored in the hidden folder (.svn in most cases [6]) which is known as your working base. When you do a diff, it goes against these files which means, yes, they might not be the latest. Again, that's why it's so important to keep your working copy (and base) up to date.
To see the changes that have been made to projects, use the TortoiseSVN > Repo-browser as touched on in an earlier section. Again, the Repo-browser is a lot like the VSS application you're used to except there's no menu bar or toolbar. Remember you can right-click items here and see their history with Show log. Every time someone commits a change to the repository, its revision number is incremented. In VSS each individual file has a version number that does this, but in Subversion that number is applied to the entire repository.
Undo your local changes, like VSS Undo Checkout, using TortoiseSVN > Revert. You can either select specific files before right-clicking, or just right-click the project folder. In either case you'll be shown a dialog which shows the exact list of files to be reverted.
Before we move on, the biggest question in a VSS user's mind is: "How does Subversion prevent stomping if checking out doesn't lock files?" In short: Subversion simply won't let you commit if someone else has commited before you. You are forced to merge conflicts in the changes, sign off on the merge, and then you can commit. It is not possible to accidentally stomp changes, you can do it, but you have to be mighty persistent. Conflicts and merging are complicated enough that I won't go into them in this section, and singular administrator/developers won't care besides.
Goal(s): Make changes to files in a Subversion repository.
Hopefully you're still here, now that we're finally getting to what you'll usually be doing with Subversion; the standard work-flow if you will. Unfortunately it may be disappointing how simple this part is.
Open up a file you want to edit in your working copy using your favored editor. Make some change, any change, and then open the file's parent folder.
Notice the green checkmark is gone and instead there is a red exclamation mark. It is meant to grab your attention and doesn't signify there is a problem. What it does mean is that the file is different than the one you last got from the repository. Move up a folder and you'll see that the containing folder even has this icon. That display will show up at the top-most folder in your working copy. In my example, that means this will be shown on theExampleProject folder, but not on its parent: C:\Work.
Assuming this is a text-based file you can see line-by-line differences by right-clicking it and selecting TortoiseSVN > Diff. For those of us quite used to SourceSafe's visual differences, this will be a treat. Not only can you see line-by-line, but if you roll the mouse over a changed line, it will show you exactly which characters at the bottom. Also, character (as opposed to whole line) differences use a slightly different color. This is helpful if you indent or de-indent a bunch of stuff, because it won't look like a huge block of changed code.
At this point in VSS you'd checkin to publish your changes to the database, assuming you were finished editing locally. With Subversion what you'll do iscommit all your changes to the repository. Do this by right-clicking that file you edited and selecting SVN Commit.
For the most part, the commit dialog (Enter Log Message) dialog is fairly self-explanatory. It looks a lot like Visual SourceSafe's checkin dialog. You can enter a message, like a VSS checkin comment, and there are some wacky checkboxes that I'll get to in a bit. Also notice it has a list of files that are being committed. If you had edited multiple files within the working copy, you can right-click the folder and select commit to publish all these changes at once.
When you've clicked OK TortoiseSVN will contact the repository, build up a transaction for the commit, and then send off all the changes. Depending on the amount of files you're committing changes for, it may take a while and the progress dialog isn't very helpful. Luckily it doesn't copy whole files, but rather only differences between them. This is helpful when working with remote repositories on, for example, http:// URL's.
Because you never did a VSS-style checkout, there was no lock to unlock, and thus you can continue to edit and commit, again and again. You may need to occassionally get the latest versions of files from the repository, however. Get the latest files when other developers have made changes, or maybe you've made changes to another working copy elsewhere, by right-clicking the project folder and selecting SVN Update. As long as you haven't changed the files being updated, this will pull down all the changes without needing input.
It's important to update periodically so your working base is up to date. You may have noticed in the differencing GUI that it shows "working base" on the left and "working copy" on the right. Of course the working copy is the files you've edited, but what is the working base? VSS is always communicating with the server, so doing a diff goes against the latest files in the database. Subversion doesn't require constant communication with a repository, instead the last files you got from it are stored in the hidden folder (.svn in most cases [6]) which is known as your working base. When you do a diff, it goes against these files which means, yes, they might not be the latest. Again, that's why it's so important to keep your working copy (and base) up to date.
To see the changes that have been made to projects, use the TortoiseSVN > Repo-browser as touched on in an earlier section. Again, the Repo-browser is a lot like the VSS application you're used to except there's no menu bar or toolbar. Remember you can right-click items here and see their history with Show log. Every time someone commits a change to the repository, its revision number is incremented. In VSS each individual file has a version number that does this, but in Subversion that number is applied to the entire repository.
Undo your local changes, like VSS Undo Checkout, using TortoiseSVN > Revert. You can either select specific files before right-clicking, or just right-click the project folder. In either case you'll be shown a dialog which shows the exact list of files to be reverted.
Before we move on, the biggest question in a VSS user's mind is: "How does Subversion prevent stomping if checking out doesn't lock files?" In short: Subversion simply won't let you commit if someone else has commited before you. You are forced to merge conflicts in the changes, sign off on the merge, and then you can commit. It is not possible to accidentally stomp changes, you can do it, but you have to be mighty persistent. Conflicts and merging are complicated enough that I won't go into them in this section, and singular administrator/developers won't care besides.
Part 7: Adding Files/Folders
Pre-requisite(s): Working copy of a project in Subversion.
Goal(s): Add new files to a working copy project as well as understand working base and the difference between unversioned and versioned.
Remember doing an import and afterwards you just had to trash the files since they weren't working copies? Well, there's an easier way to add files, even whole folder hierarchies, to a repository. The trick isn't really a trick, you just need a working copy that you can add to with TortoiseSVN > Add and afterwards those folders/files become working copies that you can edit and commit!
Let's dive right in by adding a folder containing a file. So first create a folder as you normally would and then put a file in it; remember to do this inside the working copy for your project.
Now that you have those two things, right-click the folder you created and select TortoiseSVN > Add. A dialog will come up that confirms your additions, it looks a lot like the commit dialog but it isn't. In fact, after you click OK, and even after you watch it "add" the files, nothing gets added to the repository. Instead, what this does is tell TortoiseSVN that when you commit the project folder, you'll also want to add these things. Important: it doesn't add them right away!
Ah, so what now? You'll see these new items have plus sign overlays rather than an red exclamation or green checkmark. This is another clue to you that these changes are still just local and your intentions have not been published. As you did with editing files, right-click inside the project folder, or the to-be-added items, and select SVN Commit. Note that now the commit dialog mentions these things will be added, rather than modified. Clicking OK will start the commit and, if it succeeds, then that stuff is finally added to the repository. [7]
A file or folder that is in your working copy, but is not in the Subversion repository, is considered unversioned. This really goes for any file/folder that is not having its changes tracked, but it becomes especially important to understand in the context of a working copy. If you simply put a new file into your working copy, it is unversioned. Once you've added it to the repository using the steps above, it becomes versioned.
You may have noticed the Show unversioned files option in the commit dialog, which may also be checked by default. This causes TortoiseSVN to list out files which are in the repository, even if you aren't adding them. This is another way to add things to the repository. What you do is check the box next to these unversioned files to make them part of the commit. When you click OK, TortoiseSVN will then add them.
What happens if you try to add a file that already exists in the repository? TortoiseSVN will return an error. Remember that TortoiseSVN also determines versioned versus unversioned based on your working base, not actually what may be in the repository. It's possible someone will add files that you already have in your working copy that are unversioned. When you do an SVN Update, TortoiseSVN will alert you and not overwrite them. One way to solve this (assuming your copy is basically the same content with changes) is to copy the unversioned files to another folder, do the update, and then copy them back over the versioned files. If you don't know what this new, versioned file is then you might have some developer contention and TortoiseSVN can't help you solve that.
Goal(s): Add new files to a working copy project as well as understand working base and the difference between unversioned and versioned.
Remember doing an import and afterwards you just had to trash the files since they weren't working copies? Well, there's an easier way to add files, even whole folder hierarchies, to a repository. The trick isn't really a trick, you just need a working copy that you can add to with TortoiseSVN > Add and afterwards those folders/files become working copies that you can edit and commit!
Let's dive right in by adding a folder containing a file. So first create a folder as you normally would and then put a file in it; remember to do this inside the working copy for your project.
Now that you have those two things, right-click the folder you created and select TortoiseSVN > Add. A dialog will come up that confirms your additions, it looks a lot like the commit dialog but it isn't. In fact, after you click OK, and even after you watch it "add" the files, nothing gets added to the repository. Instead, what this does is tell TortoiseSVN that when you commit the project folder, you'll also want to add these things. Important: it doesn't add them right away!
Ah, so what now? You'll see these new items have plus sign overlays rather than an red exclamation or green checkmark. This is another clue to you that these changes are still just local and your intentions have not been published. As you did with editing files, right-click inside the project folder, or the to-be-added items, and select SVN Commit. Note that now the commit dialog mentions these things will be added, rather than modified. Clicking OK will start the commit and, if it succeeds, then that stuff is finally added to the repository. [7]
A file or folder that is in your working copy, but is not in the Subversion repository, is considered unversioned. This really goes for any file/folder that is not having its changes tracked, but it becomes especially important to understand in the context of a working copy. If you simply put a new file into your working copy, it is unversioned. Once you've added it to the repository using the steps above, it becomes versioned.
You may have noticed the Show unversioned files option in the commit dialog, which may also be checked by default. This causes TortoiseSVN to list out files which are in the repository, even if you aren't adding them. This is another way to add things to the repository. What you do is check the box next to these unversioned files to make them part of the commit. When you click OK, TortoiseSVN will then add them.
What happens if you try to add a file that already exists in the repository? TortoiseSVN will return an error. Remember that TortoiseSVN also determines versioned versus unversioned based on your working base, not actually what may be in the repository. It's possible someone will add files that you already have in your working copy that are unversioned. When you do an SVN Update, TortoiseSVN will alert you and not overwrite them. One way to solve this (assuming your copy is basically the same content with changes) is to copy the unversioned files to another folder, do the update, and then copy them back over the versioned files. If you don't know what this new, versioned file is then you might have some developer contention and TortoiseSVN can't help you solve that.
Part 8: Deleting Files/Folders
Pre-requisite(s): Working copy of a project in Subversion.
Goal(s): Delete files from a working copy as well as the repository.
Often for VSS you will not have the privilege of fully destroying files. It's an extra permission that must be granted by the administrator and a good one will be loath to do it. The reason being of course, destroying a file in VSS will cause it to be irrevocably lost to the database. You can only then recover it using separate backups. This poses an additional problem with trying to re-get old versions of entire projects, because files that were required back then are no longer available. Whoops!
In Subversion you either have read-only, read/write, or no access to a repository; you can't destroy history without damaging the repository itself, e.g. you have to do it outside the software. There is no permanent destroy and deleted files are always recoverable by getting an earlier version. Recall in an earlier section I mentioned that the entire repository is given a new version when any commit is made, this is called a revision. When you get an earlier revision of a particular folder, it gets its entire structure as it existed back then, even files that have since been moved or deleted.
Anyhoo, here's something fun to try or something irritating depending on if you've had this happen yet already. Find a versioned file, one with a green checkmark and whatnot, then delete it by pressing DEL or dragging it to the Recycle Bin. Now do a SVN Update. It comes back! TortoiseSVN sees that you don't have a file which is in the repository (and in this case, still in the working base) and thus re-creates it.
In order to delete a file from the repository you need to use TortoiseSVN > Delete. The file will usually disappear, and a folder will do the same if you delete it. However, if it happens to come back before you commit, for whatever reason, it will have a red 'X' overlay. This signifies, like the plus sign for add, that when you commit the files will be deleted.
Launching SVN Commit when files are marked for deletion will list them out along with that action. As with anything else, and I can't say this often enough, you won't actually delete the files from the repository until the commit has completed. If someone else has already deleted the files from the repository, you will be rebuffed and have to do SVN Update.
Goal(s): Delete files from a working copy as well as the repository.
Often for VSS you will not have the privilege of fully destroying files. It's an extra permission that must be granted by the administrator and a good one will be loath to do it. The reason being of course, destroying a file in VSS will cause it to be irrevocably lost to the database. You can only then recover it using separate backups. This poses an additional problem with trying to re-get old versions of entire projects, because files that were required back then are no longer available. Whoops!
In Subversion you either have read-only, read/write, or no access to a repository; you can't destroy history without damaging the repository itself, e.g. you have to do it outside the software. There is no permanent destroy and deleted files are always recoverable by getting an earlier version. Recall in an earlier section I mentioned that the entire repository is given a new version when any commit is made, this is called a revision. When you get an earlier revision of a particular folder, it gets its entire structure as it existed back then, even files that have since been moved or deleted.
Anyhoo, here's something fun to try or something irritating depending on if you've had this happen yet already. Find a versioned file, one with a green checkmark and whatnot, then delete it by pressing DEL or dragging it to the Recycle Bin. Now do a SVN Update. It comes back! TortoiseSVN sees that you don't have a file which is in the repository (and in this case, still in the working base) and thus re-creates it.
In order to delete a file from the repository you need to use TortoiseSVN > Delete. The file will usually disappear, and a folder will do the same if you delete it. However, if it happens to come back before you commit, for whatever reason, it will have a red 'X' overlay. This signifies, like the plus sign for add, that when you commit the files will be deleted.
Launching SVN Commit when files are marked for deletion will list them out along with that action. As with anything else, and I can't say this often enough, you won't actually delete the files from the repository until the commit has completed. If someone else has already deleted the files from the repository, you will be rebuffed and have to do SVN Update.
Part 9: Move and Rename
Pre-requisite(s): Working copy of a project in Subversion.
Goal(s): Move and Rename.
Both of these, although different menu options, do practically the same thing. You see Subversion has no server-side method to indicate a move or rename. What TortoiseSVN actually does at the repository level is delete the previous file/folder and add it some place else. This isn't as taxing as it sounds.
First we'll do a rename, because it's simplest. Add a file with an improper name to your working copy so we can try this. Right-click it and select TortoiseSVN > Rename. The dialog you'll get is about as simple as you can get, just type in the name.
Now do SVN Commit and you'll see it's going to delete the file of the old name and add the one with the new name. When you click OK then you won't actually be uploading the file data (unless you've changed the renamed file of course); TortoiseSVN and Subversion are smart enough to know that the file data is the same. [8]
Moving files and folders is only slightly more complicated. First, make sure where you're moving them to is already versioned. That is, if the folder you're moving them to isn't already in the repository, then add it. [9] Then to do the move, right-drag (click and hold the right mouse button) the item(s) to the new folder. When you let the mouse button up, select Move versioned files here from the context menu.
Just like a rename, when you do your SVN Commit you will see the files in their previous location marked as deleted at the same time as being added to the new location.
To undo a rename or move before committing, select TortoiseSVN > Revert from the folder above both locations. Make sure to check the boxes next to both the deletes and the adds before clicking OK.
Goal(s): Move and Rename.
Both of these, although different menu options, do practically the same thing. You see Subversion has no server-side method to indicate a move or rename. What TortoiseSVN actually does at the repository level is delete the previous file/folder and add it some place else. This isn't as taxing as it sounds.
First we'll do a rename, because it's simplest. Add a file with an improper name to your working copy so we can try this. Right-click it and select TortoiseSVN > Rename. The dialog you'll get is about as simple as you can get, just type in the name.
Now do SVN Commit and you'll see it's going to delete the file of the old name and add the one with the new name. When you click OK then you won't actually be uploading the file data (unless you've changed the renamed file of course); TortoiseSVN and Subversion are smart enough to know that the file data is the same. [8]
Moving files and folders is only slightly more complicated. First, make sure where you're moving them to is already versioned. That is, if the folder you're moving them to isn't already in the repository, then add it. [9] Then to do the move, right-drag (click and hold the right mouse button) the item(s) to the new folder. When you let the mouse button up, select Move versioned files here from the context menu.
Just like a rename, when you do your SVN Commit you will see the files in their previous location marked as deleted at the same time as being added to the new location.
To undo a rename or move before committing, select TortoiseSVN > Revert from the folder above both locations. Make sure to check the boxes next to both the deletes and the adds before clicking OK.
End Notes
[1] Current editions of both Share Point and Team Foundation Server require you to checkout to modify files.
[2] VSS supports "Multiple checkouts", but there are enough issues with them that they are rarely used.
[3] When the amount of conflicts becomes especially cumbersome, there is the option of using branches for smoother, parallel development.
[4] You'll also find TortoiseSVN on the File menu of Explorer windows, but this tutorial deals exclusively with right-click (context) menus.
[5] When you install Visual SourceSafe, it will typically set you up a local database. TortoiseSVN doesn't do this.
[6] If you want to use Visual Studio 2003 and Web Projects (ASP.NET 1.1), however, working copies will have to store their information in a _svn directory (not .svn).
[7] No commit, no change made to repository. It's that simple. All changes from a working copy must be commited. Using the Repo-browser doesn't utilize a working copy and therefore doesn't have a commit, and happens immediately.
[8] When you make a small change to a large binary file, the commit doesn't take very long because TortoiseSVN just tells the Subversion repository what the changed bytes are.
[9] It's possible to add folders and move things into them at the same time. The old files/folders will simply be deleted and added at their new location along with the new folder.
[2] VSS supports "Multiple checkouts", but there are enough issues with them that they are rarely used.
[3] When the amount of conflicts becomes especially cumbersome, there is the option of using branches for smoother, parallel development.
[4] You'll also find TortoiseSVN on the File menu of Explorer windows, but this tutorial deals exclusively with right-click (context) menus.
[5] When you install Visual SourceSafe, it will typically set you up a local database. TortoiseSVN doesn't do this.
[6] If you want to use Visual Studio 2003 and Web Projects (ASP.NET 1.1), however, working copies will have to store their information in a _svn directory (not .svn).
[7] No commit, no change made to repository. It's that simple. All changes from a working copy must be commited. Using the Repo-browser doesn't utilize a working copy and therefore doesn't have a commit, and happens immediately.
[8] When you make a small change to a large binary file, the commit doesn't take very long because TortoiseSVN just tells the Subversion repository what the changed bytes are.
[9] It's possible to add folders and move things into them at the same time. The old files/folders will simply be deleted and added at their new location along with the new folder.