Ok, in the last part we spend some time on the basic idea of Version Control Systems, installed a subversion server, a nice client to connect to the server and created a repository we can store our files in. Now it’s time to get some practice. The example steps shown here assume an installation as shown in the last post. And best would be if you just follow these examples on your own installation. It will take you roughly half an hour and you will be able to handle your first projects completely under control.
Create a new Project
The base of our work are Projects. A project does not necessarily need to be large. It can even be lets say a couple of your administrative scripts you have written for your work. As the “project” in subversion is nothing more than a folder that becomes a project by convention, we are free to even implement a structure for our projects. So if you have a lot of projects, you might want to group them.
Let us start with this idea and first create a “group” or simply a folder that will host a couple of our projects. As this Blog is mainly about MDT, let’s call it “MDT” to host all our MDT-related projects.
The easiest way is using the VisualSVN Server console. Just right click on your repository (we are using the “sandbox” created in the last post for this examples) and choose “New – Folder…”
and type in the new Folder name
if you want you can also click on Details and supply some additional information for the commit so this shows up in the log (more on this later).
Now we add our new project. Just right click on our new folder “MDT” and choose “New – Project Structure…”
and give it a name. In this example I use a small project that I’ve published a few months ago about Setting the Computer Description in Active Directory during MDT Deployments. This example is actually so small most people wouldn’t even consider it a project (two scripts and a configuration file). But bear with me, it really makes sense and due to its size it is also a nice example. So I call this project “SetComputerDescription”. Again you can supply more Details for the commit if you want to.
The console is helping us a bit and already creates a structure for our trunk, branches and tags.
The same can be achieved using the “Repository Browser” of Tortoise. It just requires some additional manual work as we would need to create the subfolders ourselves.
Connect to the Repository
Now it’s time to start working. But before we can do anything, we need to connect to our new repository. As Tortoise is a Windows Shell extension, we actually use the Windows Explorer. For this examples I created a new folder on my hard drive called “Working”. It will contain our Working folders that we check out from the repository. Now within this folder (or any other folder as well) right click and choose the “Repo-browser” from the TortoiseSVN context menu.
This will open up the Repository browser and first ask for an URL to connect to. How do we get the URL of our Repository now? Well, the easiest way is again using the VisualSVN Server Console. Just right click on your repository (or any other folder) and choose “Copy URL to Clipboard”.
Now in the Repo-browser, paste the copied URL
and click OK. On default this will be a https connection and VisualSVN is using a self-signed certificate for this. As this self-signed certificate isn’t trusted Tortoise will show a warning message stating that the certificate issuer is unknown. For this guide we simply Accept this.
Then it will ask you for username and password, if you configured authentication (what I recommend). Just check the “Save authentication” checkbox and Tortoise will save and re-use your credentials whenever you connect.
The Repo-browser itself is pretty self-explaining. You can browse within your repository, see the Files and folders, the Revisions and Author etc.
As mentioned already we would also have been able to create our folders using the Repo-browser. Just right-click on any of the folders (or files) and you will see a context menu with a whole bunch of additional actions including “Create folder…”. We will go through some of them later in this guide.
Get a Working Copy
As we can connect to the repository now, it’s time to start working on our new project. So lets get a copy we can work on. The process to do this is called “Checkout”. You can do this either from the Repo-browser or directly from the context menu. As we have the Repo-browser still open, right click on the trunk (!) of our project and choose “Checkout…”. Why the trunk? Well because this is a new project and per definition the trunk hosts the project. We will have a look on branches a bit later. This will now open up the following dialog
One thing you nee to be aware when checking out a project (or folder) is, that you check out the content(!) of the folder. Not the folder itself. So be sure to point it the correct folder. In this example I simply typed “SetComputerDescription” into the Checkout Directory field. If the Directory does not exist, it will be created during the checkout. So be careful with this. To hammer this into your mind, You just get the content, not the folder itself! The good thing about this is, that you can actually use a different name as Trunk isn’t really self-explaining.
The rest of the options can be ignored at this time. They are just needed for more advanced and complex scenarios.
We now have an empty folder in our C:\Working directory called “SetComputerDescription”. Well, it’s not really empty as it contains a “_svn” folder but this one is hidden and used by Tortoise to keep track on your changes. So don’t mess around with it! (If you haven’t changed the default settings of Tortoise as shown in the last post, this folder would have the name “.svn”. If not done yet I recommend changing this now. See the last post for details).
Add some content
Let us add some files to it. The example required two scripts and a configuration file (customsettings.ini). So for demonstration purposes I create three empty files. After adding these files you will see them with a different icon in your Windows Explorer. Tortoise is using overlay Icons to show the status of a file/folder. In our cases it is showing up as just added (or better to say they show up as “not versioned”). Our Working Copy now contains a couple files that don’t exist in the repository.
Commit changes
We can change our working copy as often and long as we like. We can add new files/folders, change existing ones or even remove them if necessary. But this changes exist currently only in our local copy. If we now want to update our repository with these changes, we need to commit them.
Again we can use the context menu of Tortoise for this. Right click anywhere in your working copy and choose “SVN Commit…”
This will open up a dialog showing all the changes made. If you clicked on a folder it will only show the changes to that folder and subfolders. If you clicked on a file it will only show changes made to this file. Mark the ones you would like to commit and add a comment that will describe the changes done. In our case the all show up as “non-versioned” as they haven’t been added to the repository yet.
Another dialog will show the progress also any error that might have happened.
And the overlay Icons will show us now that these files are in-sync.
If we edit one of the files it will immediately show up as changed
This way you have an easy and direct feedback on the status of your files. It is also very easy to identify which files and folders are under version control. This is important as you can create your Working copies wherever you want. How often you should commit your changes depends on you. It’s recommended to do this at least every couple hours if your are continuously working on it. But latest if you finish your work for the day it’s a good time to commit all your changes. If you are unsure what to do, just commit more often. It doesn’t hurt. ;-)
Note: If you want to delete or rename a file/folder, the recommended way is to use the context menu of TortoiseSVN. It’s very recommended on files but actually a Must Do on folders. It can become pretty picky if you rename folders in the explorer directly and quickly comes out of synch.
To give an example on the difference it makes. We have to files that we might have been working on before. The first one got renamed directly in Explorer. The second one using the recommended way via TortoiseSVN. Just look at the overlay icons:
The first one is “non versioned” the second one “added”. OK, added doesn’t really sound that much better than not versioned but lets commit this change
What do we see here. The correctly renamed file is checked already. It also shows up as deleted and added. The other one needs to be checked by hand and shows up as “missing” and non-versioned. Not convinced? look at the log of the commit
The interesting part is the “Sending content”. This just appears for the first file. So if you rename a file in explorer, it’s actually a completely new file for the version control system and the old one is gone. Including the whole history. On the second one it knows (kind of) that it got renamed.
Have a quick look on the log of the two files. The left one shows the second one renamed correctly, the right one the first one that obviously lost its history (you need to uncheck the “Stop on copy/rename” to show the full history.
So keep in mind Delete and Rename of versioned files and especially folders only(!) via the appropriate TortoiseSVN actions!
Check for Updates
In cases you are not the only one working on a specific project or you have several working copies of it (yes, that’s possible and sometimes necessary), there might be changes in the repository that a working copy is missing. In these cases you should regularly check for updates as Tortoise will not do this automatically.
Again right click somewhere in your working Copy and click on “SVN Update”. As with a commit the update will be limited to the folders/subfolders you have chosen.
As you can see someone has added two folders to the project but they are now also part of our Working copy.
Tagging
Every time you release a version, you should make a read-only copy of it. This copy is called Tag. It’s read-only by convention as Subversion itself will not limit you to make any changes. But this convention has a couple good reasons so try to stick to it. It will make your life easier. The biggest advantage is, that you always have access to these versions. Might be to answer a specific question, do some support, fix a bug specific for that version etc.
So if you hand-out a release of your current code/files/project create a Tag first and hand out a copy of this Tag.
OK, we assume our great script has reached a point to get released to the public. We have tested it and everything seems to be working well.
How do we now Tag this release? Just right click your working copy and choose TortoiseSVN – Branch/Tag (The difference between a Branch and a Tag is just the mentioned convention).
It will open up a new dialog that will help you creating a Tag
There are a couple things to mention here. First you will see that the source will be the trunk and the target will be a new folder beneath the tags folder. For simplicity reasons just called Version_1. And it will create this copy based on a specific revision in the repository. This enables you to create this even later if additional changes have been implemented already. (You simply forgot to create it the time you send it out ;-) ) Click on the “…” Button to see a log of all revisions if you are not sure about the right one. You can also choose “Working copy” so it will create the tag based on your current working copy.
If you check the checkbox at the bottom your current Working copy will also switch to this new copy in the repository. This isn’t really necessary on Tagging but very helpful if you create a branch and you would like to immediately start working on it.
Now after you have created a Tag you most probably want to use this to publish it, or give it to a customer or to have some QA testing etc. Creating a Working Copy of that Tag isn’t really a good idea as we shall (must) not apply any changes to it. So the easiest way to get a copy is to export the folders you need. To do this just right click on a folder that you would like to export this version into and choose TortoiseSVN – Export…
and then choose the appropriate folder from your tagged version
That’s it
Just zip and deploy it.
Create a Branch
Every time you need to make changes to your project but need to retain it in an always working condition it is helpful to not work directly on the main project itself. It’s better to make a copy of the current project and implement your changes on this copy. This copy is called a “Branch”. The process is almost identical to creating a Tag as shown before. Again right click in your Working Copy and choose TortoiseSVN – Branch/Tag.
Again the source is the trunk itself. The target is a new folder beneath the branches folder. In our example let say a bug has been found in Version 1 of our script and we need to fix this bug. And as we would like to start working on this immediately, we also tell it to switch our current Working copy to this new branch.
OK, it says it has switched but how do we know what our Working copy is pointing to at the moment? Well just right click in your Working copy and choose Properties. You will see a new tab in there called “Subversion” that gives us a lot more helpful information about this
So everything we do now in our working copy and commit to the repository will update the “BugFixing” branch of our project.
Merging changes
All copies are per definition independent from each other. Otherwise we wouldn’t need to create them. So changes applied to one copy stay there. But most often these changes are important for the other copies as well. Changes implemented into a branch need to get back into the trunk at some time to improve the whole project. Or maybe changes in the trunk (e.g. bugfixes) shall be applied to long running branches as well to keep them up to date. So we need a way to merge this changes in different ways.
Merging changes from the trunk
In the last part we created a new branch. Now we assume that we had to implement an important change into our main project (the trunk). Let say we had to change the header and it’s important that this change is implemented in all our branches as well.
OK, we need to right-click again in our working copy (it’s a working copy of the branch) and choose “Merge…”
In the following dialog we select to “Merge a range of revisions”
and set our Trunk as the source for the merge
We could also explicitly define the revisions we want to merge. Just click on “Show log” to get more information about the revisions
As we can see with Revision 11 there has been an update to the header and the file ZTICreateComputerDescription.wsf has been modified. You want to know what exactly has been changed here? No problem. Right click on the revision and choose “Show changes as unified diff”
and it will show you exactly what has been changed
Or right click on the revision and choose “Compare with previous revision” which will open up a new dialog where you can choose the revision to compare
If you know double click the modified script it will open up the TortoiseMerge tool
OK, we know what has been changed now and want to continue merging the changes. We leave the Revision range empty so that all changes are merged and click on Next. Now we have some additional options
These options can actually be ignored in most cases (This post is already to long to get into any more details ;-) ). You can spend some time digging through the different options as soon as you are used to the basic steps. Now we can finally Merge the changes
And are done. The merge has actually happened to our local copy of the branch. So it needs a commit to update the changes in the repository.
Merging/Reintegrating a branch back into the trunk
We can also merge any changes from the branch back to the trunk as shown before. This happens mostly at the end of the development on this branch. If really all changes are done we can even reintegrate this branch back into the trunk. Doing this takes an extra step. We first need to switch our Working copy back to the trunk. So right click in you current working copy of your branch and choose TortoiseSVN – Switch…
and point it to the trunk
Now we can just merge some changes back to the trunk or reintegrate the whole branch back into the trunk. To do this we select again the “Merge…” in the context menu and use the second merging option shown before to “Reintegrate a branch”
we select the branch we would like to reintegrate
again we don’t need to change any of the additional options
and are done
After that we again need to commit the changes to the trunk (as the merge has happened to our Working Copy). Now we could actually delete the old branch as it is not needed anymore. You can keep them if you want but there is no real reason of keeping old/outdated branches. They just waste space.
Import existing Projects
As we have just started with putting our stuff under version control, we have a whole lot of projects that still exist somewhere else. If we need to continue working on them it might make sense to import them before changing anything. There are a couple ways we can do this. First you should create the default project structure in the repository as shown before using the VisualSVN Server console. Then the most obvious way is to right click on the folder containing the project and choose TortoiseSVN – Import…
Point it to the trunk of the new project structure that you have just created before
And you are done
One drawback about this way is, that you can’t immediately start working. You would need to get a Working Copy first. OK, to be honest, that’s not really a Drawback. It takes a few more seconds, that’s all.
But there is another way you might find helpful. Again we create the Project structure first in the repository. Then we create a Working Copy of the new (empty) trunk and point it to the root folder of our existing project.
After clicking on OK Tortoise will warn you that the target folder is not empty. Confirm that you are sure.
All your files and folders within the project will show up as not versioned. So all it needs now is a commit and your complete project will be checked into the repository. And you can keep on working without any extra step.
Change Revision
One of the biggest advantages of using a Version Control System is the possibility to change files or even complete folders (or projects) to a different revision (from a newer to an older revision or vice versa). Pretty naive I was looking for something like “Revert back” or similar. But as you can update it into any revision it’s called “Update to revision…” in the context menu of Tortoise
Then choose the revision you would like to change to
If you are unsure about the Revision use the “Show log” button to see all the changes on this file/folder
Wow, that was definitely the longest post I’ve written so far. Even so I hope you enjoyed it. Using a version control systems isn’t really complicated but will make your life much easier. Just give it a try for some time. It’s not only for professional developers. We all can benefit from such solutions. In the next post I will try to show some ways how we could combine this simple methods of version control into our Deployment solutions.
I’m interested to hear your comments about this. Are you using such a solution already? Do you consider it using in the future? Do you have some best practice or ideas on make an Administrators life easier?