Skip to content

Commit

Permalink
Minor fixes to README and a rename (#49)
Browse files Browse the repository at this point in the history 
Co-authored-by: ROOT <ROOT@TVT6012.svl.ibm.com>
  • Loading branch information
LIAM and ROOT authored Sep 4, 2020
1 parent 52df715 commit abf5642
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 55 deletions.
110 changes: 55 additions & 55 deletions IDE/GitISPFClient/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Table of Contents
- [Git ISPF Client Readme](#git-ispf-client-readme)
- [Purpose](#purpose)
- [How-To Install](#how-to-install)
- [Prerequisites](prerequisites)
- [Prerequisites](prerequisites)
- [Copy USS files to PDS](#copy-uss-files-to-pds)
- [Initial configuration](#initial-configuration)
- [Running the ISPF Client](#running-the-ispf-client)
Expand All @@ -19,39 +19,39 @@ Table of Contents
------------
## Purpose

The purpose of this GitHub repository is to provide an ISPF interface that interacts with a Git repository to allow cloning, staging, checking in, pushing and pulling as well as other git commands.
The purpose of this GitHub repository is to provide an ISPF interface that interacts with a Git repository to allow cloning, staging, checking in, pushing and pulling as well as other git commands.

------------
## How-To Install

### Prerequisites

You must have Rocket Git installed in USS on the z/OS system you plan to use. The minimum version required is 2.14.4. You can install Rocket Git using SMP/E as part of IBM z Open Development or you can go to www.rocketSoftware/git for instructions on getting Rocket Git. . You need Rocket Git to run git commands on z/OS.
You must have Rocket Git installed in USS on the z/OS system you plan to use. The minimum version required is 2.14.4. You can install Rocket Git using SMP/E as part of IBM z Open Development or you can go to www.rocketSoftware/git for instructions on getting Rocket Git. . You need Rocket Git to run git commands on z/OS.

### Clone GitHub project containing Git ISPF Client code

We have a chicken and egg situation. We want to use the Git ISPF client to clone repositories, but we have to clone a repository first before we can bring the Git ISPF Client code up. If you are reading this you are already at https://github.com/IBM/dbb. So you will need to do a command line clone to get the code.

* Update your .profile to have the required Rocket setup

There are a number of variables that need to be set up and exported before you can use Git in USS. These can be set up in your .profile file, for example:

export JAVA_HOME=/usr/lpp/java/J8.0_64
export DBB_HOME=/var/dbbTEST/usr/lpp/IBM/dbb_1.0.5
export GIT_SHELL=/var/rocket/bin/bash
export GIT_EXEC_PATH=/var/rocket/libexec/git-core
export GIT_TEMPLATE_DIR=/var/rocket/share/git-core/templates
export PATH=$PATH:$JAVA_HOME/bin:/var/rocket/bin
export MANPATH=$MANPATH:/var/rocket/man
export PERL5LIB=$PERL5LIB:/var/rocket/lib/perl5
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
There are a number of variables that need to be set up and exported before you can use Git in USS. These can be set up in your .profile file, for example:

export JAVA_HOME=/usr/lpp/java/J8.0_64
export DBB_HOME=/var/dbbTEST/usr/lpp/IBM/dbb_1.0.5

export GIT_SHELL=/var/rocket/bin/bash
export GIT_EXEC_PATH=/var/rocket/libexec/git-core
export GIT_TEMPLATE_DIR=/var/rocket/share/git-core/templates

export PATH=$PATH:$JAVA_HOME/bin:/var/rocket/bin
export MANPATH=$MANPATH:/var/rocket/man
export PERL5LIB=$PERL5LIB:/var/rocket/lib/perl5

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

* Create an SSK key pair to be able to Clone

Expand All @@ -73,18 +73,18 @@ We have a chicken and egg situation. We want to use the Git ISPF client to clone

### Copy USS files to PDS

In the clone location there is a directory called `IDE/GitISPFClient/sbgzsamp`. There is a file there called `bgzgit.jcl`. This JCL member will allocate a set of PDS libraries and copy the files from the clone location. Make a copy of this JCL member in a data set on z/OS. Tailor as per the instuctions in the job and submit the Job. The job should finish with a return code of 0 and have populated the specified libraries.
In the clone location there is a directory called `IDE/GitISPFClient/sbgzsamp`. There is a file there called `bgzgit.jcl`. This JCL member will allocate a set of PDS libraries and copy the files from the clone location. Make a copy of this JCL member in a data set on z/OS. Tailor as per the instuctions in the job and submit the Job. The job should finish with a return code of 0 and have populated the specified libraries.

### Initial configuration

In the libraries you created by running the BGZGIT JCL member there is a SBGZEXEC library. In there there is BGZCONF member. Edit this member and look for the 4 install locations specified there, by default:

JAVA_HOME = '/usr/lpp/java/J8.0_64'
Rocket_HOME = '/rsusr/ported'
DBB_HOME = '/usr/lpp/IBM/dbb'
JAVA_HOME = '/usr/lpp/java/J8.0_64'
Rocket_HOME = '/rsusr/ported'
DBB_HOME = '/usr/lpp/IBM/dbb'
ICONV_HOME = '/bin/iconv'

Change these values to where you have Java, Rocket Tools and iconv installed on your system. You can also set DBB_HOME if you have installed DBB already.
Change these values to where you have Java, Rocket Tools and iconv installed on your system. You can also set DBB_HOME if you have installed DBB already.

------------

Expand All @@ -99,7 +99,7 @@ Start the ISPF Git client dialog using the BGZGIT REXX executable code. You can
* Added to an ISPF menu:
* Set &ZSEL to **'CMD(EX <hlq>.SBGZEXEC(BGZGIT)) NOCHECK'**. NOCHECK supports the entry of concatenated commands through the direct option (trail). On the calling panel, also specify **&ZTRAIL=.TRAIL**.
* Added as a command in the SYSPROC concatenation:
* Create an EXEC in the SYSPROC concatenation (for example, BGZGIT) that starts the BGZGIT EXEC with any required parameters hardcoded:
* Create an EXEC in the SYSPROC concatenation (for example, BGZGIT) that starts the BGZGIT EXEC with any required parameters hardcoded:
* **ex 'BGZ.SBGZEXEC(BGZGIT)'**
* After creating the executable code, run the code from the command line. Enter the following command: **TSO %BGZGIT**.
* If the command is added to a command table, enter **%BGZGIT**.
Expand All @@ -108,61 +108,61 @@ Start the ISPF Git client dialog using the BGZGIT REXX executable code. You can

Once you have started the ISPF Git client you should go to Option **0 - Preferences**. There are 4 options here:

Preference | Description
Preference | Description
------------------------------| -----------
Client Code Page | The code page that will be used to convert between native characters on the host, and unicode escape sequences on the github repository. Default is IBM-037
Client Code Page | The code page that will be used to convert between native characters on the host, and unicode escape sequences on the github repository. Default is IBM-037
Git user.email | user.email used for Git commands - Currently not used
Git user.name | user name used for Git commands - Currently not used
Suppress .files from USS list | To not display .files on working directory list (default is Yes)
Git user.name | user name used for Git commands - Currently not used
Suppress .files from USS list | To not display .files on working directory list (default is Yes)

### Cloning a remote repository
To start working on code in a remote Git repository go to option **2 - Repository**. Enter the repository address in the line at the top of the screen, for example **git@github.com:campagboy/dbb.git**. It should be noted that Rockets Git port for z/OS currently only supports clone Git repositories through SSH. As such you will be required to set up private and public keys. In addition it should be noted that, at this time, the Git ISPF Client does not support interactively entering passwords for the keys, so as such the public/private key pair need to be created with no password. See **https://forum.rocketsoftware.com/t/using-git-for-z-os-with-github/654** for information on generating an ssh key pair on z/OS. Next to the git repository you will need to enter a working tree directory. The directory you specify will have an extra directory level added of the repository being cloned. So in the example above, if you enter **/u/myuser/git** as your working directory, then the actual working directory created will be **/u/myuser/git/dbb**. Once you press enter the repository will be cloned into the working tree directory.
To start working on code in a remote Git repository go to option **2 - Repository**. Enter the repository address in the line at the top of the screen, for example **git@github.com:campagboy/dbb.git**. It should be noted that Rockets Git port for z/OS currently only supports clone Git repositories through SSH. As such you will be required to set up private and public keys. In addition it should be noted that, at this time, the Git ISPF Client does not support interactively entering passwords for the keys, so as such the public/private key pair need to be created with no password. See **https://forum.rocketsoftware.com/t/using-git-for-z-os-with-github/654** for information on generating an ssh key pair on z/OS. Next to the git repository you will need to enter a working tree directory. The directory you specify will have an extra directory level added of the repository being cloned. So in the example above, if you enter **/u/myuser/git** as your working directory, then the actual working directory created will be **/u/myuser/git/dbb**. Once you press enter the repository will be cloned into the working tree directory.

It is important to note that as Git is a Hierarchical file system SCM, the folders and files in the repository are cloned into the HFS and not into PDS/PDSE.
It is important to note that as Git is a Hierarchical file system SCM, the folders and files in the repository are cloned into the HFS and not into PDS/PDSE.

### Working with files in a remote repository
Once a repository is cloned you can choose to work on the files either through the ISPF Git interface or you can work on them directly through ISPF UDLIST (3.17), or using your editor of choice through OMVS.
Once a repository is cloned you can choose to work on the files either through the ISPF Git interface or you can work on them directly through ISPF UDLIST (3.17), or using your editor of choice through OMVS.

The Git commands you use generally work at a repository level as opposed to a file level. However there are some Git commands that affect individual files. Using the ISPF Git Client you can enter a **/** on any line to see a list of available options, or you can use the fast path command. On any panel press **PF1** to get a list of the available commands and their explanation. All of the repository level git commands can be entered on all the panels, for example the file list panel, but still work at the repository level. This allows you to edit a file, stage it, commit it and push it without having to return to the repository panel.

To start working with files through the ISPF Git interface enter **JU** (Jump to Working Directory) next to the repository that contains your files. From here you will see a list of folders and files. To drill down into a directory enter an **L** next to the directory. The available options at a file level are:

Option | Description
Option | Description
------- | -----------
E | Edit file (EBCDIC)
EA | Edit file (ASCII)
EU | Edit file (UTF-8)
V | View file (EBCDIC)
VA | View file (ASCII)
VU | View file (UTF-8)
EA | Edit file (ASCII)
EU | Edit file (UTF-8)
V | View file (EBCDIC)
VA | View file (ASCII)
VU | View file (UTF-8)
B | Browse file
D | Delete file
R | Rename file
UB | DBB User Build
UL | View last DBB build log

To create a new file enter S <filename> on the command line. Make sure you give the filename an extension that matches an entry in your .gitattributes file. This way, when the file is added to staging it will automatically be tagged with the correct CCSID.
The User Build option is works with a cloned repository that has a DBB build structure containing groovy scripts for build. The structure expected will be as follows in the z/OS Unix directory :

The User Build option works with a cloned repository that has a DBB build structure containing groovy scripts for build. The structure expected will be as follows in the z/OS Unix directory :

**clone working directory/Build/Application/folder/filename**

To request a DBB User Build through ISPF Git interface, enter **UB** (User Build) next to the file you want to build.
On the DBB User Build panel, you will have to specify the build sctript to use (an existing DBB groovy build script that use IBM Dependency Based Build), and the build destination HLQ where you want to have your file built.
On the DBB User Build panel, you will have to specify the build script to use (an existing DBB groovy build script that uses IBM Dependency Based Build), and the build destination HLQ where you want to have your file built.

### Issuing Git commands against a repository
Most Git commands work against the repository. You can enter the Git commands from any line command entry field. Again, enter a **/** to see the options available, or use the fast path Git commands which are:

Option | Description
Option | Description
------- | -----------
ST | Git Status
AD | Git Add (or stage)
AD | Git Add (or stage)
CO | Git Commit
PS | Git Push
CP | Git Commit and Push
PL | Git Pull

The above commands are the standard Git commands, but through the use of ISPF panels and tables certain actions can be performed.
The above commands are the standard Git commands, but through the use of ISPF panels and tables certain actions can be performed.

#### ST - Git Status
Issues the Git status against the repository. You will be informed of files that are unstaged or uncommitted.
Expand All @@ -183,25 +183,25 @@ This is a combination of commit and push in a single command.
If there are any files in the repository that have been updated you will need to pull the changes into your local clone.

-------------------------
You can also enter any other valid Git command through the Git command prompt. On any line command enter a **/** and press enter, then select **Git Command Prompt**. You will be presented with a panel where you can enter any valid git command. For example Git Diff, or Git Merge.
You can also enter any other valid Git command through the Git command prompt. On any line command enter a **/** and press enter, then select **Git Command Prompt**. You will be presented with a panel where you can enter any valid git command. For example Git Diff, or Git Merge.

### Adding new files
To create a new file in a directory, from the file list enter **S <filename>** and press enter. The ISPF editor panel opens where you can work on the file you have just created. Please note that to be able to successfully stage and commit the file, the extension used must exist in the **.gitattributes** file.
To create a new file in a directory, from the file list enter **S <filename>** and press enter. The ISPF editor panel opens where you can work on the file you have just created. Please note that to be able to successfully stage and commit the file, the extension used must exist in the **.gitattributes** file.

### Working with branches
NMext to your cloned repository enter the **BR** command to work with the branches in your repository. From here you can perform the following actions with the following commands:

Option | Description
Option | Description
------- | -----------
CB | Checkout to working branch
PB | Push branch to origin
DB | Delete local branch
JU | Jump to working directory
PB | Push branch to origin
DB | Delete local branch
JU | Jump to working directory

The Checkout to local branch will replace the conmtents of your work tree with the files from the branch you selected.
The Checkout to local branch will replace the conmtents of your work tree with the files from the branch you selected.

### Finished working with a clone?
Once you have finished working with a clone you can remove it by entering an **RM** next to the repository name. This will delete the working directory as well.
Once you have finished working with a clone you can remove it by entering an **RM** next to the repository name. This will delete the working directory as well.

### Creating a local git repository

Expand Down
0 IDE/GitISPFClient/sbgzgml/bgzadbbsc.gml → IDE/GitISPFClient/sbgzgml/bgzdbbsc.gml
View file
File renamed without changes.

0 comments on commit abf5642

Please sign in to comment.