Overview ::

The basic idea is to provide a command-line tool that operates much like a source control utility. It provides check-in/check-out capabilities to retrieve the contents of a wiki to your local hard drive, where you can then edit them offline. Later you can upload them back to the wiki. FwSync will tell you which files have been edited on the wiki in the meantime to reduce the chance of you unintentionally overwriting changes that others have made.

Status

FwSync is now complete and checked in to the FwContrib workspace at version 0.7.

Versions

This is the documentation for version 0.7. Documentation for version 0.5 can be found in FwSync0dot5.

Authorship

FwSync was written by CraigAndera.

Compatibility

FwSync requires that the FlexWiki website it talks to be at least version 1515.

Installing FwSync

FwSync is not currently part of the FlexWiki release package, so you will need to obtain the binaries from the FwContrib workspace. Once you have downloaded it, simply copy fwsync.exe (and optionally fwsync.pdb) to some directory that is part of your PATH.

Using FwSync

FwSync is a command line tool. You can get complete help for FwSync by typing

  fwsync

at the command line. Here is the message you will receive:

 fwsync 0.7.1726.7750 Copyright (c) 2004 Craig Andera candera@develop.com


 Usage: fwsync <options> <command> <commandoptions>


 Options: 
   /debug          Cause the program to break into a debugger after launching
   /defcred        Use the credentials of the currently logged-in user (the 
                   DEFault CREDentials) to authenticate to the web service. 
                   This option may not be specified with the /user nor with 
                   the /password option. 
   /user <name>    Specifiy the user with which to authenticate to the web 
                   service. If no /password is provided, the user will be 
                   prompted to provide one. This option may not be specified
                   with the /defcred option. 
   /password <pwd> Specify the password with which to authenticat to the web
                   service. If this option is not specified when the /user 
                   option is provided, the user will be prompted to provide
                   a password. This option may not be specified with the 
                   /defcred option. 
   /url <url>      Specify a URL for the FlexWiki instance you're synchronizing
                   with. This parameter is optional on all commands except
                   init, as it will be stored in the configuration file. 


 Commands: ( { } denote optional parameters ) 
   init { <directory> } 
   update { <path> ... } 
   status { <path> ... } 
   commit /attribution <identity> { <path> ... } 


   <directory>     A directory somewhere on your local disk. Relative or 
                   absolute paths may be used. 
   <path> ...      A list of one or more files or directories separated by a 
                   space. Paths with spaces in them must be enclosed in 
                   double quotes. 
   <identity>      A name or email address.          


   init:           Initial setup of FwSync: Retrieves all topics from the 
                   server at <baseurl> and stores them in the new directory 
                   <directory>. If no directory is specified, the current 
                   directory is used. Requires the /url option - the specified
                   URL will be stored and remembered for use later by other
                   commands acting in the same directory. 
   update:         Retrieves any files that have been added or changed on 
                   the server, unless they have also been modified on the 
                   local machine. If no files or directories are specified,
                   all topics in the FlexWiki instance will be updated. 
   status:         Prints the status of all wiki files in specified directory.
                   See below for an explanation of statuses. If no files or
                   directories are specified, status for all topics in the 
                   FlexWiki instance will be printed. 
   commit:         Uploads all locally modified and added files to the web 
                   repository. If any files have a status (see below for a 
                   description of statuses) of 'InConflict', no commit will 
                   be performed - you must resolve all conflicts before 
                   performing a commit. If no files or directories are 
                   specified, all topics in the FlexWiki instance will be 
                   committed. 


   /attribution:   To whom changes will be attributed. This will show up on 
                   the web pages in the history dropdown. This parameter is 
                   ignored if an identity is specified with either the 
                   /defcred or /user switch. Note that this parameter is 
                   required (even if /defcred or /user is specified) when
                   running the commit command. 


 Status: 
   UpToDate          The file is identical with the latest revision in the 
                     repository.
   LocallyModified   You have edited the file, and not yet committed your 
                     changes
   LocallyAdded      You have added the file to the local file system and not 
                     yet committed your changes.
   NoLocalFile       The local file does not exist - it needs to be retrieved 
                     from the repository via the update command.
   LocallyOutOfDate  Someone else has committed a newer revision to the 
                     repository. You can retrieve the latest version with the 
                     update command.
   InConflict        Someone else has committed a newer revision to the 
                     repository since your last update, and you have also made
                     modifications to the file. You will not be able to commit 
                     while any file is InConflict. See below for instructions 
                     on how to deal with conflicts. 


 Dealing with conflicts: 


   At some point, this tool will provide help for dealing with conflicts. For 
   now, however, it is a manual process. Consider an example where the topic
   MyWiki.HomePage is in conflict. The steps are: 


   1. Rename the conflicting file to something like HomePage Test.wiki.conflict
   2. Perform an update command to retrieve the current version from the web
   3. Merge the two files using your favorite merge tool (e.g. WinMerge)
   4. Save the merged file back to HomePage Test.wiki
   5. Commit the modified file. 
   6. Delete the HomePage Test.wiki.conflict file.

Typical Usage Scenario

Let's assume you wanted to edit a wiki called FooWiki located on the web at http://www.foowiki.com. A typical usage scenario will go something like this:

1. Choose a new directory on your hard drive. The directory can have any name. We will assume the name of the directory is C:\data\FooWiki
2. Run fwsync /url http://www.foowiki.com init C:\data\FooWiki This will create the directory C:\data\FooWiki
3. Run cd C:\data\FooWiki to change to the directory that was just created.
4. Run fwsync update This will grab all the files from the server, creating one directory for each namespace on the server, and creating one file with a .wiki extension in those directories for each topic in the corresponding namespace.
5. (Optionally) Edit the .wiki files with your favorite text editor, using the same WikiFormatting you use to edit FlexWiki pages on the web. You do not need to be connected to the web for this step, and any amount of time can elapse between this step and the previous one.
6. (Optionally) Add any new .wiki files you like. You do not need to be connected to the web for this step, and any amount of time can elapse between this step and the previous ones.
7. (Optionally) Run fwsync status to see what has been modified on both the server and your local hard drive.
8. Run fwsync commit /attribution myUsername to push all the changed files up to the web server. The /attribution switch specifies to whom the changes will be attributed.
9. (Optionally) Run fwsync update to update the local filesystem with any files that have changed on the server.

How FwSync Works

FwSync works by maintaining a file called fwstatus.xml in the directory you specify when you run fwsync init (called the base directory). This file contains information about what fwsync thinks is on the server. It is updated whenever FwSync connects to the server (which currently happens every time you run fwsync). It keeps track of several pieces of information:

• The URL you specified at initialization time. This is so you don't have to remember to provide it every time you run FwSync.
• For each topic, the latest version stored on the server.
• For each topic, the version that was latest when we last downloaded that topic (called the based-on version)
• For each topic, a checksum value of the topic contents when we last downloaded that topic (called th based-on checksum).

FwSync then works by comparing the latest version stored on the server to the based-on version, and the current checksum (calculated from the file on the local disk) with the based-on checksum. Comparing these values lets FwSync know whether the server or the local file system has been modified. This is then used to calculate the status of that file as outlined in this table:

                                         Web                            
                     Unchanged         Modified       Doesn't exist 
                   -------------------------------------------------  
        Unch     |    UpToDate      LocallyOutOfDate  LocallyAdded 
 Local  Mod      | LocallyModified    InConflict      LocallyAdded 
        Not Exist|   NoLocalFile      NoLocalFile         N/A                  

Feature/Enhancement Suggestions

• Add authentication, including ability to pick up on logged in user's credentials for communication with sites using Integrated authentication (complete, tested, checked in, but documentation (this page) needs update)
• Change atribution argument of commit to be a switch rather than a positional argument. E.g. fwsync commit wiki /attributeto CraigAndera rather than fwsync commit CraigAndera wiki. The primary reason for this is that I can never remember which one goes first, and if you only put one it's not obvious if the one you put is the attribution or the directory. (complete, tested, checked in, but documentation (this page) needs update)
• Change init so it doesn't retrieve the topics. It should just store the URI in the fwstatus.xml file. The update command is there for the initial retrieval.
• Add the ability to update, commit, and get status for individual files or sets of files, rather than for just the whole tree. (complete, tested, checked in, but documentation (this page) needs update)
• Add an option to status command that doesn't connect to the web - a local-only status.
• Break core functionality out into separate assembly
• Once previous feature is done, write GUI front end for people that like that better
• Add a revert command for undoing changes on a file that was modified locally. Already possible by doing a delete and update, but might be handy.
• Look at performance - will decreasing chattiness by providing batch operations on the FlexWikiWebService make it faster?
• Remove the requirement to specify /attribution when authentication is used. Or just make it optional entirely.
• Change the checksum algorithm to compare based on decoded character sequences, rather than bytes in the file. Currently, two files that contain the same content except for a byte order mark (BOM) or that have different encodings will be considered different.
• Add in some sort of feedback so the user knows something is happening on long uploads.
• Add a verbose mode so the user can select how much feedback they get.
• Make /defcred the default if /user is not specified. -- TommyWilliams
• Add options to control the output when reporting status, either with the status command or after a commit or update. Typically, you might want to only show files whose status is not UpToDate -- TommyWilliams

Bug Reports

• There seems to be a problem when running a status command from within a subdirectory: seems like it ignores the URI stored in the fwstatus.xml file.
• Update this documentation to match the version in source control
• When a commit or status is run in a subdirectory without specifying a file, it should run as if that directory name was specified, not as if the parent directory was.
• FwSync seems to report InConflict files more often than it should. Have not yet been able to repro. Problem seems to have gone away.
• When using authentication on the web service, several network round trips are required for each operation, making performance way less than what it could be. This is a consequence of the completely broken implementation of web service security in .NET 1.1. Fixing this will require following the instructions at http://radio.weblogs.com/0106046/2002/10/24.html. Note that because of how busted the WS proxy stuff is, when using Integrated authentication, even when this fix is rolled in, you will still be performing three network roundtrips per web service request. There is no known fix for this. One workaround is to enable Basic security on the webserver as well, although obviously this provides only weak protection for passwords. Ultimately, the solution to this is probably use WSE 2.0, so blowing off the incredibly lame Microsoft proxies.
• FwSync is failing when attempting to run the following command: fwsync /url http://www.flexwiki.com init c:\mylocalflexwiki -- LukeLatimer
• I suspect this due to FlexWiki.com being upgraded to the WikiTalkExperimentalBuild?
• The stack trace and other error information is here: FWSyncErrors
• Confirmed - interim builds of FlexWiki broke the web service that FwSync uses. Recent builds have reportedly fixed the problem. I will verify this myself when I get the new bits installed somewhere. -- CraigAndera

Questions and Answers

The implementation I'm working on won't do a merge, however, it will refuse to commit files that are in conflict, allowing you to easily merge by renaming the conflicting file, updating to get the current web version, merging with an external tool, and committing the merged file. In the future, I plan to add a resolve command to automate this process, but right now my philosophy is to get it to the point where I can do the basics. -- CraigAndera

It will not work with the FlexWikiEditor in FlexWikiEditor's current state. This is because FlexWikiEditor is an inherently connected application, and FwSync is all about a disconnected model. My plan is to instead morph FlexWikiEditor into an application that only edits local .wiki files, and then use FwSync to get the connectivity to a web instance. This application is called FlexWikiPad, and is currently under development.

This approach has the additional benefit of yeilding an application that can be used to create wikis without ever connecting to the web. Handy if you just want to take notes.

Eventually, I will probably integrate the two somehow, so you can do all your checkins, updates, and conflict resolution from within the single UI. However, first things first. -- CraigAndera

Thanks! -- CraigAndera