Using the Subversion command line interface (tutorial)

Guided Tour

Overview	Creating branches
Subversion Configuration	Creating tags
Getting data into your repository	Creating patches
Checking out a working copy	Applying patches
Adding files to the repository	Reverting to a previous revision
Commiting your changes to the repository	Switching your working copy
Updating your working copy with changes from others	Troubleshooting

Overview

This tutorial explains how to use the Subversion command line interface 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 Subversion users regardless of whether they are maintaining a project on IgorExchange.

The Subversion command line interface is a free, open source software package that is available for Windows, Macintosh, and Linux. Some versions of Macintosh OSX and Linux may already have Subversion installed.

Subversion version 1.4 or greater is required for proper operation. Binary distributions of subversion can be downloaded from the Subversion Packages Page.

Subversion has several 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. The information below will help you to familiarize yourself with the Subversion command line interface. References to the Subversion Book are made for the various operations below, where appropriate. All text from the Subversion Book is licensed under the Creative Commons Attribution License.

See Server and Repository Settings for specific authentication and server settings information for using Subversion with IgorExchange.

Subversion Configuration

To make Subversion easier to execute from the command line, you need to add the subversion directory to your path. The easiest way to do this is from the command line using Terminal.app (located in Utilities > Terminal).

Open a terminal window. Execute the following at the command line to open your .bash_profile file in an editor:
pico .bash_profile
Add the following lines to the file:
PATH="/usr/local/bin:/usr/local/subversion/bin:$PATH" export PATH
Hit Ctrl-O to save the file.
Close the terminal window and then open a new one so that the settings take effect.
You should now be able to enter svn at the command prompt and you should get the following output: Type 'svn help' for usage. If you get this output, Subversion is installed properly.

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

Using your favorite text file editor, open the Subversion config file. On the Macintosh, this file is usually located at /Users//.subversion/config. If you can't find this file, see How do I view/edit hidden files on the Macintosh.
Scroll down towards the end of the configuration file to the [miscellany] section.
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.
Now find the [auto-props] section in the config file. It should be just below the [miscellany] section that you just edited.
Copy and paste the following block of text to the end of the [auto-props] section. These settings tell Subversion 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
Save your edited configuration file (make sure not to change the name or location of the file).
After you have saved the modified config file you can close the text editor.

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

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.

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.
mkdir widget1
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).
cd widget1 mkdir trunk mkdir branches mkdir tags
Your directory structure should now look like this:
widget1/ trunk/ branches/ tags/
Make sure that you are in the widget1 directory and import the directories you just created into the repository.
svn import . svn://svn.igorexchange.com/packages/widget1 -m "Initial import of directories for widget1 project."You will be prompted for your Subversion username and password, and you should enter those. If you are importing a project of your own, change widget1 to the short name of your project. Also, make sure to enter a log message because all changes to the repository require a log message.
If the import was successful, you should see something like this:
Adding trunk Adding branches Adding tags
Committed revision 238.
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.
cd .. rmdir widget1

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.

Note: Because checking out a 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.

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.
mkdir my_igorexchange_working_copies cd my_igorexchange_working_copies
Right now, you want to check out only the trunk/ directory from the the repository. At the command line execute the following:
svn checkout svn://svn.igorexchange.com/packages/widget1/trunk widget1_workingIf the command executes successfully you should see something like this:
Checked out revision 238. The above command creates a new directory called widget1_working within the current directory. Because this new directory contains 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. At this time there is nothing in the 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 Subversion.

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.

Copy the files necessary for your project into your working copy directory. The example working copy directory now looks like this:
widget1.ihf widget1.ipf
From your working copy (widget1_working), execute the following to schedule these two files for addition to the repository:
svn add widget1.* and you should see the following message:
A widget1.ihf A widget1.ipf
Note: Certain types of files, like temporary files and non-essential files, should not be added to the repository. You can instruct Subversion to ignore certain files or file types. See Ignoring Unversioned Items in the Subversion book for information on how to do this.
At this point, you have told Subversion 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.

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 Subversion that you wish to add widget1.ipf and widget1.ihf to the repository, but you now must commit that change to the repository.

From your working copy directory (widget1_working), execute the following command:
svn commit -m "Added first files to widget1 project"Make sure that you enter a commit message or the commit will be rejected by the server.
If the commit was successful, you should get a message like:
Adding widget1.ihf Adding widget1.ipf Transmitting file data .. Committed revision 239.

Notes:

If you want to commit changes from only one file in your working copy (instead of the entire directory), you can provide the path to the file in the command, such as:
svn commit widget1.ipf -m "Added widget1.ipf to widget1 project"
In order to commit changes to a project, you must be the owner or a maintainer of that project.

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.

From your working copy directory (widget1_working), execute the following command:
svn update
If the update was successful, you should get a message like:
At revision 239.
If, after updating your working copy, you receive any error messages or warning messages, 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 (Merging Others' Changes) in the Subversion online manual for more information on conflicts and how to resolve them.

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. Even though Subversion treats branches and tags as copies, it provides a special command that should be used when creating 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.

Note: These instructions will create the new branch not from the working copy on your computer but from the files already in the repository. If you have made any changes to your working copy that you want to be included in the branch you are about to create, you must first commit those changes to the repository.

From your working copy directory (widget1_working), execute the following command (though this line wraps below, you should enter it on the command line as one line):
svn copy svn://svn.igorexchange.com/packages/widget1/trunk svn://svn.igorexchange.com/packages/widget1/branches/IGOR-5-05--1 -m "Created IGOR-5-05-1 branch from trunk"If you were creating a branch of a different name, you would substitute that branch name for IGOR-5-05--1.
The command above created a new branch in the repository, but the part of the repository your working copy represents has not changed. To switch your working copy so that it represents the new branch you just created, execute the following command:
svn switch svn://svn.igorexchange.com/packages/widget1/branches/IGOR-5-05--1
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 switched your working copy to the new branch in step 2. If at some point you wish to have your working copy reflect the contents of the /trunk directory, see Switching your working copy.

Creating tags

Subversion treats branches and tags just like any other directory in the repository. Even though Subversion treats branches and tags as copies, it provides a special command that should be used when creating 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.

Depending on the organization of your project, 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.

Note: These instructions will create the new tag not from the working copy on your computer but from the files already in the repository. If you have made any changes to your working copy that you want to be included in the tag you are about to create, you must first commit those changes to the repository.

From your working copy directory (widget1_working), execute the following command (though this line wraps below, you should enter it on the command line as one line):
svn copy svn://svn.igorexchange.com/packages/widget1/branches/IGOR-5-05--1 svn://svn.igorexchange.com/packages/widget1/tags/IGOR-5-05--1-0 -m "Created IGOR-5-05-1-0 tag from IGOR-5-05-1 branch."If you were creating a tag of a different name, you would substitute that tag name for IGOR-5-05--1-0.
The command above created a new tag in the repository, but the part of the repository your working copy represents has not changed. This is the desired behavior when creating tags, 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.

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.

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 first need to Update your working copy.
Make the changes to the code and be sure to test the changes thoroughly.
Once you are happy with the changes, go to your working copy directory (widget1_working) and execute the following command:
svn diff > patchfile.patch
The above command will create a file named patchfile.patch in your working copy directory. This patch file will contain all changes to every file in your working copy directory since the last time you updated your working copy.
If your Subversion client is version 1.5 or greater, instead of the above command (which should work just fine), you can use the following command:
svn diff -x -p > patchfile.patch
This version of the command tells Subversion to include more context about where the changes fall within the code, and makes it easier to understand what changes a patch makes just by looking at the patch.

Note: Because Subversion cannot compare two binary files, any binary files that are 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.
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.
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.

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. Subversion does not include a utility to apply a patch to your working copy, but most distributions of UNIX (including MacOS X) include a command line utility called patch that can be used to apply the patch to your working copy.

If you haven't done this already, download the patch file to the computer that also contains the working copy of your project. For this example you should put the file in your working copy directory.
From your working copy directory (widget1_working) execute the following command:
patch -p0 < patchfile.patch
Change patchfile.patch to the actual file name of the patch file.
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.
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. However, if you haven't changed the code in any way other than applying the patch, you might find it easier to just reverse the patch. You do this by using the -R flag, like this:
patch -Rp0 < patchfile.patch

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).

From your working copy directory (widget1_working) execute the following command:
svn revertWhere <filename> is the name of the file you wish to revert. If you wish to revert all changes in your working copy, execute:
svn revert *

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, execute the following command from your working copy directory (widget1_working):
svn switch svn://svn.igorexchange.com/packages/widget1/branches/IGOR-5-05--1
If your working copy currently reflected what was in the trunk/ directory of your project, issuing the above command would switch your working copy to represent what is in the IGOR-5-05--1 branch of your project in the repository.

Troubleshooting

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

User-to-user support and collaboration