vb.org Archive - Araxis Merge Full Tutorial for Vbulletin

Overview

What is Araxis Merge?

Merge is the visual file comparison (diff), merging and folder synchronization application from Araxis. Use it to compare and merge source code, web pages and other text files with native application performance. Compare images and binary files. Synchronize folders. Perform code reviews and audits. Work with source hierarchies containing thousands of files.

Where to download it?

Araxis Merge Download

Which version should I use? Professional Version

Vbulletin and Araxis

Araxis Professional will allow you to easily upgrade your vbulletin boards and provides extensive comparison scanning for up to 3 versions. In addition, you can merge code directly from one version into the next or copy files over from folder to folder. You have the ability to create reports so you can keep track of version changes. In addition, you can perform advance filtering to limit the types of folders/files to compare.

This tutorial is meant to be an informative approach to using Araxis and how to fully upgrade your board from start to finish.

Preparing Your Vbulletin versions

When using araxis you should always work with 3 versions. The three versions you should use are:

Current hacked version
Current clean version
New upgrade version

(i.e. using 3.6.0 and upgrading to 3.6.7 we would have the following)

3.6.0 hacked version (our current website active version)
3.6.0 clean version
3.6.7 upgrade version

Why have 3 versions?

Your current hacked version may contain modifications to files such as index.php, includes/functions.php, global.php etc. that you modified at some time. You would want your modified code to be incorporated into the newest version you are upgrading to so that your upgrade goes smoothly and without any hitches.

By having 3 versions, we are able to cross compare in two ways. We can cross-compare our hacked current version with the clean current version to isolate which files may have been modified, creating a list of these modified files. We can then take the list of files that were modified and compare them to the latest new upgrade version and merge the code into the newest version.

Creating a Comparison Folder

On your local hard drive, create a blank directory called "Comparison".
In it, place a 'copy' of your complete 'forum' (hacked version) and rename it to "Hacked".
In it, place a 'copy' of the 'upgrade' folder from your (clean version) and rename it to "Current".
In it, place a 'copy' of the 'upgrade' folder from your (latest version) and rename it to "New".

Your folder structures should appear as follows:

Comparison
---Hacked
------..contents of your current hacked forum (i.e. 3.6.0 - hacked)
---Current
------..contents of your current clean version (i.e. 3.6.0 - clean)
---New
------..contents of the newest version you are upgrading to (i.e. 3.6.7 - new)

Using Araxis Merge

Open araxis merge.
Push "CTRL + D" to open a new folder comparison.
In the 'menu bar' press the "Three-Way Comparison (Vertical)" button.
In the far left frame browse to your "New" folder and open.
In the middle frame browse to your "Current" folder and open.
In the far right frame browse to your "Hacked" folder and open.
In the 'menu bar' press the "Start/Recompare" button or press "F5".
Allow a moment for the folders to be compared.

At first glance you may be thinking, "wow this view is huge and extensive - where can I possibly begin?". First, you have a very long list of files here and some of it you really don't need to be comparing. In addition, some changes may just include headers and footers which really don't need to be compared as these will change per version anyways. So, what can we do to clean some of this up?

Filtering

Filtering allows you to include/exclude files and folders that you want to compare versus having everything right in front of you. How we design our filters is really up to you but in this case, I'm going to show you how to just view .php and .xml file comparisons.

Remember, when working with araxis filtering, the patterns you create work from "top to bottom". This is very important when knowing how to include/exclude files. Let's take a look at how to accomplish this:

..While in araxis..
From the 'file menu', click "View -> Options".
Under 'Folder Comparisons' highlight "Filters".

Let's create a new filter.

Click "New".
In the name box type "php-xml" and click OK.

We now have a "php-xml" filter. Let's add some patterns to our filter.

Under the 'patterns' box click "New". An "Enter New Pattern" box appears.
Change the 'Type' to "Exclude".
Change the 'Matches' to "Files".
Change the 'Pattern' to "*".
Click OK.

We now have a php-xml filter with two patterns. Let's create one more pattern.

Under the 'patterns' box click "New". An "Enter New Pattern" box appears.
Change the 'Type' to "Include".
Change the 'Matches' to "Files".
Change the 'Pattern' to "*.php;*.xml".
Click OK.

We now have a php-xml filter with three patterns. Let's review what it does.

The first pattern..
Type (Include) Matches (Files and Folders) and Pattern (*) simply includes all of the files and folders being compared. It then moves on to the second pattern.

The second pattern..
Type (Exclude) Matches (Files) and Pattern (*) states to exclude all files being compared and moves to the third pattern.

The third pattern acts as an exception..
Type (Include) Matches (Files) and Pattern (*.php;*.xml) states to include all files that end with the extension *.php and *.xml.

So, in coding lingo we are basically stating

Include all files AND folders for initial comparison BUT exclude all files with the EXCEPTION of those that have the extension .php or .xml.

Since Araxis works top to bottom, the sequence is very important. If you are interested in understanding more about how to work with filters, read the help section while in araxis and perform a search on "filters".

Click "Apply" and then OK. We now have our .php filter created and can start to use it. Let's press "F5" and do a quick recompare now that the filter is active. Notice that things look much nicer now? We are only viewing .php and .xml files now instead of all of the other file types. This makes life a little easier especially on a short upgrade where only a few files or few sections have been updated. In addition, you can create filters to include/exclude sections as well so this is a nice rule to implement when using araxis.

So, now we have a view that shows all of the PHP and XML files for all 3 versions. Next to the files, if there are changes, there are numbers next to them stating how many different changes there are. However, notice now that we still have many files listed here from our middle clean version with approximately 2 changes. If you view the comparisons you will notice that most of these are just header and footer comments that include the || by them. How do we get rid of these in our comparisons?

Expressions

Expressions give you the ability to filter out unwanted code from your files when performing comparisons. This section may seem complicated but I've included the code to use to remove the comparison changes for header/footer commenting and also to remove changes to $upgrade_phrases. Let's start with creating a couple of new expressions.

From the 'menu bar' click on "view" -> "options".
Under 'Text Comparisons' highlight "Expressions".
Double click one of the empty expression lines.

A new box appears.

In the Description box place "Remove commenting in headers and footers"
In the Expression box place:

Code:

^[ \t]*\|\|.*$

For all expressions we are using "Force a line unchanged if it matches any part of the expression" as the expression exclusion. Make sure that all expressions in this tutorial utilize this.

Now just click OK and then Apply and OK again. You just created your first expression. So what does this do exactly? I'll break it down for you.

Code:

^ (matches the beginning of a new line)

[ \t]* (matches zero or more space or tab characters

\| (matches the literal symbol for | )

\| (matches the literal symbol for | )

.* (matches zero or more occurrences of any character)

$ (matches the end of the line)

So what it basically is doing is finding any comments that have || in front of them, which includes all of the comments for the headers and the footers in many of the php files and excluding them from the list of changes.

Let's add one more expression.

From the 'menu bar' click on "view" -> "options".
Under 'Text Comparisons' highlight "Expressions".
Double click one of the empty expression lines.

A new box appears.

In the Description box place "Remove $upgrade_phrases"
In the Expression box place:

Code:

^[ \t]*\$upgrade_phrases.*$

So what this expression does is searches for anything with $upgrade_phrases in the line and excludes them from the list of changes. You could also do multiple $variable types for common placed items but you can find out more about this by reading the araxis help file on expressions.

So, now that we have our two expressions completed, let's put them to use.

Place a check mark in the two new expressions we created and also browse up to the one created for blank lines and check mark that one as well.

Click Apply and OK.
Click "F5" to recompare.

Final Cleanup

Now you will notice that a lot less is cluttering up our screen. Let's work on clearing up some more clutter with a few simple selections.

From the 'Menu Bar' select View -> "Hide Empty Folders".
From the 'Menu Bar' select View -> "Hide Unchanged Rows".
Now then, minimize anything that is "extra" in the comparison windows

Note: By anything extra, I mean folders or files that you may have added that would not normally be in a vbulletin upgrade. An example of this would be some type of external PHP package that you added to your forum directory that wasn't included with your version.

Review

Time for a review to see where we are at. While most of what I just taught you how to do are really "one time" items, you should definitely look into what Araxis can do for you and browse the help files on questions you might have.

We first created a comparison folder and structured it to include the three versions we want to work with. We opened Araxis and browsed for the three files and ran a comparison check. We further isolated code by utilizing filters to filter out the file types we wanted to compare so that we only viewed php and xml file types. In addition, we created expressions to exclude changes for comments in headers and footers and also for any vbulletin upgrade phrases. We then performed some final tasks and now we have a much easier comparison to work with.

Sound about right?

Comparing Code and Tracking Changes

So, we're ready to work with merges? Well, almost but not quite. Let's talk about how the change features work with Araxis. One thing you'll notice is that to the right of each of the versions there is a change column that gives you the number of changes compared to a different version. These are compared from "right to left". This means that our "new" version is showing the changes that are different from our "clean" version and that the "clean" version is showing the number of changes that are different from our "hacked" version. Make sense?

So, what this means is if you want to see what code your hacked version really contains that should be looked at, you want to compare the files that have changes next to them in the clean version. If you see for instance:

index.php (23) | index.php (1) | index.php

This means that both the index.php files from the "new" and "clean" versions together combined have 23 changes and that the index.php files from "clean" and "hacked" have 1 change combined.

So, if you open the index.php file you will want to look for the changes in your hacked file first to see if anything has been changed. In this case, you might notice that a blue snippet of code shows up in your hacked file and it happens to be a minor modification you made about a year and a half ago that you forgot.

When you spot this, you should keep track of your hacked version file and keep a list for future reference. In addition, you might want to make some notes as to what the change is and what it affects so that in the future, you will know if it's going to be affected with an upgrade or if it might need some revising.

Continue down until you find all hacked files that contain code that is modified that will need to be included in your upgrade version, noting and tracking changes for future reference. Remember, if you do it now, you won't have to track it again later on.

Merging Code

Now that we've done that, we're ready to merge our code. Araxis Pro does this for you with a couple of easy clicks. But, before we do this, I'm going to teach you one way of doing this that I prefer. Remember, if you don't like doing it this way you don't have to. However, if you've followed me this far, you might as well go the whole way through. :)

There are two approaches to doing this: Novice and Advanced

The Advanced way is to work with all three files open. The novice way is to close all 3 files and just open the hacked version and the new version. I will teach the "novice" way.

Novice:

Close all of your comparison folders.
Click "CTRL+D" to start a folder comparison.
Push the Two-Way Comparison (Vertical) button.
Browse your folders so that the "New" version is on the far left.
Browse your folders so that the "Hacked" version is on the far right.
Browse to each file you tracked and made a note of and double click the file to open a file comparison.
Depending on where the code needs to go, use "Shift+Click" on the far arrows to the right in your "Hacked" file to move the code "before" the entry mark in the "New" file, or use "CTRL+Click" on the far arrows to the right in your "Hacked" file to move the code "after" the entry mark in the "New" file.
Click the "X" close box at the upper right hand corner "just below" the Araxis "X" close box. Remember that the lower X closes an active file or window inside the application and the top most X closes the application.
When you do this, you will be prompted to save the file and there will be a check mark in the file that you just changed. Click YES to save.

Rinse and repeat for the other files you tracked changes/modifications for using the same steps outlined above.

Finalizing Your Upgrade

Now, once finished modifying your files, upload your new version and run the "upgrade" script to finalize the settings. The upgrade script is dependant on the version you are using.

Summary

So, let's summarize the steps we have taken in this tutorial for better clarity.

Configure your Comparison Folder
Copy the New, Clean, and Hacked versions of your forums into the folder
Setup any file filters you want to use to minimize comparison checks
Setup any expressions you want to use to minimize code changes
Finalize views
Run your compare
Compare changes between your hacked and clean versions
Track the changes by writing them down somewhere for future reference
Merge changes into your new version
Upload your new version
Run the upgrade script

I hope that you find this tutorial both friendly and informative because that's why I wrote it. If you have any questions or comments/suggestions please reply to the article and I'll do my best to answer them.

Take care,

X vBulletin 3.8.12 by vBS Debug Information
Page Generation 0.01216 seconds Memory Usage 1,806KB Queries Executed 10 (?)
More Information
Template Usage: (1)ad_footer_end (1)ad_footer_start (1)ad_header_end (1)ad_header_logo (1)ad_navbar_below (3)bbcode_code_printable (1)footer (1)gobutton (1)header (1)headinclude (6)option (1)post_thanks_navbar_search (1)printthread (3)printthreadbit (1)spacer_close (1)spacer_open Phrase Groups Available: global postbit showthread	Included Files: ./printthread.php ./global.php ./includes/init.php ./includes/class_core.php ./includes/config.php ./includes/functions.php ./includes/class_hook.php ./includes/modsystem_functions.php ./includes/class_bbcode_alt.php ./includes/class_bbcode.php ./includes/functions_bigthree.php Hooks Called: init_startup init_startup_session_setup_start init_startup_session_setup_complete cache_permissions fetch_threadinfo_query fetch_threadinfo fetch_foruminfo style_fetch cache_templates global_start parse_templates global_setup_complete printthread_start bbcode_fetch_tags bbcode_create bbcode_parse_start bbcode_parse_complete_precache bbcode_parse_complete printthread_post printthread_complete
Messages: