TortoiseSVN - Ece

TortoiseSVN

From Ece

Jump to: navigation, search

TortoiseSVN is a Windows Subversion client with a GUI interface integrated into the Windows shell. Icon overlays show the status of files in Windows Explorer, and all commands are available through the context menu ("right-click" menu). TortoiseSVN also comes with a program called TortoiseMerge for side-by-side diff-ing.

Contents

Acquiring TortoiseSVN 

It was previously recommended that you avoid TortoiseSVN 1.5, but it may
safe to use now.  Click the discussion tab for more information.

To get TortoiseSVN 1.5:

  1. Proceed to the TortoiseSVN download page.
  2. Download the appropriate installer (as of this writing, the current 32-bit installer is TortoiseSVN-1.5.6.14908-win32-svn-1.5.5.msi).

To get the older TortoiseSVN 1.4:

  1. Proceed to the TortoiseSVN download page.
  2. Scroll down the page to the Older Releases heading.
  3. There should be a link to Sourceforge files. If not then try this link.
  4. On the Sourceforge page, scroll to the File Releases section. Within that section, there is a table of links to releases. Find the Application section of this table (it should be the first section).
  5. In the Application section of the File Releases table, click the View older releases from the Application package link.
  6. In the table on the resulting page, expand the 1.4.8 entry.
  7. Click the TortoiseSVN-1.4.8.12137-win32-svn-1.4.6.msi entry to download.

This is the recommended way to download TortoiseSVN 1.4. If for some reason the method is unsuccessful, then try the direct link, which is not guaranteed to remain up-to-date.

Basic Tasks

In TortoiseSVN, all operations are accessed from context menus—that is, the menu opened by a right-click of the mouse. Right-clicking on or within a non-working-copy will show a context menu that includes SVN Checkout and TortoiseSVN entries. Right-clicking on or within a working copy (on any file, directory, or sub-directory) will produce a context menu that includes the entries SVN Update, SVN Commit, and TortoiseSVN.

Thus, all instructions involving these context menus will be specified in the following form:

  • Right-click for a context menu, and choose checkout: SVN Checkout.
  • Right-click for a context menu, and choose update: SVN Update.
  • Right-click for a context menu, and choose commit: SVN Commit.
  • Right-click for a context menu, hover on TortoiseSVN until a further menu pops out, and then choose some command, such as Show log: TortoiseSVN→Show log.

Connecting to a Repository

For a full explanation of repository URLs and connection specifics, see Connecting to a Subversion Repository.

Getting Help

You can get direct access to help via TortoiseSVN→Help or visit the TortoiseSVN website to access the same documentation as HTML or PDF.

Browsing a Repository

To look at the contents of a repository without checking out a copy, use the repository browser. In any folder in Windows Explorer, execute TortoiseSVN→Repo-browser. You will be prompted for a repository URL.

You can use the Repository Browser to directly work on the repository, to some extent, including dragging in files, but this is highly discouraged, as all changes are automatically committed. Unless you really know what you're doing, it is advised to use the repository browser for browsing only.

Importing an Existing File Tree

If you have an existing file tree, you might want to directly add the entire tree into a repository. You can perform a direct import rather than a checking out the repository, adding the files, and then committing. Importing does all of this for you.

  1. Make sure your tree contains only the files you want to place under version control. You might even want to make a copy of your tree, and then "prune" it down. For example, temporary files, object files, compiled executables, etc. should generally be left out of the repository, since it is the source code that needs to be versioned.
  2. Execute TortoiseSVN→Import on the top-level directory of your tree.
  3. You will be prompted for a repository URL. If your repository has or will have multiple projects, or you are using a branches/tags/trunk structure, or for any other appropriate reason, you should probably specify a subdirectory in your repository, rather than import into the repository root.

Note that this will not give you a working copy. You must subsequently checkout the repository to have a working copy.

Checking out a Working Copy

Use the SVN Checkout context-menu command to perform a checkout. You will be prompted for:

  • URL of repository. You should generally use a somewhat restrictive path within the repository, especially when using a trunk/tags/branches setup. For instance, if you want the trunk, don't check out the root, because you will have to download all of the branches and tags as well.
  • Checkout directory. TortoiseSVN will use the path in which you invoked SVN Checkout and will suggest a directory name based on the URL.
  • Checkout depth. Use this to limit the file-tree depth that gets checked out and downloaded to your machine.
  • Revision. You will usually want to checkout the HEAD revision, but you have the option to specify some other revision.

You may be prompted for authentication information, depending on your connection and setup type.

Making Local Changes

Editing Files

Once you have a working copy, you can simply edit the contents of files with your favorite editor.

Creating, Adding, and Deleting Files

When you create a new file or folder or add a file/folder to the working copy, you will need to use TortoiseSVN→Add to bring the file under version control. The next time you commit, that file will be added to the repository.

Likewise, you can delete a file from the working copy with TortoiseSVN→Delete. On the next commit, this file will no longer exist in the HEAD revision, but will still exist in previous revisions.

Moving, Renaming, and Copying Files

In order to correctly maintain revision history, all moves/renames and copies of files must be performed with the right-click-and-drag menu. For example, to copy a file:

  1. Select the file with the mouse.
  2. Right-click, but do not release, the mouse on the filename.
  3. Drag the mouse until a plus (+) sign appears next to the mouse cursor, and release.
  4. Choose SVN Copy versioned files here or SVN Copy and rename versioned file here.

The same basic procedure is used to move/rename files, including to and from other folders in the working copy.

Examining Local Changes

TortoiseSVN automatically indicates the status files using icon overlays in the Windows shell.

For a more verbose listing of the working copy status, execute TortoiseSVN→Check for modifications on a file or directory (usually the working copy directory itself, in order to see all changes).

To see the local changes within a file, execute TortoiseSVN→Diff on a modified file. This will launch TortoiseMerge, which shows a side-by-side view of your working base and working copy versions of the file. Differences are noted with plus (+) and minus (-) signs.

You can also compare the file with its previous versioned state (the most recent revision in which the file was changed) using TortoiseSVN→Diff with previous version.

Reverting Local Changes

You can revert modifications to your local copy with TortoiseSVN→Revert. The changes presented for reverting will depend on which file/folder you execute the Revert command on. Use the top-level folder of your working copy to see all changes.

Updating the Working Copy

You will need to update your working copy before committing if anyone else has made a commit since your last checkout/update/commit. Read about updating first for more information about why and when updates are performed.

With TortoiseSVN, use SVN Update to update the working copy.

Resolving Conflicting Changes

Sometimes when you perform an update, you will receive changes that overlap with your own local edits, and you will need to resolve the conflict. First, read about resolving conflicts to understand what happens when a conflict takes place, including what files are created.

You have a few options for resolving the conflict:

  • Hand-edit the merged file with conflict markers in it.
  • Use TortoiseMerge by executing TortoiseSVN→Edit conflicts, which will launch a three-way view. This is a rich tool that you should experiment with (hint: use right-click). Make your edits in the bottom pane, and then choose save. If you want to try your edits again after saving, don't worry—TortoiseMerge actually reads its data from the temporary files, but writes to the actual/conflicted file.
  • Revert the file and abandon the changes using TortoiseSVN→Revert.
  • Replace the file with one of the temporary files. Do not use the TortoiseSVN commands for this. Just delete the conflicted file using the normal Windows facilities, and rename one of the temporary files (delete the extra extension).

When you have the file in the state you like, execute TortoiseSVN→Resolved on it to indicate that you have resolved the conflict. Only then will you be allowed to perform a commit.

Committing Local Changes

Use SVN Commit to commit your changes. You can choose which changes to commit, but usually you will want to commit all changes.

It is advisable to include a useful, descriptive log message every time you commit.

Reviewing Commit Logs

You can view a log of all relevant commits to the repository. Relevant means that you will not see revisions outside of your working copy's history.

To see a general history, execute TortoiseSVN→Show log on your working copy's top-level folder. You will see a list of revisions and corresponding log messages. Selecting an entry will reveal what modifications were made in that revision.

You can also execute the command directly on a file to see just the history for that file.

Getting Line-By-Line Author and Revision

TortoiseSVN provides a powerful tool called TortoiseBlame that can show, line-by-line, what author is responsible for adding or most recently editing the line, and in what revision that line was added or edited.

To view the "blame" for a file, execute TortoiseSVN→Blame on that file.

Undoing Committed Changes

Reverting a Revision's Changes

There is no actual "undo" function is Subversion. The best you can do is to cause the HEAD revision to have a change reversed.

  1. Execute TortoiseSVN→Show log in your working copy.
  2. Find the revision that contains the undesired change.
  3. Right click on that revision, and select Revert changes from this revision.

Note: this will undo all changes that occurred in the selected revision, and will only affect your working copy. You must review the changes and then commit before it takes effect in the repository.

Resurrecting or Reverting Changes to a Single File

If a single revision contains many changes, and you just want to undo one of those changes:

  1. Execute TortoiseSVN→Show log in your working copy.
  2. Find the revision that contains the undesired change.
  3. Look in the bottom pane that shows the individual files that were changed.
  4. Right-click on the file whose changes you want to revert, and select Revert changes from this revision.

If the file was modified in that revision, this will undo those modifications. If the file was deleted in that revision, then this will "resurrect" that file.

Reverting to a Revision

To revert your entire working copy to a previous revision, repeat the previous procedure, but select Revert to this revision. The changes are applied to your working copy.

Warning: this is a major action. Use it sparingly, and be sure you understand the implications.

Keyword Substitution

Subversion can automatically update author, revision, and modification date information for your files, using keyword substitution. Once you have inserted keywords into your file, you can activate the relevant properties using TortoiseSVN as follows:

  1. Execute TortoiseSVN→Properties on a file, folder, or a multi-selection (using the Shift key).
  2. Click the New... button.
  3. Enter svn:keywords as the property name, and for the property value, enter the properties you want to activate separated by spaces. For example, Author Revision Date.
  4. If you selected a folder, the Apply property recursively checkbox is useful for setting the properties on a whole tree.

You can use the same interface to later edit and remove your properties.

Branching and Tagging

Note: It is recommended that you first read about Subversion Branches and Tags. This section just covers the mechanics of branching and tagging in TortoiseSVN.

Creating a Branch or Tag

Before creating a branch or tag, it is recommended that you have no local edits waiting to be committed. Update your working copy to the newest revision as well.

To create a branch or tag, select the top-level folder of the tree you want to branch (usually the trunk or a lower subdirectory), and execute TortoiseSVN→Branch/tag....

You will then be asked for a destination URL. Specify the path to your branches or tags directory, and add a name for the tag or branch. For example, if using a typical repository structure, and you want to add a branch mytestbranch to project foobar, you would supply a URL similar to: 

svn+ssh://user@svn.ece.msstate.edu/path/to/repos/branches/mytestbranch

As another example, if you want to tag version 1.0.0 of your code, you might use: 

svn+ssh://user@svn.ece.msstate.edu/path/to/repos/tags/1.0.0

If you want your working copy automatically switched to the branch you create, be sure to check the Switch working copy to new branch/tag checkbox.

Switching Between Branches

To switch your working copy from the trunk or a branch to some other branch (or back to trunk), execute TortoiseSVN→Switch, and supply the URL that you would like to switch your working copy to.

Using switch is equivalent to deleting a working copy, and checking out a new URL into the same copy, except that switch downloads only the necessary changes to switch the copy, rather than doing a full checkout.

Merging

Note: It is recommended that you start by reading about branching, tagging, and merging. This section documents the equivalent operations in TortoiseSVN.

Also note: TortoiseSVN 1.5 includes an option to Reintegrate a branch. Do not attempt to use this option, as it is not supported by Subversion 1.4, which is what runs on Yavin.

Merging a Short-Lived Branch into the Trunk

Make sure all local edits have been committed to the branch.

  1. Check the commit log with Stop on copy/rename checked to find the revision at which the branch was created.
  2. Switch your working copy to the HEAD revision of the trunk (or the appropriate subdirectory of the trunk).
  3. Execute TortoiseSVN→Merge in your working copy.
  4. Select the Merge a range of revisions option, and click Next.
  5. Set the URL to that of the branch.
  6. Enter the revision range. For example, if you found that your branch was created a revision 22, you would likely just use 22-HEAD here.
  7. Click Next.
  8. You can either use the Test merge button to test or just click Merge.

Inspect the results of your merge. You may have to resolve a merge conflict. Once everything is in working order, use SVN Commit to apply the merge to the repository.

Synchronizing a Branch with the Trunk

To synchronize trunk changes into a branch:

  1. Check out the branch, and use the commit log with stop on copy/rename checked to find the revision at which the branch was created. For example, let's assume this is revision 73.
  2. Use the commit log on a trunk working copy to find the most recent revision at which it was changed (or use the repo-browser and note the revision number next to the trunk directory). Let's assume this is revision 88.
  3. Use a similar procedure to the above to merge the range of revisions 73-88 of the trunk into the branch:
    1. Execute TortoiseSVN→Merge in your working copy of the branch.
    2. Select the Merge a range of revisions option and click Next.
    3. Set the URL to that of the trunk.
    4. Enter the revision range. In this case, it would be 73-88.
    5. Click Next, then either test the merge, or just click Merge.
  4. Examine the local changes, resolve any merge conflicts, and then commit with a useful message, such as Merged trunk changes r73:88 into branch reallycoolfeature

Subversion 1.4 does not support automatic merge tracking, so to synchronize again, you will have to use your log messages to find out when you last synchronized.

  1. Use the commit log to find the message that mentions your merge of r73:88 of the trunk into your branch.
  2. Use the commit log or repo-browser to find the revision at which the trunk was last changed. Let's assume revision 99.
  3. Repeat the steps from above to merge 88-99 of the trunk into the branch.

Porting a Single Change into a Branch

As an example, assume a change occurred on the trunk at revision 125, and you want to port only that change into a stable branch 1.0.x.

  1. Checkout or switch your working copy to the branch.
  2. Execute TortoiseSVN→Merge in your working copy, and select the Merge a range of revisions option, and click Next.
  3. Specify the URL of the trunk, and the two consecutive revisions of the change. In this case, the change occurred in revision 125, so enter 124-125.
  4. Inspect the merge results, and commit with a useful message, such as Merged trunk change c125 to branch 1.0.x.

Merging a Synchronized Branch into the Trunk

For the case when a branch has been synchronized with the trunk, such that the two are identical except for the branch changes, we can compare the two trees to merge the branch into the trunk.

  1. Use the commit log with Stop on copy/rename checked on the branch to determine when it was created. Let's assume revision 150.
  2. Note the (current or almost current) revision at which trunk and branch are in-sync and ready for the branch to be merged. Let's assume this is revision 170.
  3. Checkout or switch your working copy to the trunk.
  4. Execute TortoiseSVN→Merge.
  5. Select the Merge two different trees option and click Next.
  6. Set the From URL to the trunk.
  7. Set the To URL to the branch.
  8. Enter the in-sync revision (170) for both trees.
  9. Click Next, then Merge.
  10. Inspect the merge, resolve any conflicts, and then commit with a useful log message such as Merged (synchronized) branch changes r150:170 from mytestbranch into the trunk.

See Also

External Links

Retrieved from "http://www.ece.msstate.edu/wiki/index.php/TortoiseSVN"