Using TortoiseSVN (tutorial)

Guided Tour

Overview

This tutorial explains how to use the Subversion front end client TortoiseSVN to manage a project located in the IgorExchange Subversion repository. Though some of the specifics below are based on the layout of the IgorExchange repository, the tutorial itself should be helpful to TortoiseSVN users regardless of whether they are maintaining a project on IgorExchange.

TortoiseSVN is a graphical front end client for Microsoft Windows that can be used to interact with the IgorExchange Subversion repository. For an overview of key Subversion concepts, please read the Subversion Basics section of this handbook first. TortoiseSVN version 1.4 or greater is required for proper communication with the IgorExchange projects repository. TortoiseSVN can be downloaded from the TortoiseSVN Download Page.

The TortoiseSVN project maintains separate documentation that is specific to the use of TortoiseSVN. References to the TortoiseSVN Manual are made for the various operations below, where appropriate. Subversion has many powerful features, many of which are not used on IgorExchange or which are not necessary to use the features of IgorExchange. The official Subversion documentation is the Subversion Book.

See Server and Repository Settings for specific authentication and server settings information.

Back to top

TortoiseSVN Configuration

If you ever plan to import, add, or commit files to the IgorExchange repository, you must first modify your TortoiseSVN configuration file in a few places so that TortoiseSVN knows how to handle certain types of files, including Igor Pro procedure files.

  1. From Windows Explorer, right click on any directory or file and select TortoiseSVN --> Settings. On the left of the dialog, the "General" section should be selected.
  2. On the right side of this dialog, click the "Edit" button to edit the Subversion configuration file.
  3. The TortoiseSVN configuration file will be loaded in your default text editor (this is usually Notepad). Scroll down towards the end of the configuration file to the [miscellany] section.
  4. You need to uncomment two settings, as indicated below by the <----- markers. To uncomment a setting, remove any # or space characters from the beginning of the line. Make sure that the line in your configuration file looks identical to the line in the example below (except that you should not include the <----- text in your actual configuration file).

    [miscellany]
    ### Set global-ignores to a set of whitespace-delimited globs
    ### which Subversion will ignore in its 'status' output.
    global-ignores = *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store <------
    ### Set log-encoding to the default encoding for log messages
    # log-encoding = latin1
    ### Set use-commit-times to make checkout/update/switch/revert
    ### put last-committed timestamps on every file touched.
    # use-commit-times = yes
    ### Set no-unlock to prevent 'svn commit' from automatically
    ### releasing locks on files.
    # no-unlock = yes
    ### Set enable-auto-props to 'yes' to enable automatic properties
    ### for 'svn add' and 'svn import', it defaults to 'no'.
    ### Automatic properties are defined in the section 'auto-props'.
    enable-auto-props = yes <-----
    Note: Do NOT include the <----- markers in your configuration file.
  5. Now find the [auto-props] section in the config file. It should be just below the [miscellany] section that you just edited.
  6. Copy and paste the following block of text to the end of the [auto-props] section. These settings tell TortoiseSVN how to handle line endings for text files.

    #####
    # Text file formats
    #####
    *.txt = svn:eol-style=native
    *.xml = svn:eol-style=native
    *.xslt = svn:eol-style=native
    *.xsl = svn:eol-style=native
    *.html = svn:eol-style=native
    *.xhtml = svn:eol-style=native

    #####
    # Image file formats
    #####
    *.png = svn:mime-type=image/png
    *.jpg = svn:mime-type=image/jpeg
    *.gif = svn:mime-type=image/gif
    *.tif = svn:mime-type=image/tiff
    *.bmp = svn:mime-type=image/bmp
    *.icns = svn:mime-type=image/icns
    *.wmf = svn:mime-type=image/wmf
    *.emf = svn:mime-type=image/emf

    #####
    # Igor Pro file formats
    #####
    ### Text
    *.ipf = svn:eol-style=native
    *.itx = svn:eol-style=native
    *.csv = svn:eol-style=native

    ### Binary
    *.xop = svn:mime-type=application/octet-stream
    *.ifn = svn:mime-type=application/octet-stream
    *.ihf = svn:mime-type=application/octet-stream
    *.ift = svn:mime-type=application/octet-stream
    *.pxp = svn:mime-type=application/octet-stream
    *.uxp = svn:mime-type=application/octet-stream
    *.uxt = svn:mime-type=application/octet-stream
    *.pxt = svn:mime-type=application/octet-stream
    *.ibw = svn:mime-type=application/octet-stream
    *.ibt = svn:mime-type=application/octet-stream
    *.ibv = svn:mime-type=application/octet-stream

    #####
    # Code file formats (text)
    #####
    *.c = svn:eol-style=native
    *.cpp = svn:eol-style=native
    *.h = svn:eol-style=native
    *.hpp = svn:eol-style=native
    *.r = svn:eol-style=native
    *.rc = svn:eol-style=native
    *.rtf = svn:eol-style=native
    *.odi = svn:eol-style=native
    *.reg = svn:eol-style=native
    *.plist = svn:eol-style=native
    *.f = svn:eol-style=native
    *.f90 = svn:eol-style=native
    *.f95 = svn:eol-style=native

    #####
    # Other binary file formats
    #####
    *.a = svn:mime-type=application/octet-stream
    *.dll = svn:mime-type=application/octet-stream
    *.lib = svn:mime-type=application/octet-stream
    *.pdf = svn:mime-type=application/pdf

  7. Save your edited configuration file.
    Note: If you are using Notepad to edit this file, you must follow these steps for the file to be saved without the usual .txt extension:

    1. Choose File --> Save As
    2. Make sure that the File Name field says: "config". The quotation marks are required.
    3. Click the "Save as type" selection box and choose All Files.
    4. Click the Save button.
  8. After you have saved the modified config file you can close the text editor.
  9. Click the OK button on the TortoiseSVN Settings dialog.

For an explanation of the configuration changes you just made and a complete sample config file, see Configuring your Subversion client.

See also:

Back to top

Getting data into the repository

In order to add data to the repository, you first need to create a project. Also, if you do not already have Subversion access, you first need to apply for Subversion access.

  1. Using Windows Explorer, create a directory on your computer with the same name you entered in the Project short name field of the project creation form. The project short name we will use for this example is widget1.
  2. Under the directory you just created, create three subdirectories and name them trunk, branches, and tags. Make sure to use these exact names and make sure the names are all lowercase. At this point it's best if these directories are empty. You can add the actual files to your project later on (see Adding files to the repository).
    Your directory structure should now look like this:

    widget1/
    trunk/
    branches/
    tags/
  3. Right click on the directory named widget1 and choose Tortoise SVN --> Import.
  4. For the URL of Repository field, enter

    svn://svn.igorexchange.com/packages/widget1
    Of course, change widget1 to the short name of your project. Also, make sure to enter a log message in the Import Message box, because all changes to the repository require a log message. For example

    Initial import of directories for widget1 project.
  5. Click OK to start the import. Assuming that you don't get an error message, move on to the next step.
  6. Now that you have imported the directory structure for your project into the repository, you can now delete the widget1 directory on your computer that you just created. Doing this will help to prevent confusion in the next step of this tutorial.

See also:

Back to top

Checking out a working copy

Whenever you want to modify code for a project on IgorExchange, you first need to create a working copy of the project files on your personal computer, and then you can modify the files in your working copy and later send those changes to the repository on the server.

To continue with the example, even though you have already imported your project's directory structure into the repository, you have not yet added any files to it. You first need to check out the contents of the trunk directory from the repository into a working copy on your computer. You will then copy any of your project's files into this working copy, and then commit those changes to the repository. From this point on, any changes you make to the repository will be made by first making changes to the working copy of your project on your computer and then committing those changes to the repository.

  1. From Windows Explorer, create or change to a directory on your computer under which you want to store any working copies of IgorExchange projects. You might want to call this directory my_igorexchange_working_copies.
  2. Create a directory your computer under the my_igorexchange_working_copies directory to hold the working copy you are about to check out. Call this directory widget1_working. Because this new directory will contain the working copy of your project, it is best to name that directory with the _working suffix so that it is obvious that this directory contains a working copy of a project.
  3. Right click on the widget1_working directory and choose SVN Checkout.
  4. Since right now you just want the contents of the /trunk directory in your working copy, change the "URL of repository" setting to
    svn://svn.igorexchange.com/packages/widget1/trunk and click the OK button.
  5. You should now have a green check mark icon next to your widget1_working directory. At this time, there will be nothing in this directory except for a hidden directory called .svn. You should never delete or modify the .svn directory or any files within the .svn directory, as they are used internally by TortoiseSVN.

See also:

Back to top

Adding files to the repository

Now that you have checked out a copy of the /trunk directory from the repository into your working copy directory, it is time to add some files to the repository.

  1. Using Windows Explorer, copy the files necessary for your project into your working copy directory. The example working copy directory now looks like this:
  2. Right click on the name of the working directory (widget1_working) and choose TortoiseSVN --> Add. In the dialog, check the box for each file you wish to add to the repository.
    Note: Certain types of files, like temporary files and non-essential files, should not be added to the repository. Just make sure not to check the box next to these types of files so that you don't add them to the repository. You can also tell TortoiseSVN to ignore certain files. See Ignoring files in the TortoiseSVN manual for information on how to do this. The dialog box should now look something like this:
  3. Click the OK button. The icons representing the files you have just added are now be marked with a blue '+' sign:

    and the widget1_working directory now is marked by a red exclamation point icon, like this:

    The red exclamation point indicates that the directory contains files that have been changed since the last time the working copy was updated (see Updating topic below).
  4. At this point, you have told TortoiseSVN that you wish to add these files to the repository, but you have not yet actually added them to the repository. To do that, you have to commit the changes back to the repository. See the next topic for an explanation of how to do this.

See also:

Back to top

Commiting your changes to the repository

After you have added or removed files or made changes to your code (and tested those changes to make sure they work), you should commit those changes back to the repository so that others can access the changes. In this example, you have now informed TortoiseSVN that you wish to add widget1.ipf and widget1.ihf to the repository, but you now must commit that change to the repository.

  1. From Windows Explorer, right click on the widget1_working directory and choose SVN Commit.
  2. In the dialog, type in a commit message (log messages are always required). Make sure that the "Changes made" list has a check next to both of the files you want to add.
  3. Click the OK button. If the commit worked, you will now see a dialog that says "Finished" and that indicates that the files were added to the repository.

Notes:

  • If you want to commit changes from only one file in your working copy (instead of the entire directory), you can right click on the file itself and choose SVN Commit.
  • Instead of right clicking on a file and choosing TortoiseSVN --> Add, you can also add a file to the repository by checking the box next to the file in the "Changes made" section of any commit dialog.
  • In order to commit changes to a project, you must be the owner or a maintainer of that project.

See also:

Back to top

Updating your working copy with changes from others

If your project has additional project maintainers other than yourself, these people are permitted to commit changes they have made to code for your project back to the repository. In order to be certain that the code you edit contains all the recent changes made by other project maintainers, you should update your working copy regularly.
Note: Because updating your working copy is a read-only operation, you do not have to be a project maintainer or have a Subversion account to follow these steps.

  1. Right click on the working directory of your project (widget1_working) and choose SVN Update.
  2. If, after updating your working copy, you receive any error messages or warning messages in the dialog, there may be a conflict between a file in your working copy and the version of the file in the repository (often by someone else). This can happen if you have edited a file since you last updated your working copy and during that time a change to that same file was committed back to the repository. If this happens, you will need to resolve the conflict in the two files. See Resolving conflicts in the TortoiseSVN online manual for more information on conflicts and how to resolve them.

See also:

Back to top

Creating branches

On IgorExchange, branches and tags are used for development and snapshot releases, respectively. If you are not yet comfortable with the idea of branches and tags, or if you do not understand when to use a branch and when to use a tag, please read the documentation on Branches and Tags before you proceed.

Subversion treats branches and tags just like any other directory in the repository. Fortunately, TortoiseSVN provides a special interface for creating and using branches and tags. In order to create a branch you must be the owner or a maintainer of the project.

So far you have only been modifying files in the /trunk directory. In this example, the /trunk directory may contain code that uses the latest and greatest features of Igor 6. But what if you want to create a version of the project that is designed to be specifically compatible with Igor 5.05? To do this, you can create a branch of the project for Igor 5.05. If you modify any files in this branch, you will make sure that none of the new operations and functions introduced in Igor 6 are used in these files. Another reason to use branches might be if the project required different files to work on Windows versus Macintosh computers.

When you create a new branch following the instructions below, all Subversion-controlled files in your working copy will be copied into the branch you create. The branch you will create will be targeted for Igor 5.05. You will call this major version 1 of the project (you can create minor versions such as 1.0, 1.1, etc. by creating tags, as described in the next section). Based on the rules for branch naming set forth in Branches and Tags, the new branch will be named IGOR-5-05--1. Note that there are two hyphens separating the Igor Pro version from the version of the project.

  1. From Windows Explorer, right click on the project's working copy directory (widget1_working) and choose TortoiseSVN --> Branch/tag.
  2. In the dialog, make sure that the "From WC at URL" field reads

    svn://svn.igorexchange.com/packages/widget1/trunk
    In the "To URL" field, enter

    svn://svn.igorexchange.com/packages/widget1/branches/IGOR-5-05--1
    If you were creating a branch of a different name, you would substitute that branch name for IGOR-5-05--1.
  3. Enter a log message. For example,

    Created branch IGOR-5-05--1 from /trunk
  4. Make sure that in the "Create copy in the repository from:" group you have checked "HEAD revision in the repository".
  5. At the bottom of the dialog, check the "Switch working copy to new branch/tag" box. This will change your working copy directory so that it reflects the new branch you are creating, instead of representing a working copy of the /trunk directory as before.
  6. Click OK and you should see a message telling you that the new branch was created.
  7. Any changes you make and then commit to the files in your working copy will now be committed to the new branch you created (assuming you checked the "Switch working copy" checkbox). If at some point you wish to have your working copy reflect the contents of the /trunk directory, see Switching your working copy.

See also:

Back to top

Creating tags

On IgorExchange, branches and tags are used for development and snapshot releases, respectively. If you are not yet comfortable with the idea of branches and tags, or if you do not understand when to use a branch and when to use a tag, please read the documentation on Branches and Tags before you proceed.

Subversion treats branches and tags just like any other directory in the repository. Fortunately, TortoiseSVN provides a special interface for creating and using branches and tags. In order to create a tag you must be the owner or a maintainer of the project.

In the last step, you created a branch of your project called IGOR-5-05--1. This branch represents major version 1 of your project and indicates that that branch requires Igor Pro version 5.05. After working on the code in that branch, you will eventually decide that the code works as intended and you wish to create a "tag" based on that code. Tags are very similar to branches, but once a tag is created the files in that tag should never be changed. This gives you a static release of your package, instead of the frequently changing code found in the branch. If a user tells you that he is using the IGOR-5-05--1-0 official release of your project (official releases are always built from tags), you will know exactly what code he is using because the files in that tag will never change.

As with branches, it may be necessary to create a tag for each operating system. So, for example, you might need to create both a IGOR-5-05--1-0-WIN and a IGOR-5-05--1-0-MAC tag for your project if you were creating an XOP that had both a Windows and a Macintosh version.

If you created a branch in the previous step, and if you checked the "Switch working copy" box, the files in your widget1_working directory now represent the files from the IGOR-5-05--1 branch. You will create your IGOR-5-05--1-0 tag based upon the files in the IGOR-5-05--1 branch . When you create a new tag following the instructions below, all Subversion-controlled files in your working copy will be copied into the tag you create.

  1. From Windows Explorer, right click on the project's working copy directory (widget1_working) and choose TortoiseSVN --> Branch/tag.
  2. In the dialog, make sure that the "From WC at URL" field reads

    svn://svn.igorexchange.com/packages/widget1/branches/IGOR-5-05--1
    In the "To URL" field, enter

    svn://svn.igorexchange.com/packages/widget1/tags/IGOR-5-05--1-0
    If you were creating a tag of a different name, you would substitute that tag name for IGOR-5-05--1-0 in the "To URL" field.
  3. Enter a log message. For example,

    Created IGOR-5-05--1-0 tag from IGOR-5-05--1 branch
  4. Make sure that in the "Create copy in the repository from:" group you have checked "HEAD revision in the repository".
  5. Unlike when you created a branch, you should not check the "Switch working copy to new branch/tag" box when creating a tag, because you should never edit the files that make up a tag, and thus you don't need to switch your working copy to represent those files.
  6. Click OK and you should see a message telling you that the new tag was created. Because you did not select the "Switch working copy" box in step 5, you will get a notice that informs you that your working copy path was not changed. You can ignore this notice.

See also:

Back to top

Creating patches

For projects with multiple developers it usually isn't a good idea to give every developer commit (write) access to the project, because doing so makes it more difficult to control the quality of the code and the direction the project takes. It is often more effective if one or two people can commit changes to the repository while the rest of the developers suggest code changes by submitting patches.

By using the project's issue tracker on IgorExchange, users can make changes to the code on their own computers, create a patch, and then attach that patch to an issue. Other users can review the changes made in the patch and determine whether they are acceptable and whether the changed code is functional.

When the various developers agree that a patch is a good addition to the project, the project maintainer can then apply the patch to his working copy of the project and then commit those changes to the repository.

  1. To create a patch, it is best to start with a freshly updated copy of the branch or trunk on which you want to base your code changes. If necessary, you may need to run SVN Update to update your working copy.
  2. Make the changes to the code and be sure to test the changes thoroughly.
  3. Once you are happy with the changes, using Windows Explorer right click the working copy directory (widget1_working) and choose TortoiseSVN --> Create patch.
  4. In the dialog, place a check next to each file that you wish to include in the patch. A patch file can contain changes to multiple files or only one file. It is usually a good idea to include all changed files in a patch instead of creating a separate patch for each file that has changed. It is also important to make sure that all of the changes that are incorporated into a patch are related. In other words, you probably wouldn't want to create a patch that included code changes that did two completely different things. In that situation it would be best to create a separate patch for each group of changes.
    Note: Because TortoiseSVN cannot compare two binary files, any binary files you select to be included in your patch will effectively be ignored when creating the patch. To share changes in binary files with other developers you should attach those files to an issue in the issue tracker for your project.
  5. Click the OK button. TortoiseSVN will ask you where you want to save the patch. It is recommended that you save the patch with a .patch extension.
  6. Click OK and the patch file will be saved to the location you entered in the step above.
  7. Before you upload your patch file to the issue tracker for your project, you should inspect it to make sure that the changes in the file are correct. You can open the patch file in any text editor. A patch file is a text file that will contain + symbols at the beginning of every line that is added in the patch and a - sign in front of any line that is removed by the patch. For example, a simple patch file might look like this:
    Index: widget1.ipf
    ===================================================================
    --- widget1.ipf	(revision 235)
    +++ widget1.ipf	(working copy)
    @@ -2,4 +2,12 @@
     
     Function widget1()
     	print "This is widget1"
    +End
    +
    +Function newFunction()
    +	print "this is a new function"
    +End
    +
    +Function anotherNewFunction()
    +	print "this is another new function"
     End
    \ No newline at end of file

    The patch file will indicate which file the subsequent code applies to and the revision numbers of the base file(s). In the example above, the modified file reflected in the patch is widget1.ipf and the base revision is revision 235.
  8. After creating a patch, you should move it to a different directory so as to keep patch files separate from the code files in your working copy. Furthermore, if you are a maintainer of the project, doing so will ensure that you don't accidentally commit the patch file itself to the repository. Adding and committing a patch file to the repository will only clutter up the project's file structure but will not actually change its code. Any user can apply a patch to his own working copy of a project on his own computer (eg. for testing purposes), but for the changes reflected in a patch to get to the repository a project maintainer must first apply the patch to his own working copy of the project (see next topic) and then commit the changed code files to the repository.

See also:

Back to top

Applying patches

As a project developer, you may receive patches from other developers through the issue tracker for your project. Often it is possible to do a quick inspection of the patch itself using a text editor to see what changes are made to your file(s) and to see whether the changes make sense. If an initial review of the patch looks promising, you will want to apply that patch to your working copy so that you can test the code that results from applying the patch. TortiseSVN makes it simple to apply a patch to your working copy.

  1. If you haven't done this already, download the patch file to the computer that also contains the working copy of your project.
  2. From Windows Explorer, right click on the working copy directory (widget1_working) and choose TortoiseSVN --> Apply patch.
  3. In the dialog, select the patch file that you wish to use and click the OK button.
  4. If the file you selected is a valid Subversion patch file, an instance of Tortoise Merge will open. In the left most pane, you will see a list of all files in your working copy that are affected by the patch. Double click one of the file names to open that file in the right window. In this window you will see two views of the file: on the left side you see the file as it currently exists in your working copy; on the right side you see the file as it would be with the patch applied. Lines that are changed are highlighted in various colors. You can scroll through the file and make sure that the patch applies cleanly.
  5. If you want to accept the patch for that particular file, you can right click the file name in the left most window and choose "Patch selected". To accept the patch for all files, right click on a file name and choose "Patch all".
  6. After applying the patch to your working copy, you should test the files that were modified to make sure that the changes in the patch work properly and do what you expect. Once you are confident that the changes made are correct, you must commit those changes to the repository in order for others to see them.
  7. If, after applying a patch, you wish to go back to the previous revision before you applied the patch, you can revert to a previous revision.

See also:

Back to top

Reverting to a previous revision

After making changes to the files in your working copy, either manually or by applying a patch, you may wish to return those files back to the same state they were in after the last (or any prior) revision. Any changes made to files in your working copy that have not been committed will be lost (though you have the option of reverting changes to selected files in your working copy).

  1. From Windows Explorer, right click on your working copy directory (widget1_working) and click TortoiseSVN --> Revert
  2. The dialog will contain a list of files in your working copy that have changed since you last updated your working copy. Make sure that each file you want to revert is selected. If a file is not selected it will not be changed by the revert operation. When you have selected all of the files you wish to revert, click the OK button.

See also:

Back to top

Viewing code changes

TortoiseSVN includes a differences viewer that graphically indicates the differences between two text files. You can use this tool to inspect changes in your code between the version of the file in your working copy and the HEAD (most recent) revision of the file in the repository.

  1. From Windows Explorer, right click on the file for which you want to view the code changes and click on TortoiseSVN --> Diff. If Diff is not an option, that means that the file you selected has not changed.
  2. The TortoiseMerge program will be loaded with the old version of the file on the left side and the new version of the file (the version in your working copy) on the right. For more information on how to use TortoiseMerge, please see the TortoiseMerge Help.

See also:

Back to top

Switching your working copy

It is often necessary to work on several different branches of your project and/or the trunk, and there are two ways to do this.

  • Manually create several directories on your computer and check out working copies based on different parts of the repository into each of them. For example, after checking out several working copies, the directory structure on your computer, but not the repository, might look like this:

    /my_igorexchange_working_copies
    /widget1_trunk_working
    /widget1_IGOR-5-05--1_working
    /widget1_IGOR-6-01--2_working
  • Keep only one working copy on your computer and switch the part of your repository that that working copy represents. To use this method, follow these steps:
  1. Using Windows Explorer, right click on the working copy directory (widget1_working) and click TortoiseSVN --> Switch.
  2. In the "To URL:" field, enter the location in your repository that you want to switch your working copy to represent. For example, if your current working copy points to

    svn://svn.igorexchange.com/packages/widget1/trunk
    and you want to switch to your IGOR-5-05--1 branch, you would enter

    svn://svn.igorexchange.com/packages/widget1/branches/IGOR-5-05--1

    If you are not sure about the exact path that you want to switch to, you can click the "..." button next to the "To URL:" field and the repository browser will pop up and you can select the path this way.
  3. Click the OK button and your working copy will be switched to represent the new location.

See also:

Back to top

Troubleshooting

See the IgorExchange Subversion Troubleshooting page for general problems with Subversion and using Subversion on IgorExchange, including the TortoiseSVN specific troubleshooting section.

Back to top

Back to top