IntraVersion: User Manual

[ IntraVersion Home | Installation | User Manual | Pro: Features | News | Buy IV Pro ]

How To Use IntraVersion

Basics

• IV runs on a web server. It can be your local PC, or a remote machine.
• Each user has a 'working directory' - i.e. iv/users/admin where there files are
• Users move files to and from their IV working directory using FTP, or via IV as zip files...

Uploading Files

The easiest way to transfer files between your machine, and IV, is via FTP. We'd recommend FileZilla.

Alternatively, you can upload a whole project into IV as a zip file from the Upload page. You first have to create a project directory for the files to be unzipped into.

You should ensure your zip file doesn't contain any 'extra' directories above the project files before you upload. You can choose to empty the project directory before the file is unzipped.

You can also upload individual files and create sub-directories from the file-list page.

Load a New Project

To load a new project into IV, copy the entire directory structure of the project into your working directory, then go to the 'Update Project' page. Select the directory from the drop-down list, and click 'Update'.

This will create a new project with the same name as it's root directory.

For projects with loads of files: If PHP times-out while importing a project, you can simply refresh the page (Update Project), and it will add the remaining files the next time around. If it keeps timing out - you can increase the default page timeout in settings.php.

Update A Project

To update any files in a project, ensure the updated files are in your working directory, go to 'Update Project'. Select the directory from the drop-down list, and click 'Update'.

You can also update projects directly from the 'Projects' page (click the 'Update' icon).

IV will only check the files that are there (in your working directory)... All the files that are in the directory will be checked for changes and updated. Any new files will be added.

You can also upload and update individual files directly - from the File List page.

If a file has changed, it's version will be incremented, and the new contents stored in the DB. If a file is checked-out to another user, an error will be generated, and the file will not be updated.

Viewing Project Files

When you click on a project name in the list of projects, you're taken to the 'File List' page. This shows any files & sub-directories defined.

Sub-directories can be renamed, and moved. They can also be 'stopped' - see below 'Stop Tracking Files / Directories' for more info. Clicking on a sub-directory takes you to the file-list for that sub-dir.

Files can be renamed, moved and 'stopped'. They can also be uploaded, updated, got and checked-out from the file-list page.

Clicking on a file takes you to the 'View File' page...

The File View Page

This page show the latest details, branches and history for a file.

Latest details are on the left. You can checkout /checkin / update the file from here. If the file is already checked-out, it will give the name of the user it's checked out to. If the file is a branch, it will say so.

All available file branches are listed on the right at the top. Click on the branch name to view it. Once you are viewing the branch, you can get / update it as normal.

You can see the differences between different versions of a file, or the differences between the latest versions of two branches. Simply select the files to compare, and click the 'Diff' button.

You can delete branches directly from this page by clicking the 'Delete' icon next to the branch.

Get / Checkout Files

To get or checkout files from a project, you can either select the individual files from the file-list, or get the whole project...

When a file is checked-out it' effectively 'locked'. It can be 'got' by any user, but can only be updated / checked-in by the user who has it checked-out.

To get individual files from the file-list, you can either click the 'Get' (or 'Checkout') icon for a single file, or tick the checkboxes on the left, then click the 'Get' (or 'Checkout') button for multiple files.

You can get file to: 1) Your Working Directory, 2) The Build Directory, or 3) A Zip File.

'Test Get' prevents any files being written (used for test purposes).

'Process Macros' convert IV macros to the appropriate values. For getting code for development purposes, this can be left OFF, for getting code for production, it should be ON.

See below for details on getting whole projects.

Renaming & Moving Files & Directories

You can rename and move both individual files and directories by clicking the 'Rename' icon.

Simply enter the new filename and path, and click 'Rename'.

This only changes the current file information, not historical data - so when getting historical projects, the old filenames / paths are preserved.

Also, when you view historical projects, it will show the file name & directories that existed at the time that version was created.

You must ensure that you remove or rename the file / directory prior to updating the project or the old files will be added again.

Building Projects

In the 'Projects' page - if you click on the 'Build' icon for a project, you will be taken to the Project Build options...

This allows you to create a new release of a project.

Bear in mind that you can get all the files for any version of any project at any time - so it's not important that the files are actually output at this stage - hence the option 'Create No Files'.

Build Options:

• New Version Number - can be any string, but must be greater than the previous project version (release).
• Create No Files - Disables the writing of project files. This is so you can create a build, then get it separately - for example if it comes in various options, and you want to get all the files as a zip...
• Get To Directory - where to write the files (if 'Create No Files' is off)
• Test Build - will run through and check the build is viable without creating it.
• System Command - run a system command after the build has completed (i.e. 'make').

The build will fail if any files are checked out, or if nothing has changed.

The build process creates the new project version. The current version of all the files in the project are stored.

Getting Projects

In the 'Projects' page - if you click on the 'Get' icon for a project, you will be taken to the Project Get options.

This page allows any user to get whole projects with various options...

Get Options:

• Version - Any previous project version (release), or 'Latest Files'.
• Branch - You can choose to get any branch that is defined in files for this project, or '(trunk)' for the main (production) files. Only one branch can be 'got' at once.
• Get To - where to write the files: Working Dir, Build Dir or Zip file.
• Build Options - (IV Pro only!) any project options you have defined in the files for this project will be automatically listed here. You can choose to include any number.
• Rename Project Directory - this will include options and version in the dir. name (e.g. the project directory 'IV' will be written as 'IV_Pro_1.04')
• Process Macros - Convert IV macros to the appropriate values. If you are getting a project for distribution you should set this ON.
• Test Get - no files will be written.
• System Command - run a system command after the build has completed (i.e. 'make').

When distributing your projects, you should set 'Rename Project Directory' ON, 'Process Macros' ON, and we like the 'Get To' to 'Zip File' option because we can use the distribution file in that form.

Stop Tracking Files / Directories

You can stop a file or directory from being tracked by IV by clicking the 'Stop' icon.

If a file/directory is not being tracked it's content is not stored, and it is not included in builds and gets.

You can re-start tracking on a stopped item by clicking the 'Start' icon.

Deleting Files / Directories

Once a file/directory is stopped, it can then be deleted. Clicking the 'Delete' icon brings up a confirmation box.

Files that have been included in project releases can only be deleted by someone with 'admin' access. Other wise anyone with 'developer' access can delete a file.

Direcories can only be deleted by someone with 'admin' access.

Note: Files with branches must be deleted individually - i.e. the trunk is deleted first, then you have to keep clicking 'Delete' until all the branches of the file have been removed.

File Branching

Branching allows you to store multiple copies of the same (source-code) file in IV. This allows you to develop variants and prototypes of code without affecting the main development files.

Main files are called 'trunk' files - i.e. not a branch. Only trunk files are ever included in project builds. Branches are never included in builds - they are for development purposes only.

A file is defined as belonging to a branch by including this directive in the file:

IVBRANCH:Branch Name

Files with branches are shown as follows:

• File 1 (myzip-class.php) - This file only exists in branch 'MyTest'
• File 2 (unzip-class.php) - This file has a 'trunk' version, and a version for the branch 'MyTest'.
• File 3 (myzip-class.php) - This file only has a 'trunk' version.

You can get a whole project branch - see the section on Getting Files above.

Output Macros

You can insert the following macros in your source code, and when the file is OUTPUT (i.e. via File or Project GET/BUILD/CHECKOUT) the macro will be replaced with the appropriate value.

• IVTIME - Time and Date Stamp
• IVVER - File Version
• IVFILE - File Name
• IVPATH - File Path
• IVPROJ - Project Version (Text)
• IVPRJV - Project Version (Code)

The following values relating to macros are defined in settings.php:

• The macro delimiters ($MD_L and $MD_R) are set to '//#' and '#' by default.
• The output macros - i.e. what the text above is replaced by.
• ALWAYS_PROCESS_MACROS - See above.
• TIMESTAMP_FORMAT - The format to use to output the timestamp macro.

Example

In IV, the comment at the top of the file is written thus (this is from settings.php):

// //#IVPATH#
// //#IVFILE#
// //#IVVER#
// //#IVPROJ#
//===============================================================
//#IVPRJV#

When the file is retrieved from IV, the comment is changed to this:

// [ File_Path: iv/ ]
// [ File_Name: settings.php ]
// [ File_Version: 2 ]
// [ Project_Version: 0.1 ]
//===============================================================
$VERSION='0.1';

When the files are updated or checked-in, the macros are reverted back prior to the comparison / update. When you look at the file in IV, they only show the original macro (i.e. //#IVFILE#)

Other Info

File Types

By default, IV will ignore any file extensions it does not recognise. These are defined in the file: ft_array.php. You can to edit the file to add / remove any extensions you need / don't need.

You can get IV to track unknown file types by changing the value of TRACK_UNKNOWN_TYPES in settings.php to TRUE

User Access Levels

There are 5 access levels in the system (defined in userlevel.php):

1. Public - For login / install only
2. User - Get / view files
3. Developer - Add / update projects
4. Admin - Add / update users
5. Test - Empty the DB / Uninstall IV