This project is read-only.

subfox32.png SubFox User's Guide

Seamless integration for Subversion source code control

38236

This documentation is intended for FoxPro developers who wish to use SubFox as it was intended -- not for those interested in modifying or participating in the SubFox project (that is the SubFox Design Documentation).

Installation

To start using SubFox (i.e as a user -- no source code) here are the steps:
  1. Download and install SVNCOM from PushOk. You will need to choose the latest "SDK installation" (either the 32 bit or 64 bit version). The 64 bit version puts the files into the "Program Files(x86) folder regardless of where you ask to put it, so then you must manually copy the "PushOk" folder into the "Program Files" folder as well (bug to be fixed).
  2. Download and install TortoiseSVN. SubFox is designed to fulfill day-to-day requirements. You will need Tortoise to cover the remaining occasional tasks.
  3. Download the SubFox.exe into any folder you like. I prefer the VFP home path but the Windows or System folders work fine, or you can create a folder in the Program Files area.
  4. If you have a licensed copy of Stonfield Database Toolkit and would like to make it available to SubFox (required for database versioning) create a Windows Registry key for HKEY_LOCAL_MACHINE\Software\SubFox, and within it create a string value named SDT. Set that string value to the full path where the SDT.APP file is installed.

Setting up a SubFox Project

  1. Find out the URL of your Subversion server. This might mean you need to install VisualSVN for you to test with, or you might want to join an existing project and you simply need your administrator to tell you the web-URL, user-ID and password to work with.
  2. Find out the sub-URL of your project on that server. If you decide to create your own for testing, please take the advice to build the standard sub-folders branches, tags and trunk which will payoff down the road. Typically the final combined URL looks like https://MyDomain.com:8443/svn/MyProject/trunk.
  3. Create a folder for your project and link it to the Subversion server using the Tortoise command SVN Checkout (in Windows Explorer, right click on your folder). Beware that Subversion does something slightly unpredictable when you download into a folder with files in it that match files coming down from the repository -- it leaves them unchanged but flags them as modified. If you want Subversion to replace these files with the version in the repository (what you would expect when downloading a complete project) you will have to wait until the download is complete, then execute a revert on those files!
  4. Start Visual FoxPro and load the SubFox menu of features with the command DO SubFox.exe. You may need to include the path to the program such as DO (home()+"SubFox.exe"). To automate this step, go to the Tools->Options->File Locations->Startup Program and register the SubFox.exe to run here.
  5. Open the VFP project file:
    1. For projects yet to be uploaded to Subversion -- create your VFP project as you normally would (or already have). Walk through the list of files and make sure that all files are located within the sub-tree of the project's home directory, and that the project file itself is directly in the project's home directory.
    2. For projects just downloaded from Subversion -- close all open projects, then go to File->SubFox->Translate Source Files. Answer YES when prompted to open a project. Set Files of type to SubFox Project (the default setting). Navigate to your project folder and select the project file that was downloaded from the Subversion repository (it should have the format MyProject.pjx.subfox). SubFox will create a new VFP project and load into it all of the files downloaded by Subversion. You should be able to click cancel on the translator window that pops up since SubFox will automatically decode all of the source files during the project bootstrap. However, the window will appear just the same.
  6. Go to File->SubFox->Setup Versioned Files. If your project contains external files -- files marked as excluded -- that you want to include in the Subversion repository, the setup editor will let you choose which of these excluded files to include in the Subversion project. It also allows for identification of which database containers (DBCs) are to be tracked, and which tables -- both free tables and contained tables -- are to be treated like source code.
  7. If this project is being moved to Subversion for the first time, go to File->SubFox->Upload to Repository. Here you will have the chance to pick-and-choose which files to include in the upload and assign a message to label the reason for the upload -- preferably something like "Initial Upload".

Day to Day Usage

SubFox is designed to automate the regular tasks of using Subversion, but what are those tasks and how is it supposed to work? The normal cycle looks something like this:
  1. Download the latest version before starting work.
  2. If there are any conflicts (normally there won't be any):
    1. Resolve them immediately and
    2. Upload those changes right away.
  3. Work upon the project -- design, code, test, debug, etc.
  4. Occasionally use the Download function to pickup new versions that may have emerged while you were working. If any conflicts occur, try to resolve them sooner rather than later.
  5. When you have a block of changes that are ready to capture:
    1. Download the very latest changes already submitted by other developers (you cannot upload unless your local working-copy is fully up to date).
    2. Resolve any conflicts that may have resulted (you cannot upload files that are conflicted).
    3. Upload your changes as a block.
  6. At the end of the day, it is generally a good practice to upload your changes as a precaution against hardware failure, theft, fire, etc. It is not, however, recommended that you upload changes that might potentially interfere with other developers by breaking otherwise working parts of the application.

Resolving Conflicts

Sometimes when you download from the repository you will encounter a conflict. This is because both you and another user have edited the same line (or block) of code at the same time, effectively stepping on each others coding. In a well coordinated shop this simply shouldn't happen, but in a world-wide collaboration like an open-source project, this is rather typical. When this happens, you must use a conflict resolution editor (included with Tortoise) to merge together your changes and the changes made by the other developer(s) that you're in conflict with.

If this seems like a tug-of-war, it's really not. The other developer beat you to the punch, and saved his/her changes without any trouble. In fact, there might have been several people that came and went, changing it over and over again. So far as the rest of the world is concerned, it is only you that is a trouble-maker, since you are trying to submit changes to a dinosaur block of code that is no longer part of the project. That is what makes it your problem to figure out how these separate sets of changes can be incorporated into the final program.

Conflicts get resolved in basically three ways:
  • You can simply revert your version, effectively discarding all of your changes and accepting those produced by other developers.
  • You can go with the all-or-nothing approach, choosing to discard all of your own changes or discard all of everyone elses changes. If this sounds callus, it's not always so. This is precisely what you should do with changes to bitmaps and icons. Even in the case of source code, typically you compare the versions side-by-side and choose take mine or take theirs for a block of code because usually the change will be the same, or nearly the same. This happens a lot when separate developers both discover the same bug and each fix it sightly differently -- perhaps by putting a comment next to the change.
  • You can rewrite the whole block of code so that the essence of all changes are incorporated into the final result. This is the most time-consuming method, and the one that is most likely to lead to new bugs, more testing, etc. However, when completely unrelated changes take the same section of code in two different directions, there really is no other choice. Often times this type of change is done collaboratively with the other developer(s) involved.

Last edited Jan 21, 2010 at 2:22 PM by DavidHolden, version 23

Comments

petercompany Mar 28, 2014 at 10:29 PM 
this plugin works with viausl foxpro 7.0? wait for any response thank's.. regards

hoffi42 Sep 25, 2012 at 6:56 PM 
Another note for 64 bit Win7 and SVNCOM. We ended up going with the 32 bit version 1.6.17.0. The 64 bit versions just wouldnt work. Error messages that the class wasnt registered and I couldn't register it for the life of me. The 32 bit version works just fine. No moving from one folder to the other necessary here either. Just works. =) Thanks.

hoffi42 Sep 25, 2012 at 5:56 PM 
FYI: latest version of SVNCOM 1.7.0.rc1 for 64 bit now installs properly. No need to copy over to the correct folder manually anymore.

DHughes Dec 15, 2010 at 12:33 AM 
As far as I can tell I've set things up according to instructions. I admit that I had 32 bit versions of SVNComm and TortoiseSVN and had to uninstall/reinstall to get Tortoise working. While in FoxPro the command subfox->upload to respository will return a window with a program error "Function argument value, type, or count is invalid"
I'm using FoxPro 8, what call would it be making? Also ->install tortoise hooks returns a screen and message "cannot access the selected table." Appears to be an install issue but I don't see any reference to these types of problems. Anyone?

Julos Sep 15, 2010 at 11:03 AM 
I've some mistakes using SubFox :
- Since I've installed SubFox into VFP9, I've a "syntaxe error" the first time I launch VFP9 compile my project but nothing after...
- I can't use the conflict resolution editor of TortoiseSVN through SubFox... It doesn't start...
Any suggestion ?

kainhart Feb 24, 2010 at 5:42 PM 
A specific version of the SVNCOM depencency should be cited in the requirements for each release otherwise it may be difficult to track down errors that people get due to using an incompatible version.

kainhart Feb 24, 2010 at 1:48 PM 
I've noticed a Beyond Compare check box in the conflict resolution screen however this application isn't mentioned during installation or in the user guide. BTW, I use the P4Merge tool lately from Perforce and it's pretty nice although it doesn't seem to have the Binary file converter plugin capabilities that Beyond Compare has.