How do I get started with the Veracity Tortoise Client?
__Introduction__
Tortoise clients are a popular GUI interface for version control on windows. Many people like having the ability to manipulate their version control programs from inside the Windows Explorer interface. The Veracity Tortoise client is a little different from other Tortoise clients, so this document will guide users through the transition.
__The context menu__
The initial point of interaction for most operations is the Windows Explorer context menu. Outside a Veracity working copy, the context menu will look like this:
![Context Menu outside of a working copy][1]
__The Create Dialog__
![The Create Dialog][2]
The first dialog most people will use is the Create Working Copy dialog. The operations that you can do while creating a new working copy with this dialog are:
* Create a new repository.
* Clone a remote repository.
* You may also simply checkout a an existing local repository.
To create a new repository or clone a repository, choose "<New Repository>" `<New Repository>` from the Repository dropdown. If a repository is being cloned, or an existing local repository is being checked out, the Checkout Revision section will allow you to choose which revision or branch to use when setting up the working copy. For this document, I'll just create a new, empty repository.
__Working inside explorer__
Now that there is a Veracity Working Copy, the context menu has changed.
![Context menu inside a working copy][3]
Note that all operations are available from the context menu, regardless of the working folder contents. Operations are only removed from the context menu based on the number of items currently selected (for example, you can't simultaneously rename multiple files).
For the purpose of this tutorial, we'll create two new files. Right-click one of the files and choose Add. The Add dialog will look like this:
![The Add dialog][4]
In the Add dialog, click Ok with only one of the files selected (this will make sense in a minute, promise).
__The Commit Dialog__
Now to commit our first changeset. From the Windows Explorer context menu, choose Veracity Commit.
![The Commit Dialog][5]
Since this is a new working folder and repository, you will need to set a user before you can commit. Click the "set current user link" to bring up the settings dialog. Enter your username, and click OK in the settings dialog. You will be prompted to create the user.
![Creating the user][6]
Now, back in the Commit dialog, you will notice that one file is Added, and one file is still Found. Let's fix that, by right-clicking the Found file, and Choose Add from the context menu. I told you that it would make sense. The context menu for the commit dialog has lots of useful operations, such as reverting changes, deleting Found files or diffing modified files.
![Add from the commit dialog's context menu][7]
While you're in the commit dialog, take a look at the Branch tab. That's where you can choose to associate this changeset with a particular branch, or commit it without a branch. The default branch is master, and that's ok.
Now commit your two added files. Don't forget to enter a change set comment.
__Back to Windows Explorer__
Returning to Windows Explorer, you should see this:
![Normal file overlays][8]
Your files should be a pretty green color. If you ever feel like the icons haven't refreshed properly in Explorer, you can use the F5 key in Windows Explorer to refresh the icons.
Here's the list of icons that you can expect to see in Veracity's Tortoise client, and how they map to Veracity's working copy status.
* ![Normal][9] The file or folder is identical to the previous version in Veracity.
* ![Added][10] The file or folder has a been added to Veracity, but the add operation has not yet been committed.
* ![Modified][11] The file or folder has been modified, moved, or renamed.
* ![Conflict][12] The file or folder has a merge conflict that must be manually resolved. Use the context menu in the Commit dialog or the Status dialog to begin resolving conflicts.
* ![Found][13] The file or folder is not known by Veracity.
* ![Ignored][14] The file or folder is in the list of Veracity ignores.
__Sharing Changesets__
Sharing is important. Let's make sure that other people get access to our new changeset. Start up the Web Server dialog from the Windows Explorer context menu.
![Web Server][15]
Because we want to share our new repository with someone else, we'll have to Stop the server that was automatically started. Now make sure that the "Only accept connections from this computer" is unchecked, and use the Start button to restart the web server.
Now another person is free to clone from your machine using the URL http://YOURMACHINE/repos/YOURREPONAME. They can use the same Create Working Copy dialog as you used above. Once the repository exists on two different computers, you can use the Sync Dialog to transfer changesets between the computers.
__The Sync Dialog__
When you wish to transfer changes from one computer to another, you use the Synchronize dialog. The other computer must have the Web server running in order to participate the pushing or pulling of changesets.
![The Sync dialog][16]
Some things to note about the Synchronize dialog are that the Operation dropdown lets you choose to Push or Pull changes. Also, the Areas text box lets you choose to synchronize only some components (pushing work item changes without including version control changes, perhaps).
Now you've gotten the basics under control.
[1]: /qa/upfiles/1.Outside_A_Working_Copy.jpg
[2]: /qa/upfiles/2.Create_Dialog.jpg
[3]: /qa/upfiles/3.Inside_A_Working_Copy.jpg
[4]: /qa/upfiles/4.The_Add_Dialog.jpg
[5]: /qa/upfiles/5.The_Commit_Dialog.jpg
[6]: /qa/upfiles/6.Creating_A_User.jpg
[7]: /qa/upfiles/7.Add_Context_Menu.jpg
[8]: /qa/upfiles/8.Normal_Files.jpg
[9]: /qa/upfiles/NormalIcon.png
[10]: /qa/upfiles/AddedIcon.png
[11]: /qa/upfiles/ModifiedIcon.png
[12]: /qa/upfiles/ConflictIcon.png
[13]: /qa/upfiles/UnversionedIcon.png
[14]: /qa/upfiles/IgnoredIcon.png
[15]: /qa/upfiles/9.Web_Server_Dialog.jpg
[16]: /qa/upfiles/10.Sync_Dialog.jpg
