With the information in this TechTip, you can get started with Git development on your IBM i!
In this article, we are going to talk about Git. I want to avoid the idea that this is a tutorial. A tutorial would be a very long and text-y article. This TechTip covers:
For this article, I will be using QP2TERM as my shell of choice. I recommend SSHing right into PASE from your local machine if you have it set up. You will also see me use the words "folder" and "directory," but they really mean the same thing.
If you don’t have an IBM i with Git installed, you can also do all this stuff on any OS that runs Git, which is almost every OS these days!
Creating a Repository
Creating a repository (repo for short) is simple, but we need to talk about what a repository is. There are two types of repos:
The main repo is where all the working code will reside. In theory, no broken or not-working code should be within the main repo. You also never edit code in the main repository. Usually, you clone the main repo, which creates the local repo.
The local repository is where you do your source changes and developer tests. It's called a local repository because traditionally you would clone the repo to your local machine and develop and test your changes there, but since we can't compile any of our code locally, we're going to have to clone our repo into your home directory on the IFS.
Before we do anything, you will need a gitconfig for your user profile. Git has commands to do this for us, so run these commands, but change where applicable:
$ git config --global user.name "John Doe"
$ git config --global user.email email@example.com
$ git config --global branch.autosetupmerge always
The branch.autosetupmerge means that when we push into a separate branch, it will automatically merge into the origin. To make this tutorial simple, we will stick with that. I would usually recommend creating the repo before you start any new development, but since we have pre-existing code, we will go with the following steps.
First, we are going to create the main repository. To do this, we are going to go to our shell client, where we can access Git and change the current directory (CD) to the MYPROJ directory, which I originally created in the root CD /MYPROJ.
Then, we simply use git init to create our new repository. This is the main repo.
> git init
Initialized empty Git repository in /MYPROJ/.git/
Git thinks there are no files in the repo yet because we have not committed the existing source we created previously (HELLOWORLD.rpgle and MYCLPGM.clle). To do that, we need to run three commands on the main repo:
> git add .
> git commit -m “initial commit for existing files”
[master (root-commit) 045bb03] initial commit for existing files
2 files changed, 18 insertions(+)
create mode 100755 QCLLESRC/MYCLPGM.clle
create mode 100755 QRPGLESRC/HELLOWORLD.rpgle
These commands will be explained later. This code should successfully commit the source to the main repository. This is also the only time we should ever run commands against the main repository; all other commands should be done only in your own local repository.
From here, there should be no need to worry about the main repo.
Local Repositories and the Distributed Development
You may be wondering why we can't just edit the files in the same directory. Traditionally, most file systems don't have a mechanism for locking—unlike how objects and members can be locked in QSYS when in use or being edited.
Git introduces the distributed development, so you can make changes to a product without breaking anyone else's code or functionality. With Git, there is no need to have 100+ lines of comments in your RPG source just to keep a modification log. With Git, you have commit logs and even the ability to revert/roll back to a certain commit.
Local repos allow you to make changes to any source you want, without breaking anyone else's development. Something you added not working in your local repo? You can fix it! Something added in an older commit broken something? Great! You can revert those changes with Git.
Cloning Your Repository for Further Development
Personally, when I sign onto any of my IBM i partitions, I like my current directory to be /home/LALLAN. I would also recommend cloning your development code into your home directory. Do not share a home directory with anyone. You can change your current directory for your job with CHGCURDIR from the regular (QCMD) command line or CD from a shell. You can also change it permanently on your user profile settings.
Now, change your current directory to your home directory. Then you should run this code:
> CD /home/LALLAN/
> git clone /MYPROJ
Cloning into 'MYPROJ'...
This code creates a MYPROJ folder within your current directory (/home/LALLAN/MYPROJ, for example). This is your local repository. Don't let other users develop in this folder. Inside would be our two folders, QRPGLESRC and QCLLESRC, with the appropriate stream files inside. We will discuss those later!
Git Command Explanations
Now we need to talk about what some basic Git commands do. You can only run Git commands against your repo while your current directory is within a repo. For the sake of this article, I will be covering only the basics.
Committing New Changes
This is where the real magic happens! You always get a nice feeling when you commit a change that fixes a bug and you get to write "I FIXED THIS OLD BUG" in the commit message.
The main command for committing is git commit, but it will only commit changes you tracked.
We’re going to make our first change in its own branch. A branch is just another area in which you can develop away from production files (for example). You might have two branches:
You would make all your developers develop in the development branch, and then when a phase of development is done, you can merge the development branch into the production branch (master).
With that being said, we need to make our development branch so we can start making changes.
> git branch dev
> git branch -l
> git checkout dev
Switched to branch 'dev'
We use git branch dev to create a dev branch, and git checkout dev to switch to that branch.
Let’s run through a simple change, commit, pull, and push. To start, let’s make a change to MYPROJ/QRPGLESRC/HELLOWORLD.rpgle in your local repo:
Dcl-S Text Char(20);
//Text = 'Hello world';
Text = 'Hello MCPress.';
*InLR = *On;
Then, check see if Git has picked up your change:
> git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
no changes added to commit (use "git add" and/or "git commit -a")
Because we changed our local copy of HELLOWORLD.rpgle, we need to track our new changes with git add:
> git add QRPGLESRC/HELLOWORLD.rpgle
Then simply commit and push, but like I said earlier, I do a pull before a push to pick up other people’s changes. Don’t forget: people will only pick up your changes after you have pushed.
> git commit -m "Change HELLOWORLD text."
[master b3f1080] Change HELLOWORLD text.
1 file changed, 4 insertions(+), 2 deletions(-)
> git pull
> git push
Counting objects: 4, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (4/4), 438 bytes | 0 bytes/s, done.
Total 4 (delta 0), reused 0 (delta 0)
You do another git status to see if the push worked.
The last thing to do might be to merge the development branch back to the master (production) branch, but since we set it up our config with autosetupmerge, we don’t have to. If you didn’t use autosetupmerge, you would merge whenever you feel the branch is production-ready.
That’s it for this TechTip. Now get started with Git development on your IBM i!