Source Control API

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

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

###Fetch

###Pull

###Commit

###Merge

###Checkout

###CreateBranch

###Undo

###Revert

###AddFile

###RemoveFile

###Status

#Repository

##Members

#FileStatusEntry