Fw Sync1dot1

Enter a topic name to show or a new topic name to create; then press Enter

.

Summary

FwSync is a command-line tool for editing the wiki.

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 1.0, which was released May 30th, 2004. Download version 1.0 here .

Versions

This is the documentation for version 1.0. Documentation for previous versions can be found on the following pages:

Version	Topic
Version 0.9	Never documented (whoops)
Version 0.8	FwSync0dot8

        ||Version 0.7||FwSync0dot7||

Version 0.5

FwSync0dot5

Authorship

FwSync was written by CraigAndera.

Compatibility

FwSync requires that the FlexWiki website it talks to must be at least build 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

General Help

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

 fwsync help

at the command line. If you do, here is what you will see:

 fwsync 1.0.1831.5643 Copyright (c) 2004 Craig Andera candera@wangdera.com 


 Usage: fwsync <globaloptions> <command> <commandoptions>


 Run one of the following commands to get more detailed help:
   fwsync help commands     Help on available commands and their options
   fwsync help options      Help on available global options
   fwsync help environment  Help on environment variables that fwsync uses

Help on Commands

Running

 fwsync help commands

at the command line will give you the following message:

 fwsync 1.0.1831.5643 Copyright (c) 2004 Craig Andera candera@wangdera.com


 Available Commands: 


   commit   - Push local changes to the remote wiki
   help     - Print help
   init     - Initialize the local wiki files
   update   - Retrieve updated content from the remote wiki
   status   - Print status of topics
   resolve  - Fix any conflicts between local and remote content


 To get more detailed help for these commands, run fwsync help <command>. For
 example, run 'fwsync help init' to get help on the init command.

Help on options

Running

 fwsync help options

at the command line will give you the following message:

 fwsync 1.0.1831.5643 Copyright (c) 2004 Craig Andera candera@wangdera.com


 These options may be specified with any command (except as noted):
  /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.
  /localonly      Tells fwsync not to connect to the web instance of the wiki
                  when performing this command. Useful for getting status of
                  the local wiki when network activity is impossible or
                  undesired. Illegal with the commit and update commands.
  /noauth         Do not authenticate. If this switch is present, the /defcred,
                  /user, and /password switches are ignored.
  /y              Do not prompt the user for confirmation - answer yes to every
                  question.

Help on Environment Variables

Running

 fwsync help environment

at the command line will give you the following message:

 fwsync 1.0.1831.5643 Copyright (c) 2004 Craig Andera candera@wangdera.com


 FwSync makes use of the following environment variables, if set:


 FWSMERGE     Set this environment variable to be the path to a tool to use
              when merging files with the resolve command (see fwsync help
              commands). The tool should accept a path to a copy of the
              remote file as the first argument, a path to the local file as
              the second argument, and a path to an output file where the
              results of the merge should be saved as the third
              argument. Standard merge tools such as WinMerge
              (http://winmerge.sourceforge.net) conform to this pattern, and
              should work with fwsync. This environment variable is
              overridden by the resolve command's /use switch, if specified.


 FWSOPTIONS   When set, the contents of this environment variable are
              prepended to the command line of every invocation of
              fwsync. For example, if FWSOPTIONS is set to '/defcred', then
              invoking the command


                 fwsync update


             is equivalent to invoking


                 fwsync /defcred update


             instead.

Help on the Commit Command

Running

  fwsync help commit

at the command line will give you the following message:

 fwsync 1.0.1831.5643 Copyright (c) 2004 Craig Andera candera@wangdera.com 


 fwsync commit


 This command uploads to a remote wiki any changes you have made to local
 files.


 Usage:


   fwsync commit /attribution <identity> [ /ignoreconflict ] [ <path> ... ] 


   /ignoreconflict   Skip topics that are InConflict (see fwsync help
                     status) rather than preventing the commit. 


   <identity>  A name or email address to which the changes being committed
               should be attributed. This will show up in the history
               section of the FlexWiki website.
   <path> ...  A list of one or more files or directories separated by
               spaces. Paths with spaces in them must be enclosed in double
               quotes. If no path is specified, the current directory is
               used. Specifying a directory is the same as specifying all
               topics in that directory.


 The commit command is the mechanism by which local changes are moved to the
 FlexWiki website specified at init (see fwsync help init) time. Any
 specified topics that have a status (see fwsync help status) of
 LocallyModified or LocallyAdded will be submitted to the wiki, where they
 will become the new version of that topic.


 By default, the commit command will refuse to commit *any* topics if at
 least one of the specified topics is InConflict. However, if the
 /ignoreconflict switch is specified, InConflict files will be ignored, and
 LocallyModified and LocallyAdded files will be allowed to be committed.


 The /attribution switch is required, but is ignored when the /defcred or
 /user (see fwsync help options) switches are specified. This may be
 addressed in a future version of fwsync.

Help on the Help Command

Running

  fwsync help help

at the command line will give you the following message:

 fwsync 1.0.1831.5643 Copyright (c) 2004 Craig Andera candera@wangdera.com


 fwsync help


 This command prints help for the fwsync program.


 Usage:


   fwsync help [ <helpTopic> ]


   <helpTopic> The name of a topic on which you would like further help.


 Run without a help topic, this command prints general help for the fwsync
 program, listing further available help topics. When run with a help topic,
 prints help about that topic, if it is available. 

Help on the Init Command

Running

  fwsync help init

at the command line will give you the following message:

 fwsync 1.0.1831.5643 Copyright (c) 2004 Craig Andera candera@wangdera.com


 fwsync init


 This command performs the initial setup for an fwsync-synchronized wiki.


 Usage:


   fwsync [ /localonly ] /url <wiki url> init [ <directory> ]


   /localonly  Set up the wiki locally, but don't connect to the web site to
               get a list of topics.


   <directory> A directory somewhere on your local disk. Relative or absolute
               paths may be used. If no directory is specified, the current
               directory is used. This directory is called the base
               directory.
   <wiki url>  A URL like http://www.flexwiki.com or
               http://www.myserver.com/wiki where a FlexWiki website lives.


 FlexWiki websites are organized into a series of namespaces. When running
 the init command, the directory you specify is known as the 'base
 directory'. Topics for each namespace are kept as individual .wiki files
 within a subdirectory of the base directory with the same name as the
 corresponding namespace.


 The primary job of init is to create the file 'fwstatus.xml', which is kept
 in the base directory. This file holds information about things like what
 version of each topic is thought to be on the server, which helps figure
 out the status of each file (see fwsync help status).


 Init requires the /url option - the specified URL will be stored and
 remembered for use later by other commands acting in the same
 directory. Init will connect to the server at the address specified by the
 /url option to download information about the remote wiki unless the
 /localonly option is specified. When /localonly is specified, fwsync merely
 creates the fwstatus.xml file and populates it with information about any
 .wiki files already present on the hard disk in subdirectories of the base
 directory. 

Help on the Update Command

Running

  fwsync help update

at the command line will give you the following message:

 fwsync 1.0.1831.5643 Copyright (c) 2004 Craig Andera candera@wangdera.com


 fwsync update


 This command retrieves fresh copies of any topics that have changed on the
 remote wiki.


 Usage:


    fwsync update [ <path> ... ]


    <path> ... A list of one or more files or directories separated by
               spaces. Paths with spaces in them must be enclosed in double
               quotes. If no path is specified, the current directory is


               used. Specifying a directory is the same as specifying all
               topics in that directory.


 Retrieves any files that have been added or changed on the remote server,
 unless they have also been modified on the local machine. If they have also
 been modified on the local machine, the topic is in conflict (see fwsync
 help status) and must be resolved (see fwsync help resolve). 

Help on the Status Command

Running

  fwsync help status

at the command line will give you the following message:

 fwsync 1.0.1831.5643 Copyright (c) 2004 Craig Andera candera@wangdera.com


 fwsync status


 This command displays the status of topics.


 Usage:


    fwsync [ /localonly ] status [ /show { U|O|M|N|C|A } ] [ <path> ... ]


    /localonly Prevents fwsync from connecting to the remote wiki to update
               version information. Prints status more quickly, but may not
               accurately reflect what is on the FlexWiki website.
    /show      When present, specifies one or more status codes (see below)
               to limit display to. For example, /show U specifies that only
               UpToDate files should be shown. More than one status code may
               be specified.


    <path>  A list of one or more files, topics, or directories separated by
            spaces. Paths with spaces in them must be enclosed in double
            quotes. If no path is specified, the current directory is
            used. Specifying a directory is the same as specifying all topics
            in that directory.


 The status command operates by comparing the local (filesystem) and remote
 (repository) versions of a topic. By examining the difference between the
 state of a topic now and the state when it was last updated (see fwsync
 help update), fwsync can determine which of the following states the topic
 is in:


   U = UpToDate         The file is identical with the latest revision in the
                        repository.
   M = LocallyModified  You have edited the file, and not yet committed your
                        changes
   A = LocallyAdded     You have added the file to the local file system and
                        not yet committed your changes.
   N = NoLocalFile      The local file does not exist - it needs to be
                        retrieved from the repository via the update command.
   O = LocallyOutOfDate Someone else has committed a newer revision to the
                        repository. You can retrieve the latest version with
                        the update command.
   C = 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 this topic while it InConflict. See fwsync
                        help resolve command for instructions on how to deal
                        with conflicts. 

Help on the Resolve Command

Running

  fwsync help resolve

at the command line will give you the following message:

 fwsync 1.0.1831.5643 Copyright (c) 2004 Craig Andera candera@wangdera.com


 fwsync resolve


 This command allows the user to integrate changes made on the local wiki
 with changes made on the remote wiki.


 Usage:


   fwsync [ /y ] resolve [ /use <mergeprogram> ] [ <path> ... ]


   /y     Instruct fwsync to accept all merged changes. Has no effect when
          /use or FWSMERGE (see below) is set.


   <mergeprogram> Specifies a program (such as WinMerge) to use to integrate
                  differences between local and remote files. This program
                  should follow the same convention as the FWSMERGE
                  environment variable (see fwsync help environment).


 Merges changes from the repository with the changes you have locally. By
 default, the program will display both copies of the topic in notepad, and
 you will have to hand-edit them to resolve changes. The program will ask you
 to confirm each merge unless you specify the /y global option (see fwsync
 help options). 


 The /use switch (see below) or the FWMERGE environment variable (see fwsync
 help environment) can be specified to tell fwsync to launch a merge program
 instead to resolve the conflicts.


 This command ignores files whose status is not InConflict (see fwsync help
 status).

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 FormattingRules 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. Or run fwsync /localonly status to find out what has changed only on 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, unless you specify the /localonly switch). 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)
• 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)
• 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)
• Add an option to status command that doesn't connect to the web; a localonly status. (complete as of version 0.8)
• Break core functionality out into separate assembly
• Once previous feature is done, write GUI front end for people that like that better
• Shell integration would rock! Think TortoiseSVN. Perhaps TortoiseFW?
• I've thought about it. But it's fairly unlikely to happen - it wouldn't be easy. Instead, expect to see FwSync features in FlexWikiPad. -- CraigAndera [2005-01-23]
• 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. (complete)
• Add in some sort of feedback so the user knows something is happening on long uploads. (complete as of version 0.8)
• Add a verbose mode so the user can select how much feedback they get.
• Make /defcred the default if /user is not specified. -- TommyWilliams (This is generally avaiable via the FWSOPTIONS environment variable)
• 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 (complete as of version 1.0)

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. (fixed in version 1.0)
• 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. (fixed as of version 1.0)
• 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
• I haven't had any problems with the current build (1569) running on the FlexWiki website. This one looks like it's fixed. -- CraigAndera
• I'm consistently getting "HTTP Status 401: Unauthorized" failures trying to init with fwsync 1.0.1831.5643, no matter what the site (even with fwsync /url http://www.flexwiki.com init c:\mylocalflexwiki) -- ChrisRogers
• Init yields "Object Moved" against 1.8.0.1703 --JonLeCroy
• After a fwsync update or commit, WikiTalk script that referenc the updated or altered topics start failing with "Object reference not set to an instance of an object." Reproes with build 1716.

Questions and Answers

Question

Will it do a merge? -- DavidOrnstein

Yes. Implemented as of version 1.0 using the resolve command. -- CraigAndera

Question

Will it work with the FlexWikiEditor? -- DavidOrnstein

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

Comment

Uh this so rocks! -- OmarShahine

Thanks! -- CraigAndera

Question

Can I use FwSync to delete pages ? Replacing the content with the word delete does not seem to work -- Andy.Farr(noSpam)@(noSpam)bentley.com

Question

No problems with init, update and status commands. But commit command is not working at all -- Eugene

        C:\Program Files\FWSync>fwsync /defcred commit /attribution Eugene


        fwsync 1.0.1831.5643 Copyright (c) 2004 Craig Andera candera@wangdera.com
        An unhandled exception was thrown.


        System.Web.Services.Protocols.SoapException: System.Web.Services.Protocols.SoapE
        xception: Серверу не удалось обработать запрос. ---> System.ArgumentOutOfRangeEx
        ception: Индекс и длина должны указывать на позицию в строке.
        Имя параметра: length
           в System.String.InternalSubStringWithChecks(Int32 startIndex, Int32 length, B
        oolean fAlwaysCopy)
           в FlexWiki.Web.Services.EditServiceImplementation.WriteAllowed() в c:\Builds\
        ccnet\server\flexwikicore-20\Working\build\FlexWiki.Web\Services\EditServiceImpl
        ementation.cs:строка 359
           в FlexWiki.Web.Services.EditServiceImplementation.SetTextForTopic(AbsoluteTop
        icName topicName, String postedTopicText, String visitorIdentityString) в c:\Bui
        lds\ccnet\server\flexwikicore-20\Working\build\FlexWiki.Web\Services\EditService
        Implementation.cs:строка 274
           --- Конец трассировки внутреннего стека исключений ---
           at System.Web.Services.Protocols.SoapHttpClientProtocol.ReadResponse(SoapClie
        ntMessage message, WebResponse response, Stream responseStream, Boolean asyncCal
        l)
           at System.Web.Services.Protocols.SoapHttpClientProtocol.Invoke(String methodN
        ame, Object[] parameters)
           at FlexWiki.FwSync.EditServiceProxy.SetTextForTopic(AbsoluteTopicName topicNa
        me, String postedTopicText, String visitorIdentityString) in c:\data\Projects\fw
        contrib\fwsync\release\EditServiceProxy.cs:line 175
           at FlexWiki.FwSync.Synchronizer.Commit(String identity, StringCollection file
        s, Boolean ignoreConflicts) in c:\data\Projects\fwcontrib\fwsync\release\Synchro
        nizer.cs:line 174
           at FlexWiki.FwSync.App.Main(String[] args) in c:\data\Projects\fwcontrib\fwsy
        nc\release\App.cs:line 90