Using GIT for Dataflex Development

Why Version control

Before we jump into GIT in specific, it is important to mention some reasons why developers are more productive when using version control;

• We can keeping track of multiple versions deployed
• Multiple developers can be working on same project
• It is helpful with code checks for auditing or training
• A proper change log of each change is maintained
• We can locate changes for one feature/fix across a number of changed files
• The code is in a safe location, in case of lost hardware
• We can find when a located bug introduced, so you can see what clients are effected

It can be tough when you are looking at a piece of code, not knowing when/how it’s used. But when you can run a version control tool, which shows exactly when those lines were added, by who and with what description, it makes it so much easier to decide what to do with that piece of unknown code, whether it’s retiring it, refactoring, documenting or just leave it as it is. Another good reason that warrants its own paragraph is when you are developing using Agile sprints/iterations. Oversimplified, you determine a list of features you or your team are going to implement in order of priority, but your iteration is timeboxed to eg 4 weeks. This means that after 4 weeks all approved and tested code stays in the product and the features that did not make it in full or are not fully tested and or approved, are to be taken out and used for the next sprint/iteration. This warrants for a good use of version control, where each feature can very easy be isolated from the packaged software.

Types of version control tools

Version control is a way of work, not a tool itself. There are many version control systems, some are more suitable for the VDF development cycle then others. We can identify the following types. Historical version control was done by directory backups e.g. by using zip and file naming. The result is many near identical copies. It also requires a lot of self discipline. Centralised version control has been very popular for years, where you have one centralised server and many remote clients. Examples are CVS, Subversion, Vault, Visual Source Safe and Team Foundation Server. These work very well when you are connected to the server. When not connected these are not giving much assistance. Distributed version control is the latest and most popular peer to peer version control tool. Examples are Mercurial (hg), GIT, BitKeeper etc. This white paper focuses on the last category the distributed version control, with GIT in particular. If you are currently using a Centralised version control, you might be interested in the following list of major changes with the Distributed flavour;

• No access to a server is required, the distributed VC has a local repository that gets synch’ed with a remote (central or peer to peer) repository when it can but can work fine on its own.
• Each developer has its own repository local to their working directory
• No file checkout is required, just start changing the files
• You can stage a number of files, so multiple files can be part of one commit (maintaining the relationship of the changes in the files)
• You can optionally stage only a couple of changed lines in a file (if more changes are made then you want to stage).
• You commit the staged changes with a comment
• You push and pull changes between the local and remote repositories
• Branching used to be hard and therefore hardly used. Now really simple.
• But commit is local, so developers have to do a push to remote to make the change visible for other developers to do a clone/pull from remote

Installing and using GIT

Enough theory, we’ll now show how it’s done. GIT is very small and easy to uninstall later if you decide to do so, therefore I strongly suggest you just follow these steps and perform these yourself while reading this white paper.

Download and install GIT-Gui

Navigate your browser to http://git-scm.com/downloads and download the latest windows version (at time of writing 1.8.0 and about 15Mb in size). Install on your machine, I recommend keeping the installer suggested components, and suggested ‘Adjusting of PATH environment’. The latter helps when creating menu’s in VDF Studio. The ‘Configuring the line ending conversions’, leave for VDF development as checkout as-is, commit as-is.

Creating your first repository

Let’s create a GIT repository of the Visual Dataflex example Order Entry workspace. This workspace always is clean when VDF is installed but in my case, full of test and other changed code after a while. Being able to go back to the original version seems like a good idea for a first repository.

Start with navigate to and select the workspace directory then use the right click (short cut) menu, and select ‘Git Init Here’ as below.

The Git Init takes about a second. In this second it initialised a local repository in this work directory. You find that a subsequent right mouse click on the same directory now shows a different short cut menu;

Inside the Order Entry directory you see a new hidden directory ‘.git’. This directory contains the whole local repository. So if you would delete this, the repository is gone.

Although the repository is created, it has not added any of our files. For this to happen we need to stage the files and then commit. We do this in the following steps;

Go back to the workspace directory and select ‘Git Gui’ from the shortcut menu on the Order Entry directory.

Git Gui will start like below

Panel 1 shows all files that are detected to differ from the repository. As the repository is empty, this means this list contains all files. Clicking on a file name (not the icon) shows in panel 3 the changes compared with the repository version

Panel 2 has the files that you have indicated you want to stage for commit. Clicking on the icon of a file in Panel 1, shifts the file from Panel 1 ‘Unstaged Changes’ to panel 2 ‘Staged Changes’.

If this starts to sound all too complicated bare with me, it is really not that hard and there are very good reasons for doing the staging this way

When you look at the files in Panel 1, the Unstaged Changes, you find that it has a number of files you do not want to track such as IDESrc/Workspace.loc, possibly files in the data directory etc.

We can teach GIT what files to ignore by placing a file called .gitignore in the workspace directory. The content of the file is;

#Exclude the following files for Visual DataFlex Projects
####################################
programs/*.exe
programs/*.dbg
programs/*.exe.manifest
programs/webapp.log
appsrc/*.dep
appsrc/*.fld
appsrc/*.pbg
appsrc/*.pdp
appsrc/*.pkd
appsrc/*.prp
appsrc/*.err
data/*.cch
ddsrc/*.bak
idesrc/studiometadata.mtd
idesrc/workspace.loc

vssver2.scc
nppbackup

#personal preference
####################################
appsrc/*.prn
idesrc/*.dsk
 

So create this file in notepad, insert the above content and save with filename’.gitignore’ as sibling next to the ‘Order Entry.sws’ file.

If you kept Git Gui open, use the ‘Rescan’ button (or F5 key) and confirm that the unwanted files are no longer shown in the list of Unstaged changes.

Ok, now it’s time to stage all not to be ignored files. You can either select each file in Panel 1, by clicking its icon, use the shift key to select multiple and use Ctrl+T Stage to commit, or click ‘Stage changed’ button (that I marked with ‘A’ in the screenshot).

Now enter the Initial Commit Message like ‘VDF 17.0 Order entry sample as released by Data Access’. And click the ‘Commit’ button (marked with ‘B’ in my screenshot).

You noticed that the commit was really quick, and all panels are blank. You have just created a new repository, told GIT what files to ignore, and committed all other files into the repository.