08 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
      • DeleteBranch
      • Undo
      • Revert
      • AddFile
      • RemoveFile
      • Status
  • IRepository
    • Members
      • Name
      • LocalLocation
      • RemoteLocation
  • FileStatusEntry
    • Members
      • FilePath
      • FileStatus
• Enums
  • 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.FileStatus is a bitwise enumeration, so we use bitwise AND to test for equality here
    If fileStat.FileStatus 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

git.Checkout "master"

' delete our test branch
git.DeleteBranch "NewBranchName"

#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 IRepository 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 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\"

• [Optional] 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\"

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 IRepository 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 IRepository 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 [IRepositoryrepo 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"

---

###DeleteBranch

Deletes the specified local branch.

Params:

• string branch: Name of the branch to be deleted.

Remarks:

The API does not support deletion of remote branches.

Example:

' deletes all branches except master from local repository
dim branch as variant
For Each branch In git.Branches
    If branch <> "master" Then
        git.DeleteBranch branch
    End If
Next

###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.FileStatus 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.FileStatus 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.FileStatus 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.FileStatus is a bitwise enumeration, 
    '     so we use bitwise `AND` to test for equality here.

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

---

#IRepository

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

Represents the status of a given file in a repository.

##Members

###FilePath

Full file path of repository file. Default Property

###FileStatus

FileStatus value representing the state of file.

---

#FileStatus

Enumeration of possible states for a file.

Remarks:

• FileStatus is a bitwise enumeration. This means you must must use Bitwise And and Bitwise Or when checking for equality because a single FileStatus can represent several file states.

Example:

Dim fileStat As FileStatusEntry
For Each fileStat In git.Status
    ' test if one of the states for the file is modified
    If fileStat.FileStatus And Rubberduck.FileStatus.Modified Then
        Debug.Print "File " & fileStat.FilePath & " was modified."
    End If
    
    ' test for files that were NOT renamed
    If fileStat.FileStatus Or Rubberduck.FileStatus.RenamedInWorkDir
        Debug.Print "File " & fileStat.FilePath & " was not renamed."
    End If
Next

Special Note:

This enumeration is from the Lib2GitSharp project and is being used under the MIT License.

##Values

Name	Description	Value
Unaltered	The file hasn't been modified	0
Added	New file has been added.	1
Staged	New version of a file has been staged to the index.	2
Removed	The deletion of a file has been promoted from the working directory to the index.	4
RenamedInIndex	The renaming of a file has been promoted from the working directory to the index.	8
StagedTypeChange	A change in type for a file has been promoted from the working directory to the index.	16
Untracked	New file in the working directory is unknown to the index.	128
Modified	The file has been updated in the working directory.	256
Missing	The file has been deleted from the working directory.	512
TypeChanged	The file type has been changed in the working directory.	1024
RenamedInWorkDir	The file has been renamed in the working directory.	2048
Unreadable	The file is unreadable in the working directory.	4096
Ignored	The file is untracked, but it's name and/or path matches an exclude pattern in a `.gitignore` file.	16384
Nonexistent	The file doesn't exist.	2147483648