If you're installing MagicCarpet on a PC

Download the setup application and launch it. MagicCarpet will install itself and launch itself and then create a shortcut on the desktop.

If you're installing MagicCarpet on MacOSX

Download the compressed .dmg file and mount the volume (it should auto-mount). Then drag the MagicCarpet icon to your Applications folder.

If you're installing the MagicCarpet Revolution plugin

Download the MagicCarpet plugin file and put it into your altPlugs folder. It is best to use MagicCarpet with altPlugin toolbar because the altPlugin toolbar will automatically update it for you as newer versions become available. Next, launch Revolution and MagicCarpet should automatically be installed on the toolbar.

In order for MagicCarpet to connect properly to your server, you need to create 'Project Connection Settings.'

This is done by clicking the NEW button above the Project drop-down menu. The Project Settings dialog window will become visible.

Magic Carpet Project Settings

Project Name - Use a familiar name for this project.
This name will be displayed in the popdown menu on the main screen.

User - this is the name of this user and will be used in the log files for uploads, documentation, changes, etc.

UserName - this is the name used when accessing the FTP site.
Typically it may have the domain included.
Ex. johndoe@ibm.com

Password - this is the password string used when accessing the FTP site.
Passwords are typically at least 6 characters long.

FTP URL - this is the URL of the ftp folder where the project files are uploaded to.
Do not use "ftp://" at the front of this URL.
Ex. ftp.ibm.com/stuff

HTTP URL - this is the URL of the HTTP folder where project files are downloaded from.
It is the same folder as the FTP folder, though it may be mapped differently.
Do not use "http://" at the front of this URL.
Ex. www.ibm.com/stuff

Once the fields are filled out, be sure a click the Test Server Settings button to make sure you're connected properly. Press the OK button to store your settings.

You can also Edit and Delete Project settings using the Edit and Del buttons above the Project drop-down menu.

Next, choose the project you just created from the Project drop-down menu. If all goes well, you should see the activity bar blink and you'll be connected to your FTP server.

Note, you can store multiple project settings, each representing a different folder on your FTP server. In fact, you can also store settings for different FTP servers as well. Also, it is not mandatory (but typically a good idea) to provide a unique login name/password for each MagicCarpet user, as their activitiy is monitored not by their login name, but rather the name found in the User field.

Once you're connected to your FTP server, you'll see three tabs: MagicCarpet files, All files, Archives. MagicCarpet is used as a versioning, tracking, archiving and control system. It can be used with many users or a single user. MagicCarpet manages and controls 'version files.' These files are called 'MagicCarpet files' and are visible in the MagicCarpet files tab.

Typically, you'll mostly use the MagicCarpet files tab.

MagicCarpet files tab
To upload a document and make it ready to be versioned, tracked and archived, you'll press the Add File button. You'll be prompted to choose the file to upload. Next, you'll be asked a series of questions.

Compress file when uploading?
Answer "Compress" if you wish to use MagicCarpet's built in gZip compression for uploading and downloading. It's most always a good idea to compress your files, unless you're uploading files for others to access via the webserver outside of MagicCarpet such as html pages with images, css files etc.. If you're only using MagicCarpet for project and file management, then by all means compress everything.

Do you wish to archive a copy each time this file is uploaded?
Answer "Archive" if you would like to save a serialized version of this file each time it is changed. While this is a good idea for historical tracking purposes, it does take a bit longer to upload, and will use up storage space on your FTP server faster.

Please enter a version number to start with:
You are prompted for a version number to begin tracking this file with. You can put any number in this field you like. You will be able to change this version number at a later date on each subsequent check-in of the file.

Once completed, MagicCarpet will do the following:

1) Upload the specified file unless compression was chosen, then it will compress the file locally, add a '.gz' extension to the name and upload the compressed file

2) If archival was chosen, it will upload a copy of the file it just uploaded, with a '.0001' extension to the 'archive' folder. The number will be incremented each time the file is subsequently uploaded / checked-in.

3) A MagicCarpet text log file will be created using the filename of the file just uploaded with '.mgc' appended.

MagicCarpet reads only the files ending in '.mgc' to create the list of files in the MagicCarpet files tab.

4) Refreshes the MagicCarpet files table of contents file: MasterMGC.txt
Though all the version, control, notes, checksum and archival data is stored in the .mgc file, the table of contents file allows for much quicker access to the MagicCarpet files list. If ever the table of contents gets accidently deleted, or is somehow corrupted, it can be rebuilt easily by holding down the option-key when pressing the refresh projects button.

5) Refreshes the MagicCarpet files list with the newly uploaded data.

The MagicCarpet list has different icons and data for each .mgc file it encounters on the server. From left to right, here's what they all mean:

Avail - If the file is available for check-out, a green circle with a check will be visible. If the file is already checked-out, a red circle with an X will be shown.

Type - Different types can be assigned to files for labeling purposes. See below for information on how to create your own type with icons. These types have no effect on the application other than displaying a different icon in this list. You may customize this list by clicking the icons button on the main MagicCarpet interface

Arc - A green check will be visible if a file is to be archived upon each new upload.

GZ - A green check will be visible if the file is to be compressed upon each new upload.

Vers - The version number of the file. If this label is clicked on it will sort the MagicCarpet list by version number.

Filename - The original file name of the file uploaded. Note, if the file was to be compressed, the actual file name on the FTP server will include a '.gz' appended to this name. Clicking on this label will sort the list by file name.

Last Modified - The date/time of the file last uploaded to the server. This is the server time, not the client time, so if a server is in a different time zone, it may not reflect correctly the time relative to the user uploading the file. This is intentional so all files have the same timezone reference. Clicking on this label will sort the list by date.

Checked Out By - The name of the person who has currently checked-out this file. If the file is not checked-out, then the word 'available' is shown here. Clicking on this label will sort the list by Name.

A number of buttons appear at the bottom of the MagicCarpet tab. The Add File button has already been discussed earlier. Here are the functions of the other buttons:

Check Out button
You can only check-out a file which has a green 'Checked-in' icon in the Avail column. First, confirm your wish to check out the desired file. You are next asked:

Do you wish to Download this file?
Choose Download and Check-out if you wish to download the file before checking it out (this is the default). There may be times you only wish to 'Just Check-Out' the file, perhaps you have a newer version of it locally.

Check In button
When changes have been made to a file, and you wish to upload the file back to the server, press the Check In button. You will then be shown a File Properties window which allows you to set the following:

File Version - Change the number in this field to represent the latest version you are working on. This number is kept only in a single place: the .mgc file for the file being checked-in. In otherwords, the version number is not stored in any way in the original file and is used only for MagicCarpet version control.

File Type - Different types can be assigned to files for labeling purposes. MagicCarpet will try to automatically set the file icon based on the file extension and your fileType preferences (see the icon button on the main interface.) These types have no effect on the application other than displaying a different icon in the MagicCarpet list.

File - Click the Browse button to choose the file named at the top of this window. If the filenames do not match, MagicCarpet will not allow uploading. Also, you cannot change either the Archive or Compression settings for this file UNLESS you are uploading a file. If the Compress File checkbox is changed, then a NEW file will be uploaded and now two files will be displayed in the MagicCarpet list. It is suggested to delete the older file.

Note: In rare cases, it may be desirable to 'check-in' a file without uploading it. For instance, someone checked-out a file, made no changes, and forgot to check it back in and now a different user wants to check it out. In these cases, you can check-in a file without uploading a file. Just check-out the file and press OK.

Notes - This is the field where a user adds the current changes made to the version being uploaded. They are then concatenated with the notes from the field below the Notes field.

Shortcut - MagicCarpet will not let you check-in a file unless it is already checked out. In the event you wish to bypass this feature and check-in a file without checking it out, hold down the shift-key while pressing the Check In button. You can then directly check-in a file without checking it out first.


Properties Button
At anytime this button may be clicked to show the current log notes for the selected file. If the file is checked out to you, notes may be added at anytime, without having to check-in the file. This is a great way to keep running notes for changes made while a file is checked out. If the file is not checked out, or checked out to someone else, the properties window will display, but the contents may not be edited.

Add File Button
This button allows you to upload a new file to the server to be version controlled by MagicCarpet. It will prompt you for a file to upload, then ask different questions about how it is to be stored. Do you wish it compressed? Archived? Once finished, it will upload the file, create the necessary .mgc files and update the MagicCarpet table of contents. It is then available for check-out and management.

Del File Button
This button will delete both the file and the transaction log file (.mgc) and update the MagicCarpet table of contents, but will not delete any of the archived files. Note, once deleted, the files cannot be retrieved, so be careful with this button.

Download Button
Sometimes it may be necessary to download a file and not check it out. This button will download the selected file to a local folder. It will automatically uncompress the file if it is compressed.

All files tab
This screen shows a list of all the files at the server location designated by the Project Settings. There are no filters, other than folders are not shown. Here, a user can manually upload, download, delete and edit files. But, any transaction done from this pane will NOT be reflected in the MagicCarpet transaction logs (unless of course one of the transaction log files: .mgc, are edited).

The All files List
The All files list has three pieces of information for each file. From left to right they are:

Size (K) - The size in K of the file on the server. If the file is compressed, this is the compressed size. Clicking on this label will sort the list by file size.

Filename - This is the actual name of the file on the server, which may be different from the name seen on the MagicCarpet files tab. Clicking on this label will sort the list by file name.

Date Modified - The date/time of the file when last uploaded to this server. This is the server time, not the client time, so if a server is in a different time zone, it may not reflect correctly the time relative to the user uploading the file. This is intentional so all files have the same timezone reference. Clicking on this label will sort the list by date.

The All Files Buttons
A number of buttons appear at the bottom of the All files tab. In order, they are:

Upload - Uploads a file to the server. Files uploaded may not contains spaces.

Download - Downloads a file from the server. If the file is gZip compressed, it will automatically decompress it.

Delete File - Deletes a file on the server. If you have a problem transaction log file (.mgc), you can delete it here and re-upload the file from the MagicCarpet files tab. You'll want to first download a copy of it to save the log text which you can then add to the new .mgc file using the Edit File button.

Edit File - Opens a small text editor window to allow one to edit contents of text files. This is also good for manually editing transaction log files (.mgc). Will not work on binary data.

Archives tab
This screen shows a list of all the files in the folder 'archive' at the server location designated by the Project Settings. Here, a user can manually download and delete any of the archive files. Any transaction done from this pane will NOT be reflected in the MagicCarpet transaction logs.

The Archives List
The All files list has three pieces of information for each file. From left to right they are:

Size (K) - The size in K of the file on the server. If the file is compressed, this is the compressed size. Clicking on this label will sort the list by file size.

Filename - This is the actual name of the file on the server, which may be different from the name seen on the MagicCarpet files tab. Clicking on this label will sort the list by file name.

Date Modified - The date/time of the file when last uploaded to this server. This is the server time, not the client time, so if a server is in a different time zone, it may not reflect correctly the time relative to the user uploading the file. This is intentional so all files have the same timezone reference. Clicking on this label will sort the list by date.

The Archives Buttons
A number of buttons appear at the bottom of the All files tab. In order, they are:

Download - Downloads a file from the server. If the file is gZip compressed, it will automatically decompress it.

Delete File - Deletes a file on the server. If you have a problem transaction log file (.mgc), you can delete it here and re-upload the file from the MagicCarpet files tab. You'll want to first download a copy of it to save the log text which you can then add to the new .mgc file using the Edit File button.

Other Controls
There are a couple of other controls users should be aware of. At the top of the tabs to the right are (clockwise from upper right)

icons button - opens an icons preferences list where you can choose which icons you want to use. MagicCarpet will automatically assign an icon based upon the file extension and whether on not you have chosen to use it in your list. So, if you check the .pdf filetype, then any Acrobat (.pdf) documents you upload will automatically be assigned the .pdf icon. If you don't check it, then they will be assigned a blank icon. You may also add and assign your own custom icons if you wish. See the section on Creating custom Filetype icons for more information.

Help button - takes you to the online help

Backup button - makes a file for file backup of the files on the server. If either the MagicCarpet files tab or the All files tab is selected, all files on the folder designated by the FTP url in the project settings will be downloaded to the folder of your choice. This will not decompress or otherwise alter any of the files as they are downloaded. If the Archives tab is selected, then all the files in the archive folder of the FTP url will be downloaded to the folder of your choice. Again, files will not be decompressed or otherwise altered. If you wish to make a backup of the current versioned files, then use the Synchronize Folder button.

Refresh button - Sometimes a user may wish to rerfresh the list. Clicking the refresh button does so instantly. Option-clicking the refresh button will rebuild the MasterMGC.txt file on the server. The MasterMGC.txt file on the server is a lookup file which houses directory info for all of the version control files (called MagicCarpet files and displayed in the MagicCarpet file tab).

Stop button - Typically if MagicCarpet cannot connect to a server, it will display a timeout message. If for some reason a user wishes to interrupt a transaction (not recommended), the Stop button may be pressed and instantly the network settings for MagicCarpet are reset.

Synchronize Local Folder - This button is only visible when the MagicCarpet files tab is selected. You are first prompted for a local folder to synchronize files to. Then MagicCarpet will use a checksum function to find out if the files in your folder are different from those on the server, and if so, download from the server the files which do not match. This can also be used to download and backup all versioned files, as this feature automatically decompresses files if necessary. Note, Synchronize Local Folder will only download  different files, so a newer file on your local machine will be replaced with the older file from the server. This is a feature intended for teams of users where they want to get the latest 'checked in' files from the server.

Set Timeout Interval - Sometimes it may be necessary to lengthen the default timeout interval of 10 seconds. For instance, if you're trying to connect to an FTP server in another country, you may try setting the interval to 30 seconds or longer. This is also helpful if you're on a real slow or busy connection.

(not visible in picture)

Shrink button (at the top next to the MGC logo) - Allows you to shrink the MagicCarpet application while still showing the status of uploads and downloads. If you're uploading or downloading a large file, you may monitor it's progress easily by clicking the down arrow at the top left of the main window.

The log field at the bottom is mostly just FTP commands and useful for detecting problems in uploading and/or downloading.

A status field at the bottom is used for backup and folder synchronization. It is displayed only during those functions.

When you upload a file in MagicCarpet, you may choose to assign it a custom icon. In order to do this, it is necessary to place your custom icon(s) in a special folder MagicCarpet looks for when starting up. The icons should be GIF files and 16x16 pixels in size. If you have larger icons, MagicCarpet will autoscale them to fit in the table grid.

You should name your icons in such a way as they can be identified when assigning them in the properties window. For instance, if you have a PDF icon, you should name it "PDF.gif" (though a pdf.gif icon already exists there). You may use as many icons as you like.

For WindowsXP the special folder is:
C:\Documents and Settings\All Users\Application Data\MagicCarpet\fileIcons

If you cannot find the folder, you may need to choose Folder Options under the Tools menu of File Explorer, and check the Show hidden files and folders radio button.

For Mac OSX the special folder is:
<home>/Library/Preferences/MagicCarpet/fileIcons
where <home> is the current user name.