Skip to content

Source Control API

Jump to bottom Edit New page
Christopher McClellan edited this page Feb 18, 2015 · 31 revisions

#Overview

The source control library not only gives you the ability to interact with Git repositories by cloning, branching, committing, pushing, etc., but also takes care of the ugly business of getting your code modules into and out of your VBA Project for you. The concept of this library is not to provide full source control functionality, but an easy way to expose your VBA Projects to basic source control functionality.

It is recommended that you not pass the Active VBProject to the SourceControlProvider. It becomes a race condition of sorts where you're actively modifying the very code that is currently executing.

The API is a beta at this point and still subject to change.

#Example Usage

Dim factory As New Rubberduck.SourceControlClassFactory
Dim repo As Rubberduck.IRepository
Dim git As ISourceControlProvider

Dim xl As New Excel.Application
xl.Visible = true
Dim wb As Excel.Workbook

Set wb = xl.Workbooks.Open("C:\Path\to\workbook.xlsm")

' create class instances to work with
Set repo = factory.CreateRepository(wb.VBProject.Name, "C:\Path\to\local\repository\SourceControlTest", "https://github.com/ckuhn203/SourceControlTest.git")
Set git = factory.CreateGitProvider(wb.VBProject, repo, "userName", "passWord")

' Create new branch to modify.
git.CreateBranch "NewBranchName"

' It is automatically checked out.
Debug.Print "Current Branch: " & git.CurrentBranch

' add a new standard (.bas) code module and a comment to that file
wb.VBProject.VBComponents.Add(vbext_ct_StdModule).CodeModule.AddFromString "' Hello There"

' add any new files to tracking
Dim fileStat As Rubberduck.FileStatusEntry
For Each fileStat In git.Status
    If fileStat.Status = Rubberduck.FileStatus.Added Then
        git.AddFile fileStat.FilePath
    End If
Next

git.Commit "commit all modified files" 

' Revert the last commit, throwing away the changes we just made.
git.Revert

#SourceControlClassFactory

Exposes the ability to create new instances of classes in the API.

##Methods

###CreateGitProvider

Returns:

A new GitProvider of type ISourceControlProvider.

Params:

  • VBProject project
  • [Optional] [IRepository][repo] repository
  • [Optional] string userName
  • [Optional] string passWord

Remarks: If supplying a username and password, a Repository object must also be supplied. Failure to do so results in an ArgumentNullException. If supplied a username without a password, the username is ignored.

Example:

Dim factory As New Rubberduck.SourceControlClassFactory
Dim git as New ISourceControlProvider

' these are valid
Set git = factory.CreateGitProvider(wb.VBProject)
Set git = factory.CreateGitProvider(wb.VBProject, repo)
Set git = factory.CreateGitProvider(wb.VBProject, repo, "username", "password")

' this will result in a runtime error
Set git = factory.CreateGitProvider(wb.Project, userName:="username", passWord:="password)

' this will work, but `userName` will be ignored
Set git = factory.CreateGitProvider(wb.Project, repo, "username")

###CreateRepository

Returns:

A new Repository of type IRepository.

Params:

  • string name: Repository name. Should correspond to the VBProject.Name.

  • string localDirectory: Path to the location of the local repository.

    • `"C:\Path\to\repository"

  • string remotePathOrUrl

    • Url or file path to the remote repository.
      • "https://github.com/username/repository.git"
      • "C:\Path\to\remote\repository\"
      • "\\server\share\path\to\remote\repository\"

Remarks:

Example:

Set repo = factory.CreateRepository("SourceControlTest", "C:\Path\to\local\repository\SourceControlTest", "https://github.com/ckuhn203/SourceControlTest.git")

#ISourceControlProvider

The bread and butter. This exposes all of the functionality of implemented providers to your VBA Project. Implementations of this interface take care of importing/exporting code to/from the VBA Project to/from the local repository. New instances of providers are created via the SourceControlClassFactory.

##Members

###CurrentRepository

The Repository object representing the repository currently being worked with.

###CurrentBranch

The name of the current branch.

###Branches

Collection of the names all local branches.

Example:

dim branch as variant
For Each branch In git.Branches
    Debug.Print branch
Next

##Methods

###Clone

Clones a remote repository to the local file system.

Returns:

A new IRepository object.

Params:

  • string remotePathOrUrl

    • Url or file path to the remote repository.
      • "https://github.com/username/repository.git"
      • "C:\Path\to\remote\repository\"
      • "\\server\share\path\to\remote\repository\"

  • string workingDirectory: File path to the directory where the repo should be cloned to.

Remarks:

The CurrentRepository and VBProject have no affect on the results of this method. It is semantically equivalent to calling

$ cd C:\path\to\new\repo
$ git Clone https://github.com/username/repository.git

###Init

Creates and returns a new repository in/from the given directory.

Params:

  • string directory: File path where the repository will be initialized.
  • [Optional] bool bare: Specifies whether or not to create a bare directory. Defaults to false.

###InitVBAProject

Creates a new repository and sets the CurrentRepository property from the VBProject passed to the ISourceControlProvider upon creation.

Returns:

A new IRepository object.

Params:

  • string directory: File path where the repository will be initialized.

Remarks:

  • Copies all of the code from the VBProject into the destination directory and then initializes a new non-bare repository.

Example:

'initialize a new repo from an existing VBA Project in an existing workbook

Dim factory As New Rubberduck.SourceControlClassFactory
Dim repo As Rubberduck.IRepository
Dim git As ISourceControlProvider

Dim xl As New Excel.Application
xl.Visible = true
Dim wb As Excel.Workbook

Set wb = xl.Workbooks.Open("C:\Path\to\workbook.xlsm")
set git = factory.CreateGitProvider(wb.VBProject)

Dim repo As IRepository
Set repo = git.InitVBAProject("C:\path\to\new\repository\")

' IntiVBAProject also initializes the SourceControlProvider's repository.
Debug.Print repo.LocalLocation
Debug.Print git.CurrentRepository.LocalLocation

' so now we can work with the repo as if we passed it a IRepository object to begin with

'...

###Push

Pushes local commits on the CurrentBranch to the equivalent branch of the tracking remote.

Equivalent to

$ git push origin branchName

Where branchName is the current branch.

###Fetch

Fetches the specified remote for tracking.

Params:

  • [Optional] string remoteName

Remarks:

  • If remoteName is not supplied, Fetch default to the "origin" remote.

###Pull

Performs a $ git pull operation, then refreshes the code files in the IDE from the local repository.

###Commit

Refreshes the local repository with the code files from the IDE, stages all modified files, and then commits to the local repository.

Params:

  • string message: The commit message.

Remarks:

Semantically equivalent to calling git status, staging each modified file with git stage C:\path\to\file.txt, and then committing with git commit -m "some message".

###Merge

###Checkout

###CreateBranch

###Undo

###Revert

###AddFile

###RemoveFile

###Status

#Repository

##Members

#FileStatusEntry

Twitter @rubberduckvba

  • Meta meta meta
Clone this wiki locally