Getting the code
You can get the code from github or you can get a premade bootstrap workbook from the github stuff section in the downloads page. This is the code needed to be able to either import code from github into workbooks or to make repos from workbooks. It may be that some less sophisticated antivirus software will dislike downloading the workbook, because it needs to access your code module. If this is the case then you'll need to build a bootstrap workbook by including all the code from the repo.
Access to the IDE
The whole point of VbaGit is to automatically read and write to the VBA code. There are various security things built in to prevent that - so we have to open those up to allow VbaGit to do its work. I recommend you turn them off again once you have finished with VbaGit. You do that in Options/Trust Center/Macros, and set it like this.
Getting authenticated on Github
VbaGit uses the GITHUB API directly from VBA to commit to and read from GitHub. If you are just reading (importing public github code into Excel), you don't need to authenticate but if you are planning to write to github, then you need to set up a git hub application. I'm assuming you already have a login to be reading this in the first place. Go to github/settings/applications and create an application. You'll see a dialog like this which you should complete. You'll also get a client id, and a client secret. You'll need those, so make a note of them
Storing credentials in the registry
I never like to leave credentials in a procedure, so we'll do a one off store of credentials to your local registry, then forget all about this. You'll find a proc in the VbaGit that looks like this.
Private Function deleteThisAfterRunningOnce()
' substitute your git application clientid/secret
setGitBasicCredentials "git user name", "git password"
setGitClientCredentials "short git creds(id)", "longer git creds(secret)"
Substitute in your github login, and the application credentials, run the function, and delete it (or at lease obscure your credentials). Normally you wouldn't need your github login details for oauth2 authentication, but the api does not allow full oauth2 from non-web applications, so we have to do basic authentication (hence the need for the credentials) to be able to obtain a token to use the API. All this happens behind the scenes anyway. Obviously if you change your login details, you'll need to update and run this again.
You don't need to do any of this if you are only reading from GitHub - just if you are planning to commit projects directly from VBA.
Regardless of whether you are reading from or writing to your workbook, VbaGit is expecting to be run from a Boostrap workbook, with the other workbook you want to read from or write to open also. So you should have 2 workbooks open. VbaGit will detect which is which.
Every user has a different local environment, so before you can start you need to describe yours. You'll find this function in the VbaGit module. You'll need to change a few of these to your environment. The most likely changes needed are shown in red.
Public Function getVGSettings(Optional force As Boolean)
' get the settings - only bothers with the parse once
If force Or isUndefined(VGSettings) Then
If (isSomething(VGSettings)) Then
Set VGSettings = New cJobject
.add "TO", "c:/users/fhk647/documents/gas/Extraction/Scripts/" ''' this is the folder that will be your root local repository
.add "name", "Bruce McPherson" ''' for commit messages on git
.add "email", "firstname.lastname@example.org" ''' for commit messages on git
.add "USERAGENT", "brucemcpherson" ''' the repo owner
.add "SCOPES", "repo,gist"
.add "OWNER", .toString("USERAGENT")
.add "root", "xLiberation"
.add "app", "vbagit"
.add "basic", "basichash"
.add "client", "clienthash"
.add "VERSION", "0.0.1"
.add "README", "README.md"
.add "INFO", "info.json"
.add "DEPENDENCIES", "dependencies.md"
.add "CROSS", "cross.md"
.add "SCRIPTS", "scripts"
.add "DEPENDENCIES", "libraries"
.add "NAME", "VbaGitAddOn"
.add "StdModule", 1
.add "ClassModule", 2
Set getVGSettings = VGSettings
Reading from Github
Once you have the receiving worksheet open, you can run this , substituting the reponame for the repo you are importing from
doImportFromGit "the repo name"
Writing to the staging area
this updates the staging are you defined in the settings earlier with all the stuff that will be later committed to Git. Note that you only need to specify the main module. All the dependencies will be figured out automatically.
doExtraction "the repoName", "the list of main modules separated by commas"
As an example, I have a large workbook - cDataSet.xlsm - which contains examples about everything in this site. In the past you would have needed to download this (you still can, see Downloads
), but if you wanted a specific set of examples or class only, you would have had all the other stuff too. Using VbaGit, I've split up as below so that can VbaGit be used to create fresh, empty workbooks with just the code you need.
Public Sub doEverything()
' these are the projects in this workbook i want to separate
' base classes
doExtraction "cJobject", "cJobject"
doExtraction "cDataSet", "cDataSet"
doExtraction "excelClassSerializer", "classSerializer"
' example projects
doExtraction "excelRestLibraryExamples", "restLibraryExamples"
doExtraction "excelRoadmapper", "doRoadmapper"
doExtraction "excelGoogleSheets", "googleSheets,googleWireExample"
doExtraction "excelColor", "heatmapExamples,colorizing"
doExtraction "excelD3", "D3"
doExtraction "excelOauth2", "oAuthExamples"
doExtraction "excelParseCom", "parseCom"
doExtraction "excelProgressPar", "TestProgressBar"
' now write them to git
Committing to Git
You can either use a standard git client to commit the staging area to gitHub, or run this from within VBA
doGit "the repoName or leave blank to commit everything in the staging area to github"
- Occassionally you'll get an error 409 from the GitHub API when using doGit. This means there is some kind of timing problem going on in the GIT database, as described here - https://developer.github.com/v3/git/ . As far as I can tell the commit actually happens successfully, so it's likely that I can ignore this error, but for now I will continue to report it as an error. You can run it again if you want to be sure.
- If one if your procedures happens to have an argument that shares a name with a public procedure, then that procedure will wrongly be considered to be a dependency and it's code (and all its own dependencies) will be included in the repo. This is not a massive problem - it just means you'll get more code than you need. I'll apply a fix for this whenever I can figure something out.
You can find the repository for VbaGit here. I'll be adding to the technical writeup over time.