So after a recent minor bug I got mailed a new report.xml file … and now have to sift through the changes manually, or do I?
I realized that had I had an “upstream” git repository from which the changes came, I would simply have been able to “merge” this into my existing reports. And then came the idea … and then the simplification
The list of companies on the Quasar server is stored in /opt/quasar/data/companies, for each company there exists a .xml file. An extract of this file looks as follows:
Ultimate Linux Solutions CC ...removed... 2008-06-01 PostgreSQL ...removed... valid
Piet Ackermann pointed out the dataDir tag for me. This allows us to have a separate datadir for each company (well, I would probably create a separate datadir for each company and just symlink most of the folders straight back into the original data folder. With one exception, and that’s the reports folder. Now, for the above example, let’s assume we want to change the dataDir to /opt/quasar/ULS instead of the default /opt/quasar/data, so off we go:
cd /opt/quasar mkdir ULS cd ULS for i in ../data/*; do ln -s $i .; done rm reports
Note that I rm the reports symlink again. So now to get our “clean” copies into git (this assumes you haven’t already made modifications to reports, if you have, make backup copies and restore the clean, unmodified reports):
cd /opt/quasar/data/reports git init git add *.xml git commit -m "prestine reports from 2.1.5"
Note that 2.1.5 is an example, it can be any older version, also, this is a log message, it can be anything. Once these are in git, we can proceed to clone them for modification purposes (can be done for as many companies as you desire):
cd /opt/quasar/ULS git clone ../data/reports reports
This will create a reports folder inside /opt/quasar/ULS and copy everything from the “upstream” (/opt/quasar/data/reports) into it, along with some meta information stored in a hidden .git folder.
You can now edit your reports here. (or in the case of old reports, copy them in here). There are a few very basic operations now.
When updating reports, you should add them into the “slave” or “downstream” repository, and commit them. For example:
vi quote_print.xml git add quote_print.xml git commit -m "Added my logo"
This has the advantage of keeping a history. You can view the history using “git log”, it’s quite detailed.
After upgrading quasar new reports will overwrite those in /opt/quasar/data/reports, this isn’t a problem, in fact, it’s what we want, we now want to pull this into our little git system:
cd /opt/quasar/data/reports git add . git commit -m "Upgrade to version 2.1.6"
That’s it on the upstream side, and now to update the ULS reports:
cd /opt/quasar/ULS/reports git pull
This will (usually) perform a clean import of the changes Linux Canada has made to the upstream reports into yours. If it doesn’t, git will inform you that a conflict has occurred. So let’s say for example we changed the same line that Linux Canada changed, then git will complain that it can’t auto-merge quote_print.xml. This is known as a conflict. Simply open the conflicting file in a text editor, look for the >>>>>> ====== <<<<<< conflict markers, edit as you see fit (you need to leave the file without any markers, as you would have wanted it to look after the merge). Now you need to "git add" the conflicting file, eg "git add quote_print.xml" and then you can commit the merge with "git commit".
A controved example follows, let's say in the original version Linux Canada had a file (called file) with one line it "this file has one line in it". Now this was committed in the repository at /opt/quasar/data/reports, at this point we cloned it, and changed the line to "customize". We also did a "git add file" and "git commit -m 'customization'". Now Linux Canada releases a new version of quasar, you go through the process above, and when you execute the "git pull" git spits this at you:
remote: Counting objects: 5, done. remote: Total 3 (delta 0), reused 0 (delta 0) Unpacking objects: 100% (3/3), done. From /home/jkroon/tmp/a b6e12ff..457d983 master -> origin/master Auto-merging file CONFLICT (content): Merge conflict in file Automatic merge failed; fix conflicts and then commit the result.
As you can see, it says big and loud CONFLICT. It also says Merge config in file (which shows I’ve chosen my filename really badly). Opening the file in a text editor shows this:
<<<<<<>>>>>> 457d983d0405dac4617a6ca5f42299e491ce8a4c
We decide we want to keep our version, so we delete the <<<>>> lines. Now we can either use the git shorthand for “git add .” and “git commit” and simply do “git commit -a”. This will bring up a text editor with Merge branch ‘master’ of /opt/quasar/data/reports, indicating the Conflicts. You should probably add some text indicating what the cause of the conflicts was and how it was resolved. When you save and quit git will do what’s required.
It’s also possible to do this whole thing using branches, and it’s a shorter process, but there are more pitfalls. So I’ll run over it very quickly.
Do not bother making copies. What I’ve done just now is this. I’ve copied everything in /opt/quasar/data/reports to ~/quasar/reports/ in order to ensure that I’ve got backup copies. I then re-installed the same version of quasar to get fresh copies of the Linux Canada reports. Now comes the tricky part:
cd /opt/quasar/data/reports git init git add . git commit -m "reports from 2.1.4"
So far so good. Now we “branch” this and re-import the backed up reports:
git checkout -b uls cp ~/quasar/reports/* . git add . git commit -m "existing customizations"
All done. Now comes the careful bit though (and there are ways around this, so if you forget, know that git is ultra powerful and can save you). Before you update you should switch back to the master branch:
git checkout master
Once you’re done updating quasar, you can go back to your own branch:
git checkout uls
And now you can merge the updated reports:
git merge master
Resolve conflicts as per above.
Whichever way you choose, it is a good idea to familiarize yourself with git. I can highly recommend the book at progit.org, it’s very informative, but deals with git from a programmers perspective. The main points from my side:
* Always make sure you don’t leave uncommitted changes around, especially not before an update (git status).
* Use sensible changelog entries. Trust me.
Other advantages of this for me is that I get a revision history of what I changed and when (and depending on the details of your changelog, why). I can imagine that consultants like Piet will find this extremely useful for managing reports for multiple “hosted” clients.
