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 of the API:

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

#Classes

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

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

InitVBAProject

Push

Fetch

Pull

Commit

Merge

Checkout

CreateBranch

Undo

Revert

AddFile

RemoveFile

Status

##Repository

###Members

##FileStatusEntry

#Enums