3.11.4. Migrating from a Tarball
********************************

The procedure to migrate to Git is as follows. The idea is to switch
without changing the version of Bugzilla you are using, to minimise
the risk of conflict or problems. Any upgrade can then happen as a
separate step.


3.11.4.1. Download Code from Git
================================

First, you need to find what version of Bugzilla you are using. It
should be in the top right corner of the front page but, if not, open
the file "Bugzilla/Constants.pm" in your Bugzilla directory and search
for "BUGZILLA_VERSION".

Then, you need to download an additional copy of your *current*
version of Bugzilla from the git repository, and place it in a
separate directory alongside your existing Bugzilla installation
(which we will assume is in a directory called "bugzilla").

To do this, you will need a copy of the **git** program. All Linux
distributions have it; search your package manager for "git". On
Windows or Mac OS X, you can download the official build.

Once git is installed, run these commands to pull a copy of Bugzilla:

**git clone https://github.com/bugzilla/bugzilla bugzilla-new**

**cd bugzilla-new**

**git checkout release-$VERSION**

Replace $VERSION with the three-digit version number of your current
Bugzilla, e.g. "4.2.2". (If the the final digit would have been a 0,
omit it - so use "4.4" for the first release in the 4.4 series.)

You will get a message about a 'detached HEAD'. Don't worry; your head
is still firmly attached to your shoulders.


3.11.4.2. Save Any Local Customizations
=======================================

Go into your original Bugzilla directory and run this command:

**diff -ru -x data -x lib -x docs -x .git -x CVS -x .cvsignore -x .bzr
-x .bzrignore -x .bzrrev ../bugzilla-new . > ../patch.diff**

If you have made customizations to your Bugzilla, and you made them by
changing the Bugzilla code itself (rather than using the Extension
system), then "patch.diff" will have significant content. You will
want to keep a copy of those changes by keeping a copy of this file
and any files referenced in it by "Only in" lines. If the file has
zero size or only insignificant content, you haven't made any local
customizations of this sort.


3.11.4.3. Shut Down Bugzilla
============================

At this point, you should shut down Bugzilla to make sure nothing
changes while you make the switch. Go into the administrative
interface and put an appropriate message into the shutdownhtml
parameter, which is in the "General" section of the administration
parameters. As the name implies, HTML is allowed.

This would be a good time to make Backups. We shouldn't be affecting
the database, but you can't be too careful.


3.11.4.4. Copy Across Data and Modules
======================================

Copy the contents of the following directories from your current
installation of Bugzilla into the corresponding directory in
"bugzilla-new/":

   lib/
   data/
   template/en/custom (may or may not exist)

You also need to copy any extensions you have written or installed,
which are in the "extensions/" directory. Copy across any
subdirectories which do not exist in your new install.

Lastly, copy the following file from your current installation of
Bugzilla into the corresponding place in "bugzilla-new/":

   localconfig

This file contains your database password and access details. Because
your two versions of Bugzilla are the same, this should all work fine.


3.11.4.5. Reapply Local Customizations
======================================

If your "patch.diff" file was zero sized, you can jump to the next
step. Otherwise, you have to apply the patch to your new installation.
If you are on Windows and you don’t have the **patch** program, you
can download it from GNUWin. Once downloaded, you must copy patch.exe
into the Windows directory.

Copy "patch.diff" into the "bugzilla-new" directory and then do:

**patch -p0 --dry-run < patch.diff**

The patch should apply cleanly because you have exactly the same
version of Bugzilla in both directories. If it does, remove the
**--dry-run** and rerun the command to apply it for real. If it does
not apply cleanly, it is likely that you have managed to get a
Bugzilla version mismatch between the two directories.


3.11.4.6. Swap The New Version In
=================================

Now we swap the directories over, and run checksetup.pl to confirm
that all is well. From the directory containing the "bugzilla" and
"bugzilla-new" directories, run:

**mv bugzilla bugzilla-old**

**mv bugzilla-new bugzilla**

**cd bugzilla**

**./checksetup.pl**

Running "checksetup.pl" should not result in any changes to your
database at the end of the run. If it does, then it's most likely that
the two versions of Bugzilla you have are not, in fact, the same.


3.11.4.7. Re-enable Bugzilla
============================

Go into the administrative interface and clear the contents of the
shutdownhtml parameter.


3.11.4.8. Test Bugzilla
=======================

Use your Bugzilla for several days to check that the switch has had no
detrimental effects. Then, if necessary, follow the instructions in
Upgrading with Git to upgrade to the latest version of Bugzilla.


3.11.4.9. Rolling Back
======================

If something goes wrong at any stage of the switching process (e.g.
your patch doesn't apply, or checksetup doesn't complete), you can
always just switch the directories back (if you've got that far) and
re-enable Bugzilla (if you disabled it) and then seek help. Even if
you have re-enabled Bugzilla, and find a problem a little while down
the road, you are still using the same version so there would be few
side effects to switching the directories back a day or three later.

======================================================================

This documentation undoubtedly has bugs; if you find some, please file
them here.
