Git on z/OS
🖥 🖥
What is Git?
There is a high chance you have heard of Git, but what is it exactly? Git is a distributed open-source tool that manages source code in a central server used to track changes in a set of files. As a “Software Code Management”[1] (SCM) tool, it allows developers to store versions of their code in folder structures called repositories (repos). As a distributed SCM, it lets you copy repos to a PC, or any network-connected device with commands like “clone” and “pull”.
There are many Git service providers (i.e. GitLab and GitHub) that can host your repos. In addition to source code hosting, they provide features like team collaboration, integration workflows, security, issue tracking, and more.
The Value of Git
Git provides easy team collaboration by allowing several developers to seamlessly work on the same code base in parallel. Git is one of the most widely used SCM in the development community, and It is available for use on z/OS.
Modern IDEs like IBM’s IDz or Microsoft’s VSCode all come with a Git client to allow developers to work with their remote repos. Also, modern DevOps processes can run pipeline builds on z/OS using Git to clone a repo as the first step of an automated compile and link process.
How is Git different on z/OS?
On z/OS, Git plays a key role in the overall DevOps solution. The version of Git that IBM recommends is Rocket Software’s port of the Git client. This is normally installed in z/OS UNIX to access repos from any Git Server.
Rocket’s port of Git has the added feature of codepage translation. Basically, this means that your mainframe source code (which is encoded as EBCDIC) can be stored and retrieved from Git (which is internally stored in ASCII).
This allows developers to work on their repos from their desktop in ASCII, the default for PCs or Linux, while allowing mainframe DevOps pipelines to work in EBCDIC. All this happens under the covers through a file called .gitattributes[2]. It tells Git which files should be translated from ASCII to EBCDIC when working on z/OS. A sample file looks like this:
# file encodings for zOS
*.cpy zos-working-tree-encoding=ibm-1047
*.cbl zos-working-tree-encoding=ibm-1047
.gitignore zos-working-tree-encoding=iso8859–1
The first line is a comment, the next lines tell Git that files ending with ‘.cpy’ or ‘.cbl’ must be translated from ASCII to EBCDIC. In this case, Git will translate the source code to codepage ‘ibm-1047’.
IBM-1047 is the default codepage on z/OS UNIX in the United States, while other countries can choose different codepages. The z/OS systems programmer can provide guidance on which codepage to use.
Below is Rocket’s Software’s currently supported set of codepages.
There are some characters (see below) that will not translate properly. For example, a COBOL program that has a hardcoded hex ‘0D’ value will not translate from ASCII to EBCDIC correctly. In this example, the recommendation is to either change the source code to use a ‘picture’ clause with an explicit hex value “pic x(1) value x’0D’”. Alternatively, you can set the property in the .gitattribute file as “binary” to skip codepage translation.
Unsupported hex code
CHAR_NL = 0x15
CHAR_CR = 0x0D
CHAR_LF = 0x25
CHAR_SHIFT_IN = 0x0F
CHAR_SHIFT_OUT = 0x0E
How to install Git
You can get the Git client from Rocket Software’s website at https://www.rocketsoftware.com, and through IBM’s SMP/E package for Git.
All of Rocket’s open source software, including the newest version of Git (2.26), now use conda for downloading, installing and upgrading. Conda will help to simplify the installation process for open source software by eliminating the amount of steps involved in the installation. For those not familiar with conda, it is an open source package and environment manager that runs on multiple operating systems. To get started with this method, the first step is to install z/OS Miniconda. This is the installer for conda on the z/OS UNIX environment.
Once you have registered and signed-in at Rocket’s community page, navigate to the downloads page and under “z/OpenSource” search for Miniconda (ID USSP-1175)
Tip: change show entry per page, found at the bottom of the panel, to “100” to see all the products in one page.
Download the latest version of Miniconda and follow the provided instructions (you can also follow this step by step video tutorial). Once z/OS Miniconda has been installed and setup on your z/OS environment, you are ready to install Git!
Go back into the Rocket community downloads page (where z/OS Miniconda was downloaded from), and search for Git. You will not be able to download the latest Git version from there, but you can download the full installation instruction guide for the latest version with the file Git for zOS 2.26.2 -Release Notes.pdf. Once you have read all the instructions, use the command below to install Git using conda right on z/OS.
conda install -c <channel> gitThe preferred installation method is to use IBM’s SMP/E package for Git. Instructions are available in https://www.ibm.com/docs/en/dbb (under prerequisites for z/OS in the “Installing and configuring DBB” section)
Best Practices
Using Git on z/OS implies it will be used to clone repos to build programs with some DevOps automation tool like IBM’s Dependency Based Build (DBB). In order to do this, verify the z/OS UNIX environment is setup to use Git.
The Rocket install guide explains how to setup the z/OS UNIX environment for Git. Here is an excerpt from that document showing the environment setup.
Security and firewalls must also be configured to access a repo from z/OS. There are several security options, but the most common are SSH, HTTPS with Active Directory, or Personal Access Tokens (PAT) based credentials. The local z/OS system programmer and Git admin can provide guidance.
As a best practice, a repo should contain all the files needed to compile and link your application. This can include source programs, copybooks, JCL and Rexx execs. Another best practice is to always include a README file. This is where project instructions, documentation, and any other useful information is shared. As a rule of thumb, limit the number of files to less 10,000.
Use good folder naming conventions to simplify navigation within your repo. For example, use a meaningful folder name like ‘batch-cobol’ for all COBOL programs that run in batch.
As a best practice, consider implementing a Gitflow model that fits your current agile practices. This helps standardize a consistent Git branching strategy across all teams.
Also, when committing changes in Git, add meaningful text messages to allow others on a team to quickly understand the change during peer review.
Sample Gitflow
Gitflow is a common practice used by distributed development teams but also works for mainframe teams. It consists of a set of rules on how developers create branches to do their work and ultimately promote their code to upper environments like QA and production.
This diagram describes the basic branches used in a typical mainframe application project.
The diagram below outlines a standard flow from developer on their PC, to the merge request, and then the pipeline orchestrator to complete a full CI/CD workflow.
It lists the steps that a developer takes:
- clone
- branch
- change code and build (this can be with IBM’s Dependency Based Build product)
- Test
- Requests to merge (pull request) changes into the integration branch as explained in the Gitflow above.
This article provided a quick introduction to Git on z/OS. Getting started with Git on z/OS is made easy with the help of Rocket Software’s port of Git that provides the added feature of codepage translation. Whether you chose to develop using an IDE like VSCode with a Git plugin, or chose to use Git through the command line, you will be able to take full advantage of all its capabilities like you would in any other platform. For more information regarding Git on z/OS, check out the resources below.
