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 source control, although not yet included in the release.

Authorship

FwSync was written by CraigAndera.

Installing FwSync

FwSync is not currently part of the FlexWiki release package, so you will need to obtain the source code from the GotDotNet workspace and build the tool yourself. Once you have built 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 version 0.1
 Copyright (c) 2004 Craig Andera http://staff.develop.com/candera
 No arguments were supplied  


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


 Options:
   /debug


 Commands: ( { } denote optional parameters )
   init <baseurl> { <directory> }
   update { <directory> }
   status { <directory> }
   commit <identity> { <directory> } 


   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.
   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 directory is specified, the current
                   directory is used.
   status:         Prints the status of all wiki files in specified directory.
                   See below for an explanation of statuses. If no directory
                   is specified, the current directory is used.
   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.


 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 My 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 My HomePage Test.wiki
 5. Commit the modified file.
 6. Delete the My 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 init http://www.foowiki.com C:\data\FooWiki This will create the directory C:\data\FooWiki and 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.
3. (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.
4. (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.
5. (Optionally) Run fwsync status C:\data\FooWiki to see what has been modified on both the server and your local hard drive.
6. Run fwsync commit myUsername C:\data\FooWiki to push all the changed files up to the web server.
7. (Optionally) Run fwsync update C:\data\FooWiki 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.

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.

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 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, up

dates, and conflict resolution from within the single UI. However, first things first. -- CraigAndera

Thanks! -- CraigAndera