This tutorial walks through the process of installing the EGit plug-in to IBM Explorer for z/OS (z/OS Explorer). It then shows how to work with the plug-in to perform standard tasks related to source code management with Git, such as creating a new Git repository, adding an existing Git repository, cloning a Git repository from a remote host, and committing and pushing to a Git repository.
This work is being done as part of a series of code patterns and tutorials centered on bringing DevOps practices to z/OS Connect projects.
- IBM Explorer for z/OS must be installed. If it is not installed, please do so using this reference guide.
- Basic knowledge of Git.
It should take approximately 90 minutes to complete this tutorial.
If you have any questions, feel free to leave an issue in this GitHub repository.
- Install the EGit plug-in
- Create a Git repo with EGit
- Create a repo from an existing project
- Clone a Git repository
- Start working with EGit
1. Install the EGit plug-in
Before you can interact with Git, you need to install a plug-in in your z/OS Explorer environment. This can be done with just a few clicks using the “Install New Software” feature.
1.1 Open IBM Explorer for z/OS. You should see an Eclipse application that looks something like this:
1.2 Click on Help -> Install New Software.
1.3 Click the Add button.
1.4 Type “eGit” for Name and “http://download.eclipse.org/egit/updates” for Location. Then click OK.
1.5 Click the check box next to Git integration for Eclipse. Then below that, click the check box next to Show only software applicable to target environment. All the other checkboxes in the bottom section should have been checked by default. Then click Next.
1.6 On the Install Remediation page, click the Next button.
1.7 On the Install Details page, click the Next button.
1.8 On the Review Licenses page, click the radio button to accept the terms of the license agreements, then click Finish.
1.9 A window will pop up during the install. Make sure the check box next to Eclipse Foundation\, Inc; Java Software is checked. Then click OK.
1.10 Once the plug-in is finished installing, IBM Explorer for z/OS will need to be restarted before it can be used. Another pop-up window should appear asking if you want to restart. Click Yes.
2. Create a Git repo with EGit
Now that your plug-in is installed, it’s time to create a repository you can work with. Start by creating a local repository on your PC where z/OS Explorer is running.
2.1 Re-open IBM Explorer for z/OS if it did not re-open automatically.
2.2 Click on Window -> Perspective -> Open Perspective -> Other.
2.3 Select Git and click OK.
2.4 Select Create a new local Git repository.
2.5 Select the directory where you want to save the Git repository. (A sample path you can use is: C:\Users\YOUR-USER-NAME\git\repository.) Then click Create.
2.6 You’ll see that the repository now shows up in the Git Repositories view.
OPTIONAL 2.7 If you would like to remove the Git repository from the list, follow these instructions:
- 2.7.1 Right-click the repository you wish to remove. Then select “Remove Repository from View” in the drop-down. A pop-up will appear asking if you would like to remove the projects in the Git repository from the workspace; if so click Yes, if not click No. Now the repository should be removed from the list.
OPTIONAL 2.8 If you would like to delete the repository when you are done using it, follow these instructions:
- 2.8.1 Right-click the repository you wish to delete. Then select “Delete Repository” in the drop-down. A pop-up will appear with two checkboxes. If the first checkbox is checked, it will delete the Git repository but not the actual project files. If both check boxes are checked, it will delete the Git repository and the project files. Once you have selected the options you like, click “Delete.” The repository should now be deleted and removed from the list.
3. Create a repo from an existing project
Instead of starting with an empty repository, you might want to start a repository based on a project you already have in z/OS Explorer. Follow these steps to do so:
3.0 Set up: Create a project example.
3.0.1 Click Window -> Perspective -> Open Perspective -> Other. Then select the z/OS Projects perspective, then click OK. (If you don’t have the z/OS Projects perspective available, then jump to step 3.0.2.) Right-click in the z/OS Projects view, then click New -> z/OS Project. Enter a name for the project in the Project name field (for example, “ProjectExample”). Then select Do not create a subproject now and click Finish. Now jump to step 3.1.
3.0.2 Click Window -> Perspective -> Open Perspective -> Other. Then select the Resource perspective, then click OK. Right-click in the Project Explorer view, then click New -> Project. Next, in the wizard select the drop-down next to the General folder, then select Project, and click Next at the bottom. Then type a project name in the Project name field (for example: “ProjectExample”). Then click Finish.
3.1 Find your project in the Project Explorer.
3.2 Right click on the project, then click Team -> Share Project.
3.3 On the Share Project page, select Git and click Next.
3.4 On the Configure Git Repository page, click the Create button. If your project has already been initialized as a Git repository, then you won’t see this window. You will be immediately taken to the next step.
3.5 On the Create a New Git Repository page, choose the directory for your repository then click Finish.
3.6 On the Configure Git Repository page, click Finish.
3.7 The repository is now created. If you followed the instructions in sections 2.2 and 2.3 to open the Git Perspective, you should see the newly created repo.
OPTIONAL 3.8 Now that you have created a repository from an existing project, you may repeat step 2.7 or 2.8 if you wish to remove or delete the repository.
4. Clone a Git repository
Cloning a repository will copy the repository from a hosted remote location, like GitHub, GitLab, or Bitbucket. This will give you a copy of not only the source code but also a full copy of the history of the source code that has been recorded by Git.
4.0 Set Up: Create a GitHub account and fork the repo.
4.0.1 If you don’t already have a GitHub account, you can create GitHub account here.
4.0.2 Now that you have your own GitHub account, click the Fork button at the top of the GitHub repo. This will create a copy of this repository under your GitHub account. Note that the following screenshots show a different repo name than what you should be using in these steps.
4.0.3 For the rest of these instructions, you will be using the GitHub repository under your own account.
4.1 Now back in IBM Explorer for z/OS, Click the Clone a Git repository link or the clone icon at the top.
4.2 Enter the information for the repository you wish to clone. To find the URI for your newly forked repo, click the Clone or download button on your GitHub repo page (this button is located at the top of your GitHub Repository’s page):
Then click the Copy button next to the URL to copy it to your clipboard.
Paste the URI into the URI field. As you enter the URI, the Host and Repository Path should fill themselves out. (Note that your URI should follow this pattern: https://github.com/YOUR-GITHUB-USERNAME/Egit-Installation.git.) If no port is specified, the default port will be used. In the Authentication section, enter your GitHub username in the User field and your GitHub password in the Password field. Then click Next.
4.3 In this window, you can select the branches to clone. You only need the “master” branch, so click the checkbox next to it and then click Next. (Note: We will cover what a branch is in Section 5.)
4.4 Enter the location on your machine where you would like to save the cloned repository in the “Directory” field, then click Finish.
4.5 Now your cloned repository should show up in the Git Perspective of z/OS Explorer.
4.6 Do not remove or delete the repository you just cloned. You will be using it in the next section.
5. Start working with EGit
Working with Git repositories means understanding how code is organized. Let’s examine what a branch is in a Git repository, learn how to work with different branches, and explore why this is useful.
Now that we have walked through the different ways of starting your Git project, let’s discuss how to work with your Git repository. For this section it would be best if you used the repository you forked and then cloned down in the previous steps.
5.1 Once your project has either been created, imported, or cloned, you should see it in the Git perspective of z/OS Explorer.
5.2 Expand the Git project by clicking the arrow to the left of the project. From the drop-down, expand the Branches section, then expand both the Local and Remote sections. These sections show you the different branches of your Git repository. A branch is an independent line of development, meaning you can make a branch off of the main line (your production source code) and work in that branch without affecting the main branch. This is how Git handles parallel development. Each developer can work in their own branch without having to worry about what another developer is doing. Then when your development branch is finished, it can be incorporated back into the main branch. (Note: In Git the main branch is commonly named master.) The branches under the Local section are available on your local machine. The branches under the Remote section are available on the remote Git server (in your case, this is GitHub).
5.3 Please note, in the Local section the master branch has a check mark on it. This indicates that the master branch is currently checked out, meaning when you look at the source code you are looking at the source code in the master branch.
5.4 Now it’s time to create your own branch to work in. Right-click the Git repository at the top, then from the drop-down select Switch To and click New Branch.
5.5 In the pop-up window, enter “development” in the Branch name field. Make sure the Check out new branch option is selected. (This will switch you to the new branch or check out the new branch in Git terms, once it is created.) Then click Finish.
5.6 You should now see the development branch under the Branches > Local section. Also note how the check mark is now over the development branch, meaning that is the branch that is currently checked out.
5.7 Now that you have your own branch to work in, let’s make a change. Under your Git repository, expand the Working Tree section. This section holds your source code. (Note: The .git directory is a hidden directory where Git stores its information.) You should see a
5.8 Now double-click the
sample.txt file to open it.
5.9 Next, add a new line to the file. Once you’ve added the new line, save the file with CTRL+S on Windows, CMD+S on Mac, or click File > Save.
5.10 Once you’ve saved the file, in the panel at the bottom of your screen, make sure the Git Staging view is selected.
5.11 Look at the Unstaged Changes section. You should see the
sample.txt file you just changed. Unstaged changes are changes that are not going to be included in the next Git commit. A commit is like saving in Git terms.
5.12 Now stage your change so it can be included in the next commit. You can do this by selecting the change and clicking the green plus button. (Note: Clicking the double green plus button will stage all unstaged changes.)
5.13 You should now see that the file has moved to the Staged Changes section. So now the change will be included when you commit your code.
5.14 Now it’s time to commit your new change. In the Commit Message section, write a commit that describes the change you made.
5.15 Now you can choose to either just Commit your changes or Commit and Push your changes. If you Commit your changes, they will be saved to the branch you are working in (the development branch) on your local machine. If you Commit and Push, then your changes will be saved to your branch locally and it will then push the local copy of your branch to GitHub. If there is already a development branch on GitHub, your code will be added to that branch. If there is no development branch, then a development branch will be created. Click the Commit and Push button.
5.16 A pop-up window should appear after you click Commit and Push. Leave all the defaults and click Next.
5.17 If prompted, enter in your GitHub username and password. Then click OK.
5.18 You should now see a pop-up like the one below. This pop-up shows that your development branch will be pushed up to GitHub, and that this is a new branch on your GitHub repository. Click Finish to push the branch. If you are prompted for your username and password again, enter them and then click OK. If not, proceed to the next step.
5.19 You should now see a window that looks like the one below, which confirms that your branch was pushed up to GitHub. Click the Close button.
5.20 Now go back to GitHub and incorporate your development branch into your master branch. Back on your GitHub repo page, click the Pull requests tab at the top.
5.21 Now click the New pull request button.
5.22 Under the Comparing changes title, you’ll see that there is a section that has one branch being merged into another. Change this so that the master branch is on the left, and your development branch appears on the right.
5.23 Now click the Create pull request button. (Note: If you look at the bottom of this page you can see the changes you are going to bring in to the master branch from your development branch.)
5.24 Now you can add a description about what changes are going to be brought into the master branch from your development branch. Then click Create pull request.
5.25 Now that your pull request has been created and other people can see your changes, it’s time to add to the master branch. Here you can also assign someone to review your request and you can merge your pull request. Let’s merge the pull request so your changes are added to the master branch. Click the Merge pull request button.
5.26 Click the Confirm merge button.
5.27 You should now see a purple Merged icon on the screen.
5.28 Now the changes from your development branch have been incorporated into the master branch. If you click the Code tab at the top of the page, you can view the source code.
5.29 Now you should see that the master branch is selected. Click on the
5.30 Here you can see that a new line is added to the file on the master branch, so you have successfully incorporated your changes from your development branch into the master branch.
Congrats on finishing this tutorial! We hope you’ve enjoyed installing and learning how to use the EGit plug-in to allow easy interaction between z/OS Explorer and Git. If you want to start using Git in your organization but aren’t sure how to get started or what the migration process looks like, please contact Ronald Geraghty at firstname.lastname@example.org to set up a virtual session. We can discuss topics like parallel development using Git, and what a mainframe DevOps pipeline looks like with Git. And for additional information about this topic, see the Resources section in the top right column of this page.