Git

By Martin Erich Hieden, HIEDEN Software GmbH

This article shows how to set up a proper development environment for a PHP project on IBM i using Git for version control. This information is offered “as is”.

Premise

At Hieden Software, weíve been developing a PHP application meant to run on IBM i, so IBM i is where we host and test our code. At first we installed Git on our Windows PCs, accessing our IBM iĖhosted PHP scripts using mapped drives, but the mapped drives were too slow. To gain the speed we needed, I installed Git directly on the Ďií. Now our IBM i hosts both Git and the PHP scripts it manages, providing not only efficiency, but a demonstration of the versatility of IBM i.

Requirements

  • Zend Server (and all of its prereqs)
  • IBM Tools for Developers for i5/OS (5799PTL Ė as of V6R1)
  • Zend Studio 9
  • Git (we used v1.7.9.4)

Overview

Throughout this article “andi” and “zeev” will be used as user names while “<project>” is, yes you guessed right, the actual project name. “ibmi” is used in a few places as the system name. All in all it should be rather self-explanatory.

Basically I’m going to show you how to install and/or configure:

  1. Git on IBM i
  2. Git in ZendStudio
  3. Git on PC
  4. Gitweb on IBM i

The following picture shows what parts are installed where and how they interact. The detailed description on the installation and configuration process follows thereafter.

Figure 1 - Structural overview

The blog post A successful Git branching model by Vincent Driessen describes the workflow I wanted to utilize on my project perfectly, so I wonít discuss it any further in this article.

Git on IBM i

Installing Git

Thanks to Michael Perzlís fantastic site ( perzl.org), IBM i binaries of many OpenSource projects are available. Though, prior to installing Git you need to prepare your system according to Open Source Binaries (you donít need to install any packages using wwwinstall.sh Ė this script points to the old IBM binaries).

Once youíve prepared your system according to the wikiís instructions, run wwwinstallgit.sh (also copied to /QOpenSys/download) in a PASE shell (CALL QP2TERM) to install git and all its prereqs. Using --all as the sole argument will do the trick. To see the complete syntax, call this script without any arguments. You have to additionally add a symbolic link since IBM i is missing one file, which is stored under an different name:

$ ln -s ../../QIBM/ProdData/OS400/PASE/lib/libc.a /QOpenSys/usr/lib/libbind.a

Next, configure Git (this has to be done by every user, who wants to use Git directly on IBM i):

$ git config --global user.name "Andi Suraski"
$ git config --global user.email "andi.suraski@example.com"
$ git config --global merge.ff false

Creating the Repositories

Congratulations! Now you should be ready to use Git on your system. The next few steps are fairly straightforward, assuming you are already comfortable with Git. If not, thereís a fantastic book by Scott Chacon out there which you can also get as pdf for free: ProGit

$ cd /www/zendsvr/htdocs/demo/<project>
$ git init

Now refer to chapter 3.2.4 in ProGit to see how to edit .gitignore file to meet your needs. Once you have done that, youíre ready to create your basic repository:

$ git add *
$ git commit -m "Initial repository commit"
$ git branch develop
$ git checkout develop
$ git tag -a v1.0 -m "<project> v1.0"

Now youíve got the basic repository and are able to share it with your co-workers. So itís time to setup the central (bare) repository.

$ mkdir /git
$ git clone --bare /www/zendsvr/htdocs/demo/<project> /git/<project>.git

Git in Zend Studio

The following needs to be done on every developer PC. The pictures and commands suppose the user is named andi.

Starting SSH on IBM

If SSH is not yet started, start it now. On i/OS V6R1 and higher, run the command STRTCPSVR SERVER(*SSHD). For V5R4, see the instructions at SSHSetup.

Configuring the Remote Project

First we need to create a Project in ZendStudio. You can easily do this with “New -> PHP Project from Git” (a restart may be needed to install missing features). The next steps are shown on the screenshots:

Figure 2 - Creating the Project (1)

Figure 3 - Creating the Project (2)

On the next page select which code libraries you want to utilize in your Git project You may skip this step and do it later, since itís not required for Git setup.

When Zend Studio has finished importing the Git repository and setting up the project, itís time for you to open the “Git Repository Exploring Perspective”. Customize the view using “Window -> Show View” if you desire. Iím using all of the Git views more or less frequently.

Figure 4 - Git Repository Exploring Perspective

In my case the local master branch was not created automatically. You can do that yourself by right-clicking the original/master branch and selecting “Create Branch...”. Since you create it from a remote branch you should choose merge as pull strategy, so you will get a tracking branch, which simplifies the process of fetching and merging new commits from the central repository.

Figure 5 - Create Branch

By default git push is configured completely wrong in ZendStudio. To correct this, go to “<project> -> Remotes -> Original” and right click “(Push) ssh://andi@ibmi/git/<project>.git” and choose “Configure Push...” Under “Ref mapping” choose “Advanced” to get the “Edit (Advanced)...” button and use the following dialog to change your settings in this way (the develop branch should be added too).

Figure 6 - Push Ref Specifications

Now you have properly set up the Project on your PC, but you still need to store this application on your IBM i. In PASE shell (CALL QP2TERM) you should prepare your HTTP server:

$ cd /www/zendsvr/htdocs
$ mkdir andi
$ cd andi
$ mkdir <project>

After that you can configure your Zend Studio project to upload the files to your IBM i. In the “PHP Explorer” View you should right-click your project and then select “Properties...”.

Figure 7 - Remote Server Support

To specify the Remote Connection, if you have not done it yet, choose “Manage”.

Figure 8 - Remote Connection Profile

Finish the connection setup and press Ok and your project will be uploaded to your IBM i. Now youíve done most of the work. You only need to setup standalone Git on your PC.

Standalone Git

Git can be obtained from Git - Fast Version Control System. The installation process is fairly easy, so I wonít cover it here. Whatís more interesting is that, by default, Zend Studio and standalone Git will use the same configuration file, so you donít need to configure anything since you already did that in ZendStudio.

Of more interest is the question why do I need Git installed as standalone too, rather than relying on the Git support in Zend Studio? EGit/JGit, the version of Git used by Eclipse, has two problems as of Zend Studio 9.0.4. First, it will ignore the configuration directive merge.ff which causes my merged branches to be not as distinguishable as Iíd like. Second, I need to know whether the files changed between two commits. Not what exactly changed, just the files names. With Git this is easily doable using “git diff Ėname-only”. I havenít found a way doing the same within Zend Studio. If you know of one, please let me know.

As I found out since first writing this article, you can easily update Git in ZendStudio without upgrading to a newer ZendStudio version (thanks Alan). So you can (and I already did) update EGit to version 2.3.1 - which recognizes the merge.ff directive - without having to buy new ZendStudio 10 licences. If there’s interest I can show how to do this as well.

Gitweb

Setting up Gitweb is not necessary but itís a good way to see what exactly is in your central Git repository. But be aware, itís rather cumbersome to get running.

Because you ran the wwwinstallgit script earlier, your system contains most of the files needed for Gitweb, but the files must be copied to new locations. In /var/www/git you find the files you need. It doesnít matter where you place them as long as your HTTP server finds them, with one exception: gitweb.cgi MUST be placed somewhere under /QOpenSys. Otherwise it wonít be recognized as an executable script.

$ mkdir /www/zendsvr/htdocs/gitweb
$ cd /var/www/git
$ cp git-favicon.png /www/zendsvr/htdocs/gitweb
$ cp git-logo.png /www/zendsvr/htdocs/gitweb
$ cp gitweb.css /www/zendsvr/htdocs/gitweb
$ cp gitweb.js /www/zendsvr/htdocs/gitweb
$ chown -R qtmhhttp /www/zendsvr/htdocs/gitweb
$ chmod -R 770 /www/zendsvr/htdocs/gitweb

$ mkdir /QOpenSys/cgi-bin
$ cp gitweb.cgi /QOpenSys/cgi-bin
$ chown -R qtmhhttp /QOpenSys/cgi-bin
$ chmod -R 755 /QOpenSys/cgi-bin
$ chown qtmhhtp1 /git

Now you need to make a change to /QOpenSys/cgi-bin/gitweb.cgi in order to get it working on IBM i. Otherwise you will only see EBCDIC characters.

+ print "Content-Type: text/html;\r\n\r\n";

Now you should create the config file in /etc/gitweb.conf with the following content:

# This is the directory where your git repositories live
$projectroot = '/git';

# file with project list; by default, simply scan the projectroot dir.
$projects_list = $projectroot;

# This is used to generate the URI for each repo
$my_uri = "/gitweb/gitweb.cgi";

# Text and URI for the home link
$home_link_str = "HIEDEN Software GmbH - Projects";
$home_link = "/gitweb/gitweb.cgi";

# This is the title of the site
$site_name = "HIEDEN Software GmbH - Git";

# These tell gitweb the URIs for the images and css it needs.
# Depending on the version of GitWeb you have there may be
# different locations. Newer versions include a /static/ path
# element and a javascript library.
$stylesheet = "/gitweb/gitweb.css";
$logo = "/gitweb/git-logo.png";
$favicon = "/gitweb/git-favicon.png";
$javascript = "/gitweb/gitweb.js";

# This just makes the description field wider so you can read 
# it better
$projects_list_description_width = 50;

# directory to use for temp files
$git_temp = "/tmp";

# html text to include at home page
$home_text = "indextext.html";

You have to make sure itís accessible by the CGI user:

$ chown qtmhhtp1 /etc/gitweb.conf
$ chmod 755 /etc/gitweb.conf

What is left is to tell your HTTP server how to access gitweb. Add the following directives in /www/zendsvr/conf/httpd.conf or whatever Apache instance you use for PHP.

RedirectMatch permanent ^/gitweb/?$ /gitweb/gitweb.cgi
ScriptAliasMatch ^/gitweb/gitweb\.cgi.*$ /QSYS.LIB/GIT.LIB/GITCGICL.PGM
<Location /gitweb>
    Order Allow,Deny
    Allow from 127.0.0.0/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16

    SetEnv  GITWEB_CONFIG  /etc/gitweb.conf

    DefaultNetCCSID 819
    # Replace the 1141 CCSID value with the appropriate one for your system.
    # See a list here: http://www-01.ibm.com/software/globalization/ccsid/ccsid_registered.html   
    CGIJobCCSID 1141
    CGIConvMode %%EBCDIC/EBCDIC%%
</Location>

Why am I using a new CL program as ScriptAlias? Well, I havenít found a way (and I took ages to look for one) to properly pass the parameters to the perl-script without the wrapper program GIT/QCLSRC(GITCGICL).

/*   CGI-Wrapper for gitweb                                                   */
             PGM

             CALL       PGM(QP2SHELL) +
                          PARM('/QOpenSys/cgi-bin/gitweb.cgi')

             ENDPGM

Compile the CL program, restart your Apache instance, and you should be able to take a look at your central repository with your browser at http://ibmi/gitweb

Known Problems

The CGI wrapper for Gitweb does work but it requires a lot of steps.. Sorry for that, but as I mentioned earlier, I couldnít come up with a better one and therefore would welcome suggestions to simplify the process. I was glad that I did find at least a working one.

Conclusion

You managed to install and setup an up to date version control system on your IBM i. No more need for documenting each and every change manually, Git will do this for you. No more need to tell other developers to not touch the files youíre working on, Git will merge changes of the same file for you. No more need to wait for started features in a small release, Git will have it in a separate branch. Weíre running Git for a year now and weíre still amazed at what this little piece of software can do for us.

Thanks

  • Alan Seiden
    Thanks for motivating me to write this article and doing the proofread on it. And thanks for being an overall great guy and such an active community member.
  • Kent Mitchell
    Thanks for pointing me in the right direction at setting up ZendStudio.
  • Tony Cairns
    Thanks for sharing your knowledge on YiPs.
  • Michael Perzl
    Thanks for maintaining this huge collection of IBM i binaries for open source projects.
  • Scott Chacon
    Thanks for writing such a great book and sharing it with everyone.
  • Vincent Driessen
    Thanks for posting your experience with Git.

Links