Projects briefcase

Projects briefcase can be distributed and used freely. It is released under the GNU General Public License (GPL). Please provide a link to http://projects-briefc.sourceforge.net if you do distribute it.

DISCLAIMER

Projects briefcase comes with ABSOLUTELY NO WARRANTY; for details see the file LICENSE. Furthermore, please note that the software is still in the beta stage. I have been using previous versions myself for some time. I have encountered some serious problems, probably related to third-party CD-writing software, which may result in completely suspending your system, as described in the "Known problems" section close to the end of this file. There may be other problems, not listed here. Please note that the program has not yet been tested on any OS other than WinXP.

What is it?

Projects briefcase is a very simple tool for transferring files between different workstations using a CD-RW. It should aid every developer who has to work at different workstations on the same projects (e.g. working at two places or doing some work at home as well). I wrote it because I badly needed it for my work.

Manually copying files using a CD is easy enough, but:

you have to browse to find your project directory each time
it is easy to forget which workstation has the most current version of the files, or are they still on a CD you just found?
if it takes too much time, you might be reluctant to do it (speaking from experience).

The idea was to make it as simple as possible: you insert a CD-RW (formatted for packet-writing) to have your projects stored on the disk and then you insert the CD to another workstation to have them restored. Then, when you finish your work, you insert the CD again, and so on. At best the program should store no settings on a workstation, require no installation on the workstation (of course the CD-RW has to be prepared) and work pretty much automatically.

You prepare a CD-RW (explained below) with the program and a settings file that lists the projects you want to move. When you insert the CD-RW, the program is auto-run and copies your projects onto the disk. It will ask about (and save on the CD) the location of each project it does not know where to find on this machine. Project locations are stored in a separate text file for each machine. The directories on the hard disk are renamed - they get an added ".archive." and today's date - to make sure you do not edit projects that were "taken somewhere else", by mistake. To continue your work at a different machine, you follow a similar procedure. The projects are removed from the CD upon successful copy.

Requirements

Projects briefcase operates on directory level. It may archive/restore entire directories (with subdirectories) only, so every project you wish to transfer must be placed in its own directory. You should make sure that each workstation you use has its own unique descriptive name, as different workstations are identified only by their names by Projects briefcase.

In order to use Projects briefcase with CD-RW you need CD packet-writing software, e.g. InCD by Ahead NERO. In general, you can use it with any media where you can copy/manipulate files using the MS Windows standard Shell, for example floppy disks (for small projects), USB hard disks etc. Please note, however, that Projects briefcase cannot split projects that do not fit on the media. Autoplay must be enabled for the program to start automatically. It may not be available for some media, so you will have to start the program manually. When run, the program examines the path to the executable (with no regard to the current or working directory) and uses the subdirectories "settings" and "projects" of its containing directory to store settings and project files. Make sure there are no other files in these locations as they might be overwritten or deleted.

In this guide I assume that you will be using a blank CD-RW.

You may download Projects briefcase from here. Make sure you select a "binaries" package from the most recent release.

How do I use it?

You prepare a CD-RW (formatted for packet-writing) where you place the contents of the "binary" directory of this package (do not copy the directory itself). Now you can eject the CD (to make sure all data has been written) and insert it again. If the Autoplay feature is enabled, the program window will appear. Be patient - the packet-writing software needs to initialize, the Autorun file must be processed, it all takes time. I you disabled Autoplay, you can start the program yourself. It is "briefcase_mswindows.exe" in the root directory of the CD. You should see a window like this:

The first edit field lists active projects, i.e. the ones you want to transfer using this particular briefcase. You enter each project you want to transfer in a separate line in the form:

<project name> restored here

So, replace "test_project" with the name of the project you want to move to the briefcase and add more lines as necessary. I suggest that for this first session you create some empty directories to represent dummy projects on your hard disk and use those.

Project name may contain no spaces, must be unique and fairly descriptive, so you do not get confused. It need not be the same as the name of the project directory, although I would suggest it should be, unless you need to extend it to make it unique. The project name will be used for storing Projects briefcase settings and storing project files on the CD. When the program asks you about the project location or display other messages, it will use the project name.

Once the projects have been specified, press OK to transfer the files and answer the prompts. If everything went well, the program window should now look like this:

Press OK to close the program window and eject the CD.

When you want to continue your work at a different machine, insert the CD there. You should see a program window as above, except, the "locations" field will be empty, because the program does not know where these projects should reside on that machine, so it will ask you. When you press OK, the projects should be restored.

Projects briefcase settings and controls

When the program starts, the two edit fields represent the contents of the setting files located in the "settings" directory on the CD. The top edit field shows the "active.briefcase_projects.txt" file, which consists of lines in the form

<project name> restored to <workstation name>

<project name> archived from <workstation name> <year>.<month>.<day>

Additionally, "restored here" may be entered instead of "restored to <workstation name>" to indicate that the project is on the present workstation. If any of the lines is non-empty and does not fit to the above pattern, the user receives warnings but all the lines are preserved. When you press OK, all the projects marked as "archived" are restored onto the workstation and removed from the CD and all the projects marked as "restored" to this particular workstation are archived. Usually it is not a good idea to mix the two modes.

The bottom edit field represents either the locations file (named <workstation name>.project_locations.txt) or the file "inactive.briefcase_projects.txt", depending on the option selected. Project locations are specified in subsequent lines of the form:

<project name> <directory>

Only the lines that match the above pattern are stored in memory. All the other lines are lost, which means that you will be asked about the locations of the corresponding projects when they are needed. You should not edit the locations yourself. When the location of a project is changed, you can just delete the appropriate line, so the program will ask you to browse for the project directory again.

The "inactive.briefcase_projects.txt" file has no special meaning to the program, but it is useful to save the status of the projects that you want to stop moving around for some time. In that case, first, make sure the project is where you want it, i.e. restored to the appropriate workstation. Then you just cut the project status line from the top edit field, select "Inactive projects" below and paste the line to the bottom edit field. The project will not be moved until you put its status line back to the "active.briefcase_projects.txt" file.

After the settings are specified as required, pressing OK starts the file transfer to and/or from the briefcase and, when it is completed, pressing OK again exits the program. Pressing Cancel does not transfer the files and discards the changes made to the settings. Pressing Close does not transfer files, but saves the settings.

Data safety and error recovery

Projects briefcase uses system shell functions to perform file operations. These operations include copying, renaming and deleting directories. Please be very careful when you use Projects briefcase on platforms where it has not yet been tested. If you encounter an error while using Projects briefcase, you should verify the presence and examine the contents of your project directories on the hard disk and on the CD and recover your files manually. This is entirely YOUR RESPONSIBILITY.

All kinds of errors are possible when moving files around. The most probable ones are:

not enough disk space
invalid directory name
no rights to modify/overwrite a file
etc.

The best I could do is: when there is an error, do not try to do anything more with this particular project. So, if the project cannot be restored, it should not be deleted from the CD, etc. In such a case the project status will not be modified, so if you tried to restore the project and failed, the project status should still read "archived". If, however, at least some of the projects were successfully archived/restored, but the access to the settings file is refused, the program can do nothing about it, so the information on the CD will be false and may cause data loss. There might also be hardware failures involved, etc.

In general, in order to minimize the danger of accidental data loss, you should only use Projects briefcase to move data between different workstations, i.e. avoid placing projects in the briefcase and restoring them right back onto the same workstation (which would make no sense anyway). When you keep your files on several machines, they are safer. Please have a look at the "Known problems" section below, as well.

Why would I use it?

Alternatives include backup programs (involves several steps each time), copying/moving files manually (error prone), various existing "briefcase" applications (Ms Briefcase always seemed to drop some files when I tried it and copying took a long time; Yahoo Briefcase requires a fast and cheap internet connection; there is one briefcase at SourceForge, but it seems to be a Unix shell script, no use for me under Windows) and perhaps some version control systems - much more powerful and much more complicated, and with a very different scope. This program does only one simple thing and may therefore be very simple to use.

Can I port it to another OS?

Of course! I tried to make sure that porting is fairly straightforward by separating the OS-specific parts from the rest. I use system shell functions to copy/rename/remove directories. Porting involves implementing these functions and the user interactions. Some info on porting is provided in the "specific.h" header file. Please let me know if you succeed.

Known problems

Projects briefcase relies on CD packet-writing software in order to store/retrieve/delete the files on/from CD-RW. I am using InCD 3.51.91 (by Ahead Software) for this purpose. Program settings are also stored on the CD-RW. When any of the settings files is modified using an editor, and then Projects briefcase is invoked, the system is likely to be suspended. The same is likely to happen, when the CD contents were modified and then the user tries to display the contents of the CD. Although Windows XP (tm) is able to recover from many crash situations and kill misbehaving processes, it does not seem to work in this case. I had to cold-restart the system in several cases.

I suspect that the reason for this problem is that something is asked from the CD drivers while cached data is still being written to the CD. As far as I can tell, this problem does not occur if you patiently wait until all the cached data have been written before proceeding to perform another operation.

The present (first public) release of Projects briefcase partially fixes the root of this problem as it exposes the contents of the settings files to the user and stores all the changes in memory until the transfer to/from the briefcase is performed. All the CD-writing operations are now likely to be saved in one go.
If you archive a project, then restore it on the same workstation on the same day, and then archive it again, on the same day (or with system clock set to the same date), your first archive directory will be removed from the hard disk. If the project files on the CD were corrupted, you will loose your original files. Therefore, whenever there are any error messages while using the program, you should always examine the contents of your project directories and Projects briefcase setting files.

Please let me know if you find any other problems.

Acknowledgements

This project is hosted by SourceForge. The executable has been compressed with the UPX executable packer (http://upx.sourceforge.net) by Markus Oberhumer & Laszlo Molnar.

I hope the program works for you!

Maciej Radziejewski maciejr@users.sourceforge.net

Poznan, Poland, 10 March 2003