Source Control API

• Overview
• Example Usage
• Classes
  • SourceControlClassFactory
    • Methods
      • CreateGitProvider
      • CreateRepository
  • ISourceControlProvider
    • Members
      • CurrentRepository
      • CurrentBranch
      • Branches
    • Methods
      • Clone
      • Init
      • InitVBAProject
      • Push
      • Fetch
      • Pull
      • Commit
      • Merge
      • Checkout
      • CreateBranch
      • Undo
      • Revert
      • AddFile
      • RemoveFile
      • Status
  • IRepository
    • Members
      • [Name][repo-name]
      • [LocalLocation][repo-locallocation]
      • [RemoteLocation][repo-remotelocation]
  • FileStatusEntry
    • [Members][filestat-members]
      • [FilePath][filestat-filepath]
      • [FileStatus][filestat-filestatus]
• Enums
  • [FileStatus][filestatus]
    • [Values][filestatus-values]

#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
    ' fileStat.Status is a bitwise enumeration, so we use bitwise AND to test for equality here
    If fileStat.Status And 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] 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

Checks out the destination branch then attempts to merges the source branch into the destination branch. Finally, refreshes the IDE with the resulting files in the local repository.

Params:

• string sourceBranch
• string destinationBranch

Remarks:

• If the merge results in a conflict, the merge is aborted with git reset --hard HEAD~1 semantics. Uncommitted changes will be lost.

---

###Checkout

Checks out the specified branch from the local repository and refreshes the IDE.

Params:

• string branch: Name of the branch to be checked out.

---

###CreateBranch

Creates a new branch as a copy of the current branch.

Params:

• string branch: Name of the new branch.

Example:

Assume a repository with two branches, master and dev where the current branch is dev and we want to create a new branch test based off of master.

Debug.Print git.CurrentBranch ' => dev

' first check out the branch we want to copy
git.Checkout "master"

' then create the new branch
git.CreateBranch "test"

---

###Undo

Undoes all uncommitted changes to the specified file and refreshes the IDE.

Params:

• string filePath: Full file path to the file to undo.

Example:

' undoes all changes made to modified files
Dim fileStat As Rubberduck.FileStatusEntry
For Each fileStat In git.Status
    If fileStat.Status And Rubberduck.FileStatus.Modified Then
        git.Undo fileStat.FilePath
    End If
Next

---

###Revert

Creates a new commit reverting the last commit.

Remarks:

• Raises an error if the revert action results in a conflict.

---

###AddFile

Adds unstaged/untracked file to tracking.

Params:

• string filePath : File path of the file to be added.

Example:

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

###RemoveFile

Removes file from staging area, but leaves the file in the working directory.

Params:

• string filePath: Name of the file to be unstaged.

Example:

Dim fileStat As Rubberduck.FileStatusEntry
For Each fileStat In git.Status
    If fileStat.Status And Rubberduck.FileStatus.Untracked Then
        git.RemoveFile fileStat.FilePath
    End If
Next

---

###Status

Returns a collection of FileStatusEntries representing the current state of the current repository.

Example:

Dim fileStat As Rubberduck.FileStatusEntry
For Each fileStat In git.Status
    ' FileStatusEntry.Status is a bitwise enumeration, 
    '     so we use bitwise `AND` to test for equality here.

    If fileStat.Status And Rubberduck.FileStatus.Ignored Then
        Debug.Print "Ignored File: " & fileStat.FilePath
    End If
Next

---

#Repository

A structure representing some basic, but necessary, information about a repository.

##Members

###Name

The name of the repository. Default property

---

###LocalLocation

File path to the location of the local repository. i.e.

C:\path\to\local\repository\repoName\

---

###RemoteLocation

File path or Url of the remote repository.

Examples:

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

---

#FileStatusEntry