Using git to manage and upgrade a wiki with modifications to core (hacks)

By <daniel@redwerks.org>

Modifying core is horrible… it’s extremely bad practice and causes trouble for you. That said, people still do it. Especially in contracted scenarios. There are also unfortunately issues with most methods of trying to manage a wiki with modifications that make it difficult to upgrade or restrict your ability to track the changes you make. I’ve seen this scenario a few times. So one of the tricks I came up with once was this.  It’s a way of managing your wiki’s source in git so you can track your modifications and take advantage of git’s merge functionality to upgrade MediaWiki with the least trouble. We start by turning your MediaWiki installation into a clean git repo. This will work even after you’ve installed and made a pile of local hacks. Init an empty git repo in your wiki’s directory (git init .). What you check in is going to vary from wiki to wiki so I won’t go over any specific commands here. But generally you’ll commit everything except your images, LocalSettings, and any caching folders you’re using. Though a good setup will also move the private settings to a different file and commit the non-private LocalSettings into the repo and use it to track changes to settings. This makes for a very good way to deploy things to production from a testing site. Now we move on to the actual trick. The fundamental basis of this trick is to turn a series of tarballs into a git branch allowing us to take advantage of git’s 3-way merging to handle all conflicts on upgrade. So to start we create a new git repo. Download the same version of MediaWiki you started with and extract it into the repo. The idea is basically to create a duplicate environment with the same things in the same spots as your wiki, but with complete vanilla untouched software. So if you didn’t use the extensions versions that come with the tarball or didn’t check the extensions in then you should remove the extensions that come with the tarball. Once you’re done add all the files to git and make your first commit. Now we want to tie this repo into our  real repo as a branch. To do this we want to add the repos you put the tarball into as a remote (you can call it whatever you want vendor, core, mediawiki, tarballs, etc…). Then you want to fetch from the remote and use the ‘ours’ merge strategy to merge the master of that repo into your repo:

$ git remote add {theremote} {path-to-other-repo}
$ git fetch {theremote}
$ git merge -s ours {theremote}/master

Because of the  ‘ours’ merge strategy nothing from the other repo will actually become part of your repo. Instead this will have the effect of simply tying the vanilla data into your repo and asserting that these are supposed to be the same set of code. From now on any merge you make from the tarball repo will do a proper 3-way merge. Basically it will take the last version of mediawiki from the tarball repo you merged and the new version of mediawiki you’re trying to upgrade to and create a delta to apply to your current code instead of simply replacing your code and erasing your hacks. You may occasionally have to do handle a merge conflict, but generally those will only happen in places where you have modified core. Now lets upgrade MediaWiki. Go back to that tarball repo… Delete EVERYTHING. Erase every MediaWiki file there, including the hidden dot (.gitreview, etc…) files. Don’t leave anything behind except for the .git/ directory. Now that the folder is clear download the new version of MediaWiki you want to install and extract it into the repo. Add ALL of the new files, modifications, and deletions to the index and make a commit for the new version of MediaWiki. You can do this by git add-ing all the new files and doing a git commit -a. Now that you’ve added a new version of MediaWiki to the tarball repo you can pull it into your repo to upgrade. Then as usual upgrade the database:

$ git pull {theremote} master
$ php maintenance/upgrade.php

You may have to resolve conflicts when you pull. But when you’re done you will have upgraded your MediaWiki install and won’t have to worry about re-applying any hacks. You can also keep track of the difference between your modified code and the real code using git diff vendor/master master this should help you slowly eliminate these hacks from your code.