In this post I will walk through the steps necessary to clone a repository from GitHub using Rocket’s port of git for z/OS.
Much of the content in this post is contained in the release notes for git for z/OS.
In a nutshell
These instructions will suffice for readers already familiar with git, ssh, GitHub, and Unix System Services on z/OS.
- Install git for z/OS, including its dependencies (bash and perl).
- Set up your environment on z/OS for git, as per the git release notes.
- Create an account on GitHub (if you don’t already have one).
- Generate an ssh key pair on z/OS.
- Add the public key to your account on on GitHub.
- Clone the repository using the ssh access method for git. A suggested starter repo is https://github.com/zorts/hello_world ;this repo contains an example of a
.gitattributes file that arranges for text files to be encoded and tagged as EBCDIC.
A more detailed account
What, that wasn’t enough? 
OK, here’s a more detailed description.
Install git for z/OS, including its dependencies (bash and perl).
Download the latest version of git for z/OS from the Rocket Open Source download page. You will also need the latest versions of bash and perl. If you don’t already have gzip on z/OS, you will need that, too.
Typically people download the software to a Windows PC and then transfer it to z/OS for installation. Be sure that the transfer is a binary transfer; FTP is a good choice. Note that some transfer methods (notably scp) will unconditionally convert an incoming (to z/OS) file from ASCII to EBCDIC, rendering the file unusable.
Once the files have been downloaded, install them into “an appropriate install location.” If you are just testing the software and don’t have the necessary permissions to install it in a location such as /usr/local, you can just install them into a directory in your home directory.
For more information on unpacking files for installation, see this post on the Rocket Community Forum.
Update: See this forum posting for more detailed installation instructions.
Set up your environment on z/OS for git, as per the release notes.
The git release notes contain detailed information on the necessary environment variables to set for using git.
That said - this script can be put into a file and sourced as needed, or invoked from your .bash_profile at login. Change the value for GIT_ROOT to point to the directory in which you installed git and its prerequisites.
# setup script for bash
#
# NOTE: this can either be added to your .bash_profile OR
# sourced when needed:
#
# . <this file name>
#
GIT_ROOT=/path/to/git/installation
export GIT_SHELL=$GIT_ROOT/bin/bash
export GIT_EXEC_PATH=$GIT_ROOT/libexec/git-core
export GIT_TEMPLATE_DIR=$GIT_ROOT/share/git-core/templates
export PATH=$GIT_ROOT/bin:$PATH
export MANPATH=$MANPATH:$GIT_ROOT/man
export PERL5LIB=$PERL5LIB:$GIT_ROOT/lib/perl5
# These enable enhanced ASCII support
export _BPXK_AUTOCVT=ON
export _CEE_RUNOPTS="FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)"
export _TAG_REDIR_ERR=txt
export _TAG_REDIR_IN=txt
export _TAG_REDIR_OUT=txt
# optional (do once): set git editor to create comments on encoding ISO8859-1
# git config --global core.editor "/bin/vi -W filecodeset=ISO8859-1"
Create an account on GitHub (if you don’t already have one).
Go to GitHub and follow the instructions there for creating an account. This is necessary because the only git access protocol currently supported by git for z/OS is the ssh protocol; the “git” and “http” protocols are not supported.
Generate an ssh key pair on z/OS.
See the instructions on GitHub for generating an ssh key pair more detail. There are a few things not mentioned there that are important:
You need to first create a .ssh directory in your home directory, and make sure that the path to that directory is not writable by anyone but you. Here are a typical set of commands to do this. Do NOT type the comments at the end of each command line.
$ cd ~ # cd to your home directory
$ chmod 755 . # allow others to read and traverse your home directory,
# but not write into it. If you don't want ANYONE to be
# able to read your home directory, change to 700.
$ mkdir .ssh # create the .ssh directory
$ chmod 755 # allow others to read this directory but not write into it.
Now you can create an ssh key pair. A description of public key encryption is beyond the scope of this article, but the important concept is that a key pair consists of a public key and a private key. You share the public key with other servers you wish to access, and keep the private key carefully protected on your own system. ssh will use them both to establish a secure communication channel between the local system and the remote (and untrusted) server.
You can generate an appropriate key pair with this command:
$ ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -C "yourid@yourdomain.com" -P ""
Generating public/private rsa key pair.
Your identification has been saved in /u/yourid/.ssh/id_rsa.
Your public key has been saved in /u/yourid/.ssh/id_rsa.pub.
The key fingerprint is:
02:63:a9:bd:23:d0:61:0b:85:36:0b:af:86:71:54:75 yourid@yourdomain.com
$
This will create a public key pair and store both pieces in your .ssh directory.
Add the public key to your account on on GitHub.
Follow the instructions on GitHub for adding a new SSH keypair to your account. You will be copying the contents of the newly created public key to GitHub.
Clone the repository using the ssh access method for git.
Go to the repository on GitHub that you wish to clone and click on the green “Clone or download” button towards the right side of the page. A suggested starter repository is https://github.com/zorts/hello_world; this repo contains an example of a .gitattributes file that arranges for text files to be encoded and tagged as EBCDIC. Make sure you chose the SSH URL. Copy the URL and then insert it into this command on z/OS:
$ git clone <URL from GitHub>
This will clone the repository on your local z/OS machine.
What’s next?
Once you have successfully cloned a repository you can begin working with its files using git.
An important issue when using source from git is handling the ASCII/EBCDIC encoding issue. There are detailed instructions on this in the git release notes, but to summarize, you will need to create a .gitattributes file that identifies how to encode the files in the working directory. Some files must be encoded using ASCII, most notably the .gitattributes and .gitignore files. A good starting point for a .gitattributes file is:
# encode all files as EBCDIC unless mentioned elsewhere
* git-encoding=iso8859-1 working-tree-encoding=ibm-1047
# encode selected files as ASCII
.gitattributes git-encoding=iso8859-1 working-tree-encoding=iso8859-1
.gitignore git-encoding=iso8859-1 working-tree-encoding=iso8859-1
You will need to become familiar with the features of IBM’s enhanced ASCII support, including file tagging and automatic conversion.