foxbin2prg/docs/FoxBin2Prg_git.md

FoxBin2Prg - Use with git

Documentation of FoxBin2Prg - A Binary to Text converter for MS Visual Foxpro 9

Purpose of this document

Using FoxBin2Prg with git.
See Use with SCM tools

---

Table of contents

• Introduction
• Requirements
• Tools
• Recomendations
  • git settings
  • settings per project
    • gitignore
    • gitattributes
      • Fixing line endings
    • config

Introduction

As we all know, there is a whole bunch of tools that we might use to colaborate and to version our work.
Since I use git I try to point out what I do to do as fast and comfortable work.
This document gives no workflow, in special not a workflow of git. There is no wrong or right.
If you are not familar with git, please read through this first, there are minor settings that might help a bit on later work.

Please note, if you come from a SCM system, git feels very odd. It's a complete different idea of thinking. Do yourself the favour, on git-scm you find pro git. Read and work at least through the first three chapters. No matter, if you are using git on bash or GUI

There is a bunch of common traps to avoid - like storing credentials to github - I recommend Oh my git! too.

For almost anything you don't need a server, even for colaborating a storage is enough. I use a server - a self hosted copy of gitlab - but this basically for access restrictions and remote work.

Do not hesitate to try anything. Always remember, git is just a couple of files inside your project folder. CTRL+C, CTRL+V on Explorer might save the day. ;)

Requirements

#1

A copy of FoxBin2Prg.
Or Install via Thor, this keeps you on the latest version.

#2

It might be a good idea to have a copy of git.
If you download a setup or clone the code and compile yourself is up to you. I prefer the setup - it's a nice package with all bells and whistles one might need on command line. See git settings for stuff to set during setup.

#3

I prefer it on the bash. Some of the reasons

• It's complex. If a GUI does something wrong, you need to go to the bash anyway.
  • Note, every git-GUI is simple a tool that needs git to run original commands.
• It's simple. For day to day work, it's some easy to learn commands.
• The little visual need I have, and yes, some commands too, run on gitk, what ships with git for windows
• bash, because all help out of the web comes in 'nix style, rethink to the windows world is to much work.
• working on the command line gives ideas of doing the stuff using the Fox, and we are programmmers, are we?
• since we have those extra step to create Text and Binary around the git repo, any GUI is awkward.

The use of git on the command line is not a taste all like. So if you need a GUI tool, it's your choice. git-scm.org list a lot, and there might be more out.
Or use the Fox and build your own - it's nothing then some commands and handling text files.

Tools

To integrate git into the Fox VFPX lists some tools.
I'm somehow into the Bin 2 Text extension, but then I know this best.

A nice graphical compare / mergetool is nice too have - check if and how to integrate first, and also if the code monkey creating the interface understands git. Some try to use it like SCM, what ends up odd.

Recomendations

Short about git

The first one must understand here, git is set up to deal with text based files. It's a Linux tool developed to deal with Linux - the Kernel code.
Highly sophisticated, neat, fast.
So storing binaries into it is something one should avoid as far as possible.

There is stuff where one might not circumvent it - like pictures.

Text representation of VFP's binaries

And there is the oddness of VFP sources. Storing those to git is as wrong as it could be.

• Bloat of the repo
• No trace of changes
• Not mergeable

And if there is one what is realy cool on skipping locking servers, it's colaboarting. Even on VCX's.

Solution

With thanks to Fernando FoxBin2Prg comes into play.
One might be reluctant to dropping the binaries - but I do for years and it works like a charm. Do not play around with text-to-look-up-changes ideas storing both Text and Binary. Just merge, compare like a normal text based language.
The only thing one must learn (and remember, even after odd merges) is to run FoxBin2Prg wrapping any git operation.

git would even allow to hook FoxBin2Prg to run after some git operations, but this might be a killer.

I try to show what to set to keep it running as Text - only storage.

Class libraries

I know there is a lot how to store a class. Microseconds here and there. Folks, hardware is cheap. There is no sense in counting ticks and bits any more. I'm grown up that way, but.
Dealing with the FoxBin2Prg.prg is the limit. If I imagine to have one of my larger vcx's like this in a merge view - no.

Just split up the vcx's into single classes using FoxBin2Prg for git purposes. It's like a charm on merge and diff. Also on blame.
If you go for the lib.baseclass.classname.vc2 or lib.classname.vc2 style is a matter of taste. I can see baseclass on classname, so there is not much value, other might think different. But split into classes makes life easy.
This is to be done in the config file, setting UseClassPerFile option to 1 or 2.

Forms

Side effect of splitting VCX is that SCX will be split into 3 files too. I have no idea if there is some use of it - I just do classes. If you like it separated from VCX - let me know.

Databases

Splitting DBC is possible too. My approach does not touch the DBC structure (it's meta data only) in the source over decades, so there is little use. So I've added an option to inhibit splitting DBC while splitting VCX/SCX.

Tables

Since nobody brought up the .NULL. problem, it looks like it's not commonly used. It works for me for a while now and I found no problems so far.

Note

I do DBF / DBC to text and vice versa for a while now, but still with the binaries. I found no problem yet, except the binaries are a pain on merges. What I see is that a synthetic PK is helpfull, not all the lookups had one. So I added one just for the purpose of merging.

Others

All the other table-based-sources of VFP work seamless as Text. No fuzz.

git settings

Those settings are mainly per user (in git terms global)

---

Assuming you do a fresh install of git, you will be asked questions over questions. The most you left unchanged.
The one I recommend is the dealing with line endings. You know all the odd uses of LF and CR. git offers to alter this while dealing with your files. I recommend not. Just Check in as is, check out as is while installing git for windows. This will keep your files, and any modern editor or WEB UI will not care anyway.
If you missed on install - just install again.
If you have an issue with CRLF/LF so that you will get odd commits due to changing line endings, see Fixing line endings.

Do not forget to set up username, email and a ssh key. The following script sets up git and creates the key. It will copy the public key to clipboard too - ready to paste into github. Anyway, you allways can copy the contents of ~/.ssh/id_rsa.pub. Note, this will clear data, so do not run twice or on the wrong comp. A key overwritten is lost!

#!/bin/sh
#--------------------------------------------
#  create_rsa.sh
#
#	Abstract:
#   create an rsa ssh key an ~/.ssh
#   with options to git
#
#   set email and domain in this file
#
#   Written by SF
#   May 2018
#--------------------------------------------

user=="your name"
email="$user@$domain"

cd ~
if test -d .ssh
then
 cd .ssh
 rm id_rsa.*
 rm id_rsa
else
 mkdir .ssh
 cd .ssh
fi

ssh-keygen -t rsa -b 4096 -C "$email"
cat ~/.ssh/id_rsa.pub | clip
 
git config --global user.name "$user"
git config --global user.email "$email"

Depending on your needs you might set a password or not.

Note

For some odd reasons, the people on git-scm are going the way of evil. If you start the Setup of git, all depends who you are. If you not check Run as Adminstrator, it will install into your user folder. Even if installed in Programs folder earlier!

Settings per project

Those settings are mainly per project (repository) (in git terms local). One can argue to put the one or other in different levels. I recommend those inside the project to keep the repository as self contained as possible.

gitignore

The .gitignore file controls which files go not into the git repository by default. It goes by folder with inheritance. If you understand the inheritance of .gitignore, you grok FoXBin2Prg.cfg and vice versa. Very close.

But git would not be git if one could not teach .gitignore to define the files included. Again, see pro-git.

Creating the file might be a bit odd on MS Windows (Windows dislikes just extension). Created once, most editors will not complain. In case, just open the bash in your projects base folder (Explorer, context menu) and enter touch .gitignore.

An example for Text only use.

#.gitignore
#exclude general
*.*

#include general
#dbx data
#!*.dbf
#!*.cdx
#!*.fpt

!*.dbc
!*.dc[tx]

#grafics
!*.bmp
!*.msk
!*.ico
!*.cdr
!*.cur

#programms
!*.prg
!*.fpw

#header
!*.h

#libs (by FoxBin2Prg)
#!*.vc[xt]
#!*.pj[xt]
#!*.fr[xt]
#!*.mn[xt]
#!*.sc[xt]
#!*.lb[xt]

#FoxBin2Prg
!*.vc2
!*.pj2
!*.fr2
!*.mn2
!*.sc2
!*.lb2
!*.d[bc]2

#include special
#default git
!*.gitignore
!*.gitattributes
!/desktop.ini
#desktop.ini. usless? no! it keeeps the folder icon!

#diverse
!*.reg
!/FoxBin2Prg.cfg
!README.md

#exclude special again
foxuser.*
_command.prg

Also this approach ignores any bak / log / tmp / err files by default.

gitattributes

The .gitattributes file controls some things that might be set to as local computer / user / repository (via git config). Note, using git config to alter the behaviour of the repository will still be local to your computer, so a remote computer is not influenced. IOW, this is not pushed.
It should be constant to the repository, no matter the local settings of any collaborator. This while we should use .gitattributes file and included into the repository.

For VFP purposes, .gitattributes controls the processing of line ending on git commit / checkout.
As mentioned above git might manipulate CRLF and LF. If the settings are different on different computers , it might checkout with LF instead of CRLF. This creates useless files in the commit, but also might create havoc using the files. See GoFish for an example.
To solve this, add a .gitattributes file to any of your projects, next to the .gitignore file. It should look like this:

#.gitattributes
# disable newline conversion on checkout with no conversion on check-in for all files
* -text

If you have a project running, check the line endings and make shure they follow DOS standard CRLF:

Fixing line endings

If you run into the problem that you have set up different computers different for dealing with line endings so commits of all files or all lines of a file without reason, you might need to change to git to keep CRLF and set your files line endings to CRLF.

• create a backup of your folder
• create .gitattributes file as above run following lines in bash:

git add . -u
git commit -m "Saving files before refreshing line endings"
git add --renormalize .
git commit -m "Normalize all the line endings"

Note: You must do this to every repository and, if there are several branches of a repository, with every (active) branch.
Note: Be careful, this will not alter any older commit, so git reset (or the like) to an old commit could create the problem again. Recreating .gitattributes and the code snippet should solve the problem, for single files like:*

git add --renormalize filename
git commit

FoxBin2Prg config

The config of FoxBin2Prg using FoxBin2Prg.cfg files is relative simple. As you might see above, I carry the file within the repo.
The good on this is, if I change my mind and alter settings in it, FoxBin2Prg will find the setting that fit to the data on each commit. If I have to checkout old stuff - the setting will fit. See Configuration file(s) for detailed information.

---

This project is part of VFPX.

---

Last changed: 2026/06/21