|
Araxis Merge Full Tutorial for Vbulletin
by
22 May 2007
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? https://www.araxis.com/2003/merge/download.uri 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:
(i.e. using 3.6.0 and upgrading to 3.6.7 we would have the following)
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
Your folder structures should appear as follows: ComparisonUsing Araxis Merge
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:
Let's create a new filter.
We now have a "php-xml" filter. Let's add some patterns to our filter.
We now have a php-xml filter with two patterns. Let's create one more pattern.
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.
A new box appears.
Code:
^[ \t]*\|\|.*$ 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) Let's add one more expression.
A new box appears.
Code:
^[ \t]*\$upgrade_phrases.*$ 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.
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.
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:
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.
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, |