Getting started with VbaGit

For an overview of what VbaGit is, please read Integrate VBA with Github

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)"
End Function

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.

The scenario

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.

Your settings

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
            VGSettings.tearDown
        End If
        Set VGSettings = New cJobject
        With VGSettings.init(Nothing)
            With .add("EXTRACT")
                .add "TO", "c:/users/fhk647/documents/gas/Extraction/Scripts/"  ''' this is the folder that will be your root local repository
            End With
            With .add("GIT")
                With .add("COMMITTER")
                    .add "name", "Bruce McPherson"                              ''' for commit messages on git
                    .add "email", "bruce@mcpher.com"                            ''' for commit messages on git
                End With
                .add "USERAGENT", "brucemcpherson"                              ''' the repo owner
                .add "SCOPES", "repo,gist"
                .add "OWNER", .toString("USERAGENT")
            End With
            With .add("REGISTRY")
                .add "root", "xLiberation"
                .add "app", "vbagit"
                .add "basic", "basichash"
                .add "client", "clienthash"
            End With
            With .add("APP")
                .add "VERSION", "0.0.1"
            End With
            With .add("FILES")
                .add "README", "README.md"
                .add "INFO", "info.json"
                .add "DEPENDENCIES", "dependencies.md"
                .add "CROSS", "cross.md"
            End With
            With .add("FOLDERS")
                .add "SCRIPTS", "scripts"
                .add "DEPENDENCIES", "libraries"
            End With
            With .add("PROJECT")
                .add "NAME", "VbaGitAddOn"
            End With
            With .add("VBA")
                With .add("TYPES")
                    .add "StdModule", 1
                    .add "ClassModule", 2
                End With
            End With
        End With
    End If
    Set getVGSettings = VGSettings
End Function

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"
    
    ' utilities
    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
    doGit
    
End Sub

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"

Issues

  • 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.

Now take a look below for more on this subject

Technical writeup

You can find the repository for VbaGit here. I'll be adding to the technical writeup over time. 

Hover over the image below to see the full code for the main VbaGit module is below, and the documentation is here.


For help and more information join our communityfollow the blog or follow me on twitter . For how to do this for Google Apps Script, see Getting your apps scripts to Github

You want to learn Google Apps Script?

Learning Apps Script, (and transitioning from VBA) are covered comprehensively in my my book, Going Gas - from VBA to Apps script, available All formats are available now from O'Reilly,Amazon and all good bookshops. You can also read a preview on O'Reilly

If you prefer Video style learning I also have two courses available. also published by O'Reilly.
Google Apps Script for Developers and Google Apps Script for Beginners.



Comments