Difference between revisions of "OnlineHelp:Contents"

From RapidSVN
Jump to navigation Jump to search
m (→‎Create a Tag / Branch: rearrangement to make structure more logical)
(DiffMerge setup for use as Merge Tool)
Line 38: Line 38:
 
|-
 
|-
 
| Diff    || [http://winmerge.sf.net WinMerge]    || [http://meld.sourceforge.net/ Meld] (to install Meld on ubuntu, apt-get install meld) || [http://sourcegear.com/diffmerge/downloads.html DiffMerge]<br>[http://developer.apple.com/documentation/Darwin/Reference/ManPages/man1/opendiff.1.html FileMerge (via opendiff)] NOTE: Requires Mac OS X Developer Tools
 
| Diff    || [http://winmerge.sf.net WinMerge]    || [http://meld.sourceforge.net/ Meld] (to install Meld on ubuntu, apt-get install meld) || [http://sourcegear.com/diffmerge/downloads.html DiffMerge]<br>[http://developer.apple.com/documentation/Darwin/Reference/ManPages/man1/opendiff.1.html FileMerge (via opendiff)] NOTE: Requires Mac OS X Developer Tools
 +
|-
 +
| Merge    || [http://sourcegear.com/diffmerge/downloads.html DiffMerge] || || [http://sourcegear.com/diffmerge/downloads.html DiffMerge]
 
|}
 
|}
  
 
=====DiffMerge Setup in Mac OS X=====
 
=====DiffMerge Setup in Mac OS X=====
 
After installing the application in the Applications folder, copy the shell script from the disk image to <code>/usr/bin/</code>.  Specify <code>/usr/bin/diffmerge.sh</code> in RapidSVN->Preferences->Programs->"Diff tool:".  For "Program arguments" use <code>"%2" "%1"</code>.  %2 is the original file and %1 is the modified file.  The quotes will properly encapsulate paths with spaces.
 
After installing the application in the Applications folder, copy the shell script from the disk image to <code>/usr/bin/</code>.  Specify <code>/usr/bin/diffmerge.sh</code> in RapidSVN->Preferences->Programs->"Diff tool:".  For "Program arguments" use <code>"%2" "%1"</code>.  %2 is the original file and %1 is the modified file.  The quotes will properly encapsulate paths with spaces.
 +
 +
===== DiffMerge Setup for Use as Merge Tool =====
 +
This is the commandline argument:
 +
/title1="Base" /title2="Mine" /title3="Theirs" /result="%4" "%1" "%3" "%2"
  
 
=== User Interface ===
 
=== User Interface ===

Revision as of 16:03, 14 March 2008

Introduction

As you can see, the user documentation for RapidSVN has just started. The first draft with the outline was created 2006-11-01 and it will grow in the weeks and months (and years!) to come.

Your help with the documentation is requested! If you want to proofread the texts or if you want to create whole sections of the documentation: just create an account and start working on the site.

In the past I had to disable the user account creation to the public after this was abused by wiki spammers who would come and insert invisible SPAM links in our pages (probably to get a better google pagerank). Hopefully this won't be that much of an issue anymore, since now a user has to verify her account.

Installation

Windows

  1. Download the installer package for windows operating system from here.
  2. Double click on it to start the installation process.
  3. Follow the steps that you see on the screen, you can leave the default options.
  4. You are done, now you need some SVN repository to start working!.

Mac OS/X

  1. Download the dmg package (RapidSVN-x.y.z.dmg) for Mac OS X operating system from here.
  2. Double click on dmg file to mount the disk image.
  3. Drag the RapidSVN.app file to your Applications folder.
  4. Go into the Application Folder and double click RapidSVN.app to start the program.
  5. You are done, now you need some SVN repository to start working!.

Linux/Unix

Setting preferences

  • Click on the menu item 'View/Preferences...' to set the preferences. Mac uses will find "Preferences..." under the RapidSVN menu.

Programs

The 'Programs' tab must be filled with the paths pointing to the programs that perform Edit, Explore and Diff functions.

The suggested programs are:

Function Windows Linux Mac OS/X
Editor Scintilla/SciTE
Programmer's Notepad
notepad.exe
Scintilla/SciTE
TextEdit
GVim
Explorer explorer.exe nautilus TODO: explorer for Mac OS/X
Diff WinMerge Meld (to install Meld on ubuntu, apt-get install meld) DiffMerge
FileMerge (via opendiff) NOTE: Requires Mac OS X Developer Tools
Merge DiffMerge DiffMerge
DiffMerge Setup in Mac OS X

After installing the application in the Applications folder, copy the shell script from the disk image to /usr/bin/. Specify /usr/bin/diffmerge.sh in RapidSVN->Preferences->Programs->"Diff tool:". For "Program arguments" use "%2" "%1". %2 is the original file and %1 is the modified file. The quotes will properly encapsulate paths with spaces.

DiffMerge Setup for Use as Merge Tool

This is the commandline argument:

/title1="Base" /title2="Mine" /title3="Theirs" /result="%4" "%1" "%3" "%2"

User Interface

Basic Concepts

Tutorial, Part 1

Note: This tutorial was written to assist a user getting started with RapidSVN. It was not written to assist an administrator starting from the beginning.

RapidSVN has the notion of a server (a repository) and a client (a working copy). Both repositories and working copies can be bookmarked. By creating a bookmark, the user has quick access to either the working copy or repository in RapidSVN. The first thing a user should do is bookmark a repository.

Browse an existing repository (via a bookmark):

  1. Under the Bookmarks menu select Add Existing Repository...
  2. Type the URL (e.g. http://TagentServer/svn/RFID) and click OK

After bookmarking a repository the user can browse (but not view or edit) all the files on the server.

Next a user may want to work with a file in the repository; this is done by checking out a working copy. But RapidSVN does not do checkout at the file level. Instead directories are checkout out. The user could checkout the entire repository from the Repository menu but often times this is undesirable due to time and space requirements to checkout a large repository. So instead the user can checkout the parent directory of the file to be worked on.

Edit a file (via Checkout) and Checkin the changes (via Commit):

  1. Using the repository bookmark created in the prior step, browse to the parent directory (or higher) that contains the file to be worked with.
  2. In the Bookmark browser, right-mouse click the desired parent directory and select Checkout New Working Copy... from the context menu.
  3. The URL will already be filled out (make sure it’s just the directory and doesn’t contain the filename (a bug), if you don’t remove the filename you’ll get an error).
  4. Enter your local path in the “Destination Directory” and click OK. This will populate your hard disk with the files and create a bookmark.
  5. Browse the bookmark in RapidSVN to the file to be edited and double-click the file.
  6. After editing and saving the file, reactivate the RapidSVN window. The status for the file should now indicate “modified”.
  7. In the right-hand window, right-mouse click on the modified file and select Commit...
  8. Enter a log message and click OK.

Undo a local edit (via Revert):

  1. Make another change to the file we worked with in the prior section and save it.
  2. Switch back to RapidSVN and in the right-hand window, right-mouse click on the modified file and select Revert.
  3. Click OK to the Revert dialog and observe the changes made in Step 1 have been lost.

Add a file (via Add)

If you have progressed this far then you have bookmarked a repository and a working copy. If a file is added to a directory that already has an existing “working copy bookmark,” the file will appear in the right-hand window with a status of "unversioned".

  1. In the right-hand window, right-mouse click on the file to be added and select Add.
  2. Right-mouse on the file in the prior step and select Commit....
  3. Enter a message in the log window and click OK.

Add a directory (via Add recursive)

  1. Create a new directory in the directory we have been working in.
  2. Add a file or two. You can even create a subdirectory with more files in it.
  3. Return to RapidSVN. In the right-hand window you will notice the new directory appears as "unversioned".
  4. Right-mouse on the new directory and select Add recursive.
  5. Right-mouse on the new directory again and select Commit....
  6. Enter a message in the log window and click OK.

The new directory and its contents have been added to the repository. Note: It is possible to add empty directories.

Add your project directory

Up to this point we have been working in an existing directory in the repository. One of the first things you will likely want to do is add your project directory. This can sometimes be tricky. For instance, you want to put your directory at the root of the repository but you don’t want to store the entire repository on your hard disk. There are a couple of ways to accomplish this:

Option 1: Add a directory via Import

  1. In the Bookmark browser, select the repository you want to add the directory to.
  2. From the Repository menu select Import....
  3. For the "Repository URL" make sure you specify the full path to the new directory. For example, if I wanted to add the Reader directory to the path //TagentServer/svn/RFID/ enter http://TagentServer/svn/RFID/Reader for the "Repository URL".
  4. Next enter your local path in the "Path" field. In this example we’ll use /Users/gerrior/Projects/RFID/Reader.
  5. Type something in the "Enter log message" field.
  6. Confirm "Recursive" and "Path type:" "Tree" are selected and click OK.

This will add your directory and all the files and directories in your project. Unfortunately doing an import doesn't checkout your files. Your files are in the repository but you can't start working with them. The directory on your drive remains untouched (it doesn't contain the hidden .svn directories). The next step is to checkout what you just imported.) (Entered enhancement request)

  1. Rename the directory you just imported (.e.g. \Reader to \Reader.orig). If you do not this you will receive the error "object of the same name already exists" when you perform the next step. Checkout does not allow you to overwrite existing files.
  2. In the Bookmark browser, right-mouse click the newly imported directory (e.g. \Reader) and select Checkout New Working Copy... from the context menu.
  3. The URL will already be filled out (make sure it's just the directory and doesn't contain the filename (a bug), if you don’t remove the filename you'll get an error).
  4. Enter your local path in the “Destination Directory” and click OK. This will populate your hard disk with the files and create a bookmark.

Option 2: Add a directory to the repository

  1. In the Bookmark browser, select the parent directory for the new directory. This can be the repository bookmark or a subdirectory.
  2. In the right-hand window, right-mouse in an empty row and select Make directory... F7.
  3. In the Bookmark browser select the new directory (you may need to refresh the view).
  4. Right-mouse and select Checkout New Working Copy... , specify the "Destination Directory" and click OK.
  5. Now you can add your files as we did previously. (You may need to select another bookmark and then select the new bookmark again in order for the files to appear. Refresh View doesn't work in this scenario. Bug 566)

Tutorial, Part 2

Checkout a Working Copy

If you are new to both Subversion and RapidSVN, probably the first thing you are trying to do is checkout a working copy of an existing repository.

  1. Click on the 'Repository' menu
  2. Click on the menu item 'Checkout.. (CTRL-O)', this will open the 'Checkout' dialog box
  3. Enter the URL of the Subversion repository in the 'URL Text box'
  4. Select a local directory for your sandbox (working copy)
  5. Click the 'OK' button

View an existing subversion sandbox (working copy) with RapidSVN

If you are new to RapidSVN, but have used Subversion, probably the first thing you want to do is view an existing Subversion sandbox with RapidSVN.

  1. Right click 'Bookmarks'
  2. Click 'Add Existing Working Copy'
  3. Browse for the root of the local copy
  4. Click the 'OK' button

Review your Changes

Update your Working Copy

Create a Tag / Branch

Branching and tagging are both achieved by using RapidSVN's Copy command (Modify > Copy, or press F5). Copy the directories and files you wish to branch / tag into a subdirectory of your relevant branch or tag folder.

Tip: it's easier if you add a bookmark for your repository (Booksmarks->Add Existing Repository...) and perform your operations in there. You can use relative destinations when moving/copying in there. For example you might select "trunk" and then Modify->Copy. Enter "tags/my first tag" as destination. Note that the resultant file structure would not then be tags/my first tag/trunk, even though you are copying the trunk folder -- so you needn't worry about copying the files individually, just copy the folder and the result will be as you'd hope.

Note: if you would like to create a tag from your (local) working copy you will need to type the full address (i.e. starting with svn://) into the "Select Destination:" box.

Merging

Merging is combining the contents of one branch with another, or combining one branch with your trunk (main) version. This is accomplished via the Repository > Merge... option. An important thing to know about merging is that you merge the versions on your local machine, not on the remote repository.

In brief, the steps are as follows. Assumming you want to merge branch1 and branch2,

  1. Update your local copy of branch1 from the repository
  2. Update your local copy of branch2 from the repository
  3. Select Merge... from the Repository menu
  4. In the "First working copy or URL", enter the local address of branch1
  5. In the "Second working copy or URL", enter the local address of branch2
  6. Enter revisions in the two "Revision" boxes (see below).
  7. In "Destination path", enter the local address of the folder you'd like your merge to be created in
  8. Click OK
  9. Select the lkocation where your merge has been placed and Commit it to the remote repository (use Ctrl-M, the toolbar icon, or Modify > Commit).

If you are merging a branch with a trunk (main) version, you may wish to have "Second working copy or URL" and "Destination path" both be the path to your main version.

"Revision" cannot be left blank. You are also unable to type "head". If you wish to use your head (latest) version, you will need to type in its number. This can be discovered by selecting your remote repository in Bookmarks (you can't do this while the Merge dialog is open) and selecting "Log..." from the "Query" menu. Use the Revision number from the latest entry in the log (top of the list).

Advanced Tutorial

Export from the Repository

Exporting from a repository allows you to copy the contents of a repository without the SubVersion (SVN) information. Essentially, it gives you a clean version of the files.

To export from a repository:

  1. Click on Repository and choose Export...
  2. In the "URL" box, type the URL of the repository you wish to export. You don't have to export the whole respository, you can export individual files or directories if you wish.
  3. In The "Destination Directory", type the path to the location you wish to export to.
  4. Click OK

Create a new Repository

As of version 0.9.4, a repository can only created with the command svnadmin. At the command line type svnadmin create /path/to/repository

For more information about repository administration, refer to the Repository Administration chapter of the Version Control with Subversion book.

Tips

  • If you have a lot of files to check in and they are spread across multiple directories, select Flat Mode from the View menu. When a directory is selected in the Bookmark browser its contents and all its subdirectories contents will be shown in the right-hand browser.

Troubleshooting

Getting support

A good place to ask questions about RapidSVN is the users' mailinglist at mailto:users@rapidsvn.tigris.org.

The mailinglist central is at http://rapidsvn.tigris.org/servlets/ProjectMailingListList. You can use this page to search for messages that may address your problem.

The RapidSVN project uses an issue tracker to manage bugs/defects or feature requests. The URL for the issue tracker is http://rapidsvn.tigris.org/servlets/ProjectIssues. Please ask your questions / report your problem first on the mailinglist to keep duplicate entries in the issue tracker at a minimum.

I've sized a file list heading to zero and can no longer see it

(all)

You can also reset all columns to their default widths and selections from the View->Columns->Reset Columns menu pick.

(Windows)

  1. Quit RapidSVN
  2. Run regedit
  3. Navigate to HKEY_CURRENT_USER\Software\RapidSVN\RapidSVN\FileListCtrl
  4. Find parameter names that end in width with their values set to 0
  5. Set the parameter value to something like 50.
  6. Run RapidSVN

Appendix

Glossary

Index