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.

Versions

This is the documentation for version 0.5. Documentation for version 0.1 can be found in FwSync0dot1. Documentation for the current version can be found in FwSync.

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 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:

    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.

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.

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