I’m planning on officially releasing the rewrite sometime soon – tentatively I’m thinking sometime this month. I’m giving it a last minute stabilization period to eliminate any bugs I’ve come across, and add a couple small and easy features.

Since this isn’t a release changelog, I’m not going to list out the bugfixes – you can always look at the log for that. But there are a few features currently implemented in the master branch that you’ll probably be interested in knowing about:

Javascript

I finally got around to starting to add a couple of the javascript features I’ve always wanted to add. These are the first steps towards the actual next generation of the user interface that I intended to do, after the architectural rewrite. I used the jQuery javascript library – I’ve worked with it before and I’m familiar with it.

I started with the two things that bugged me the most usability wise – so these are primarily supposed to be functional improvements (although admittedly some of the animation effects I used are more for cool looks rather than pure functionality…)

• Commits in the shortlog, project summary, and blame pages now give much more useful info when you mouse over them. Previously they used the browser’s built-in tooltips (using the title attribute) to display the full first line of the commit message. This was clumsy because all formatting was discarded, it can take several seconds for the tooltip to pop up, and it was small and hard to read. Now it uses tooltips from the qTip jquery plugin. The tooltip shows the author, committer, and full commit message. It asynchronously loads in the background with ajax when you first hover over the commit, to avoid increasing the size of the initial page. The tooltip content is defined by a template so it’s customizable, and the content is cached like everything else.
• Blame data can now be loaded asynchronously into the blob page. Previously when you clicked the blame link on a blob page, you got pretty much exactly the same page, but with an extra column of blame data. A lot of this was unnecessary work and time. So now, when you click the blame link, it uses ajax to pull the blame data from the server, and inserts it in the right place right next to the blob, without having to load all the blob content again. This blame data is also cached.

Both these features are running now on the GitPHP instance on this site, if you want to try them out. They are designed to degrade gracefully – so without javascript you’ll get the old style tooltips, and the blame link will take you to the normal blame page. Also, if you don’t want them for your instance at all – you don’t like them, you prefer not using javascript to lighten the footprint of your site, or you’re a grumpy old man – you can turn them off using a config option, and they will degrade the same way for everybody.

Syntax highlighting on the blame page

Previously, the blame page didn’t do any syntax highlighting, due to limitations in the HTML given to me by GeSHi. I found a way around it, so the standard blame page now does syntax highlighting just like the blame page. Note that this only applies if you’re not using the javascript blame feature described above.

New project array format

I’m changing the way projects are defined with categories in the git_project array. The previous method was extremely limited, and only allowed definition of a single piece of metadata – one category – for each project. I have at least one feature in mind that will depend on more metadata than that, so I’m changing to a new project array format. The whole $git_projects definition is being moved to a new file – config/projects.conf.php. This makes the config cleaner, by putting options in one file and projects in another. The new format uses a multidimensional php array in such a way that an arbitrary amount of metadata can be added for a project. Right now there’s no extra data supported yet – just the one category – but this is just in preparation.

Admittedly the new format is a tiny bit harder to set up because it relies on php’s array syntax – so you need to get all the commas and array() calls right. You can look at config/projects.conf.php.example for an example of how it’s supposed to look. I contemplated making a config parser to simplify the format, but since this file gets loaded every time you load any page, I chose to keep the performance hit as light as possible and not try to parse anything.

In order to make upgrading easier, the system still supports the old method. If the projects.conf.php file exists, it will use that to load the new format. If it doesn’t exist, it will fall back to the older method loaded from gitphp.conf.php. So you can keep using the old method, and whenever you’re ready, copy projects.conf.php.example to projects.conf.php and set it up.

Features from Calen Pennington at Wireless Generation

• When using the directory list method of listing projects (no projects defined in the config, to crawl the projectroot for projects), the projects will automatically be categorized by the directory they’re in
• When using the directory list method of listing projects, this method can now respect the magic file git-daemon-export-ok, and only list projects that have that magic file in them. (see the git-daemon man page for details on that file) Whether that exclusion is done is set by a config option, in order to avoid breaking existing installs on upgrade.

Feature from Tejas Dinkar

• Now, in the tree view, a snapshot archive can be generated for any sub-tree (a single subdirectory of your project)

• Yes, I’m still around
• No, I haven’t forgotten that I rewrote gitphp
• Yes, I still plan on releasing the rewrite

I’ve had a really huge increase in the amount of stuff I have to deal with at work these past four months (I have the government to thank for that… if you follow HIT, you’ll know exactly what I’m talking about when I say the words “meaningful use”). It’s been tough for me to get back to my personal development, but I still do intend to get back to it when I can.

The rewrite uses an exception catching system to display error messages to the user. Some of these are intentional – for example, displaying that a search had no results. However, for the moment, I have disabled this exception catch in order to debug actual issues easier – errors will be a lot less friendly but will show a lot more useful debugging info. This exception catch will be re-enabled before release.

As a side effect of the rewrite, a couple small “features” did make it into the rewrite right now:

• The configuration management operates on a merge system now, in that configuration values specified in gitphp.conf.php will be merged over and replace default values. What that means is that now the config file doesn’t have to specify all the config values in order to work properly – it only has to specify the values that you want to change. In fact, you’ll notice that this is now reflected in the example config; the example now only has config values that almost everyone cares about: the projectroot config value (because it’s necessary), the git projects list (because it’s frequently used), and the caching option (because really everyone should be using caching, I just can’t turn it on by default because it requires setting up a cache directory). Every other config option has been moved to the gitphp.conf.defaults.php file, which lists all the config values and their defaults (formerly what the example used to do). The defaults file isn’t usable as a real config; the idea is that if you want to change a config value, you copy it from the defaults file into your gitphp.conf.php file and set it appropriately. This way users can keep the amount of noise in their config files to a minimum. If you have suggestions for other very frequently used config options that are good candidates to put in the example file, let me know.
• Previously, ref tags (the little yellow labels that list heads/tags for a commit) would not distinguish between tags and heads. Now, tags and heads are different colors, and clicking on the little badges will direct you to an appropriate page for that ref (the shortlog for heads, the tag page for tags).
• Turning on debugging outputs a wealth of timing and memory usage information – probably way more than you care about. This output also breaks any non-html output (snapshots, rss, opml, etc). In other words, turn debugging off if you were using it.
• Trees display file sizes by blobs. At the moment they’re not right-aligned though, I need to fix that (Update 2010-03-30: also it requires git 1.5.3 or greater, as I found out the hard way just now when my copy hosted on this website has been crashing on the tree view because dreamhost only runs git 1.4.4.4. A fix was added to make it fallback gracefully on older versions)
• File searching shows the line number by matching lines

I have a variety of ideas that I want to implement. I don’t know how many of these will get in before the next release, but some ideas are:

• Using javascript tooltip bubbles to show more information – for example, mousing over a commit title to get the full commit message in a more readable form than the current method of using the title attribute
• GeSHi syntax highlighting on the blame page
• Loading blame info inline into the blob page using javascript and ajax, rather than going to a separate page
• I18n
• Allowing drilling down into a tree using javascript and ajax without having to navigate to a different tree page

Other suggestions are welcome.

The rest of this post is about the architectural design and decisions of the OOP rewrite. If you don’t care, you can stop reading now.

The idea of the rewrite was to separate the business logic from the UI using a model-view-controller system. I followed this basic methodology:

• Model: a library of objects representing the various pieces of a git repository – project, commit, tree, blob, etc. In directory include/git
• View: the smarty template
• Controller: connector class that reads the parameters for an action, instantiates the proper model objects, and passes them to the template system (smarty). In include/controller

The git data model is pretty self-explanatory. Most objects represent pieces of a git repo you’re familiar with. Any objects representing a hash in the repository inherit from the GitObject class, which is an abstract class representing a hash. The ProjectList* classes represent a list of projects, with ProjectList being the factory and ProjectListBase being the abstract base class that the various projectlist implementations (directory list, gitosis file, categorized array) extend.

Controllers are also pretty straightforward. All controllers inherit from ControllerBase, the base class which does a lot of the generic implementation, such as setup of template variables used in all templates, handling displaying a cached template vs loading the data for rendering, etc. The Controller class itself is the “supercontroller” that maps the action to a given controller class. Controllers can also be flexible and change things based on parameters – for example, shortlog and log now both use the same data objects and therefore use the same controller – just that the controller decides whether to use the shortlog or the log template depending on a parameter.

This is not a 100% pure MVC system – to minimize the amount of processing the controller does, the template has to know some things about how the data objects work. For example, if the template knows how to get the commit message out of a commit object, or get the root tree from a commit object, it doesn’t really make sense to make the controller do the extra work of pulling that out beforehand. Really, this is because for this project I am both the programmer and the template author, so I don’t have to pretend that the template author doesn’t know anything about the data model.

Apoplectic MVC purists can leave now.

That said, if you can get over that, any constructive criticism on any part of the design is welcome. I did take shortcuts in the data model in a couple places, after all.

Performance testing is showing certain actions to be slower and others to be faster. In particular, pages that can make repeated use of a single object (project summary, commit, etc) are showing speedups because of the way objects only load data from the repository on demand and cache it. At the same time, code that makes use of many different objects (for example, all the commit objects used to display all the entries on a log page) are showing slowdowns because it takes php time to create those objects. In the end, it balances out. Of course, caching still makes much of this pretty much moot.

Give the new code a test – play around with using the rewritten code, have a look at the code if you’re programming inclined and offer suggestions. Heck, if you use http://gitphp.xiphux.com you can do both at the same time. Let me know what you think.

First, features:

• Support for specifying a project list file, rather than listing out projects manually in the config file. It was done with Gitosis in mind, but will work with any flat file of projects. Thanks to Jonathan Kolb
• Switch to using GeSHi’s CSS mode to make highlighted blob support more lightweight (less traffic)
• Basic blame support. This is available as a link on any blob page to see the blame view for that file (if there’s somewhere else you would like the link, let me know). This is just the standard git blame algorithm, it doesn’t do any of the more fancy pickaxe stuff such as added/deleted lines. Also, currently blame view does not do any syntax highlighting with GeSHi – it’s actually trickier than it sounds because of the way GeSHi works
• Smarty and GeSHi are now included with GitPHP so you don’t have to install it yourself – more on this below

Bugfixes:

• Fix a bug that prevented filesearch from working, thanks to Christiaan Kortekaas
• Fix a bug that caused RSS to generate an error for a project with a small number of commits, thanks to Zaran
• Fix a security hole that allowed users to access any project using the p= parameter, even if it was not listed in the project list. Thanks to Jonathan Kolb

Just a note that some files have been moved around for organizational purposes (in particular, images, CSS, and documentation was moved into their own directories, rather than having them float around in the root), so if you’re upgrading, I would backup your config, delete your current install, then install the new version and replace your config so you don’t have unused files hanging around.

As always, release is on the GitPHP page, and bugs can be reported on Mantis.

For future releases, I am aiming for making everyone’s lives easier with some significant changes. In case you’re a tl;dr person, I will bold key points.

Ease of setup
Currently, GitPHP is not easy to setup. You have to read through a long list of configuration options to get things set up, and you have to install smarty on your own, as well as (if you choose) GeSHi. One thing I’ve discovered, after developing commercial software for a year and a half, is that users don’t read instructions. Despite the fact that I’ve written up a README and explained how to do everything, I’m willing to bet there’s been at least one user that tried to install GitPHP, gotten an error that Smarty isn’t found, then gave up. There was even a fork by someone at one time to remove Smarty support. While I have nothing against forks (I’ve seen at least two forks of GitPHP), I couldn’t really understand why someone would want to remove support for Smarty other than the fact that they didn’t want to have to install it themselves as a dependency. If it’s completely internal to the project, it shouldn’t matter whether you’re using smarty or any other template engine. Besides, Smarty is what provides the caching framework that GitPHP uses.
Previously, I always excluded Smarty and GeSHi because I wanted to keep the package lightweight and allow users to choose what versions they wanted to use (in keeping with Unix style). But since this has led to so much confusion for people, I am now including Smarty with GitPHP (in a ‘lib/’ directory). The example config now points to this smarty install by default. GeSHi is also included in this lib directory, and the example config points to this copy and enables GeSHi by default. Eventually the config options will be removed from the example config, or at least moved away from the main config options. The config options themselves will probably never go away because it’s useful to be able to point to a shared smarty or geshi instance, but at least they’ll be hidden away from the average user and not be required options.
This is probably the best I can do as far as making Smarty transparent. You still need to set templates_c writable by the server because I can’t control permissions on a directory in a tarball.
I will also be evaluating other configuration options for removal in the future from the example config so you don’t have to read over them if I can provide reasonable defaults. No current options will be removed completely, but like Smarty and GeSHi, they may be hidden away by default. The only config option a user must be required to set up is the project root, because I’m not psychic and I don’t know where you’ve made your projects available.

Ease of maintainability
For the past few years, I’ve hated the GitPHP codebase. GitPHP was written in 2005, back when PHP 4 was still commonplace and PHP 5 was not widely deployed for everyone. So at the time, when I started the project, I wrote it as a very large collection of functions (like a C program), because:

• I wanted it to work on PHP4, which most people (including me) were still using at the time
• I was basing it on Gitweb, which is a single perl file. Perl is not exactly organized, and neither was the Gitweb code. (it still isn’t)
• I was still relatively inexperienced with PHP

However, after five years of changes and tweaking, it’s ended up as a train wreck of spaghetti code. I’ve found myself having to violate the DRY (don’t repeat yourself) principle all over the place just to fix simple bugs, and adding a new feature (blame) was a lot messier than it should have been.
Therefore, I am going to be rewriting all the internal code of GitPHP. Because PHP 5 is widespread now (and PHP 4 is end of life), I can take advantage of PHP 5′s much better (though still not quite perfect) object oriented programming support. This means I can use things inherent to object oriented programming like patterns, code reuse, and loading data by git commands only on demand and caching it in objects to minimize the number of git commands executed.
For people looking at the code (me, and maybe anyone doing a bugfix), this will eventually make your job a lot easier. For users, what this means is that at some point – maybe even as soon as the next release – GitPHP will stop working on PHP 4. I’ve already started, but as a rewrite of pretty much the entire application, it’s going to take quite a while. Depending on how long it takes me, it’s possible that the next release will have a half-half codebase. We’ll see.

Ease of use
The current GitPHP interface is based on Gitweb (obviously). While the gitweb interface works fairly well, there are also places where I’ve found using it to be fairly clumsy.
Also, currently GitPHP uses no javascript for browser compatibility reasons. However, there have been a number of times where I would have liked to use javascript to make life easier for someone using the site. As compatibility between browsers gets better, using javascript in a compatible but also degradable way looks more and more feasible, so I will be looking into ways to make the user interface of GitPHP more flexible in the future – implementing javascript, and partially departing from the Gitweb look. It’s not going to look like a radically different application or anything, but it will probably stop adhering so closely to Gitweb. This is a long term thing though; I probably won’t start this until I’ve at least addressed the other two points, rewriting the core and making the install easier.

Changes:

• Security fix: A user could perform a directory traversal using a crafted relative path (using .. and a null byte) to read an arbitrary file on the server
• Allow display of clone/push urls for projects

Release is on the GitPHP page, and bugs can be reported on Mantis.

Changes:

• PHP 5.3 fixes (avoid assigning object references, switch to perl compatible regular expressions since the posix extended regex functions are deprecated) – patch by Khee Chin
• On the project list, the project description links to the project page like gitweb – patch by Khee Chin
• Packed ref support – based on work by Khee Chin
• Fixed display of non-english UTF-8 characters (they used to appear garbled)
• Disabled smarty’s template compile check in releases for a small performance boost (smarty used to constantly check if a template was modified, something that’s unnecessary in releases put into production and is only useful during development)

Release is on the GitPHP page, and bugs can be reported on Mantis.

Major features:
Caching
By request… GitPHP now makes use of Smarty caching to cache the output of any action – this includes all pages, blobs, diffs, searches, and even snapshots. There are new cache options in the example config, so make sure you copy them into your existing config to turn on caching and choose your desired cache lifetime.
GitPHP will attempt to automatically expire the cache appropriately. When a page is loaded for a project, it will expire any cached pages that are older than the most recent commit to the project, on any head. This ensures that users are always seeing the proper information for the project, and not seeing outdated information due to cached pages that have been hanging around too long. This check is a tiny performance hit, but is trivial compared to the gain of caching. You can turn this off if you want to skip the check, but you should beware that users could be seeing mixes of old and new data depending on what has and hasn’t been cached. You can also turn this off if commits are coming in so quickly that the cache is constantly being expired, but if you’re doing your git workflow properly (occasionally pushing groups of commits from a private to a public repository) this should not be the case.
If you ever run into cache issues, you can go to

http://yourserver.com/gitphp/index.php?a=expire

to forcefully expire everything in the cache. You will also need to do this if you change any config options. This is not linked anywhere from the interface since it’s an administrative action; you have to type it in yourself.

Unified templates
I realized that the way I was handling templates previously was hampering customizability. I had template pieces that got displayed in order… for example, the header template, then the nav template, then the paging prev/next template, then the log template, then the footer template… you get the idea. While each of those templates was customizable, I was still enforcing the order of elements – eg the nav always had to be first, before the content.
Now, each page’s template is a single file that displays everything. This allows full flexibility to customize the template any way you want – anything can now be moved anywhere on the page. (It also made implementing caching easier)
This is a very slight performance degradation compared to previous versions, because there are times where the code will have to loop twice – once to parse data, then another time to output it in the template. However, caching completely eliminates this difference (and then some).

Minor features:

• Debugging can be turned on with a new config option. This is probably not useful for most users. However, this will display the execution time of a given page at the bottom, so it can be useful for checking how much time a particular action on a repository takes – although naturally, this is influenced by the cache

Bugfixes:

• The “performance fix” introduced in version 0.0.6 made use of the –skip parameter for revision lists. This parameter was introduced in git 1.5.0, which means that revision browsing was effectively broken for any version of git lower than that. (It was broken on this site… dreamhost runs git 1.4.4.4). I have now made it backwards compatible; gitphp will use the faster –skip parameter if it detects you are running git 1.5.0 or greater, and transparently fall back to the old method if you are not. I refuse to be like gitweb and require the gitweb and git versions to both be the most current; I’ll always support old versions to the best of my ability, so please report bugs on Mantis if you have any issues with old versions.
• Whitespace is preserved on non-html pages (such as opml and rss) for readability
• The blob page now properly displays ref tags for HEAD
• Pages now properly report their charset to the browser as UTF-8
• Pages do not use the output buffer anymore. It is unnecessary if you are using caching, and avoids issues where the snapshot is larger than the output buffer and gets truncated

Internationalization is not in this release. Technically it is done, but no one showed interest in translating into another language. Abstracted and tokenized strings, without any other languages besides English, are just an unnecessary performance hit. The code still exists in the branch i18n-manual, but I’m not going to merge the feature until there’s a reason to, meaning there’s at least one other language to offer.

As always, the release is on the GitPHP page, and bugs can be reported on Mantis.

There are three small(-ish) changes:

• Readable names in diffs (I changed some of these last release but didn’t get all of them)
• Treeview paths now have clickable links for each folder, so you can jump to any parent directory easily
• Ref icons appear in more places by commit titles

I wouldn’t normally do a release this small, but I’m planning on making some major changes to the way templates work (internally, not really much difference visible to users), which is a change that could potentially take a while, so I wanted to get these fixes out and released before I started anything.

As always, packages are available from the GitPHP page, and bugs can be reported by Mantis.