Ivercy Git Connector
After many years of staving of requestors of Git connectivity for Ivercy and referring to the rather unsatisfying Git MSSCCI implementations the situations is about to change.
We are working on a custom Git connector utilizing the LibGit2Sharp library. In fact, we just released the first preview/beta version of this connector. – If you want to try it, you need to download Ivercy beta version 1.4.1 (or later) from our download page (beta releases are on the lower half of the page).
This text here contains in-depth technical details about our Git Connector. We also have a more lightweight Getting Started Guide for the Git Connector.
Warning – Beta Stage
The current implementation of our Git connector (as of 2021-06-14) is in beta stage. We believe that our implementation is reasonably reliable, but you should take good care when evaluating it in a real development environment. Please be aware that there still may be serious bugs and unforeseen situations/behavior when working with the new Git connector. Furthermore, there may be significant changes in behavior and capabilities in upcoming versions without prior notice.
There are also a couple of know limitations and peculiarities as described further down in this text.
Configuration and Setup
Before you can use the Ivercy.git connector, you need to add some required files to your installation and adjust the configuration.
Prerequisites
The Ivercy.git connector depends on several prerequisites installed on your computer.
Microsoft .Net Framework 4.6 or newer
LibGit2Sharp only works with the Microsoft .Net Fx version 4.6 or newer. Make sure you have got this installed on your computer.
Ivercy must be registered to use the .Net 4 Runtime
Beginning with Ivercy version 1.4.1 the setup will default to register Ivercy with the .Net 4 Runtime. If you installed Ivercy for the first time with this release no don’t need to take any action.
If you installed previous versions (1.4.0 or older) of Ivercy and also have the .Net 2 Runtime on your computer, Ivercy will be registered to use this runtime. (You can check in the Ivercy About dialog.) Then you should uninstall the previous version of Ivercy before installing version 1.4.1 to make sure it gets registered with the correct .Net 4 Runtime.
LibGit2Sharp
Starting with Ivercy version 1.4.3 the LibGit2Sharp 0.26.2 assembly and the required native binaries are included in the Ivercy setup. Normally you do need to download dependencies manually. The following stroke-through text is only relevant if you want to use a different version of LibGit2Sharp.
Our connector was developed against LibGit2Sharp version 0.26.2. We recommend you navigate to the LibGit2Sharp nuget page and use the “Download package” link on the right-hand side of the page. Use WinRar, 7zip, or a similar program to open or unpack the downloaded nuget-file. Then extract the LibGit2Sharp.dll file from the path \lib\net46 and put it into the Ivercy program files directory, usually %LOCALAPPDATA%\Ivercy\Ivercy.
LibGit2Sharp.NativeBinaries
LibGit2Sharp depends on the LibGit2Sharp.NativeBinaries which are a wrapper around the native LibGit2 library. The version of the LibGit2Sharp.NativeBinaries must match what the version of LibGit2Sharp you downloaded depends on. This will be indicated on the LibGit2Sharp nuget page in the “Dependencies” section. For LibGit2Sharp 0.26.2 you need version 2.0.306 of the LibGit2Sharp.NativeBinaries. Download them from the LibGit2Sharp.NativeBinaries v2.0.306 nuget page. Extract the git2-106a5f2.dll (the file name will be different if you downloaded another version of the NativeBinaries) file either from the path \runtimes\win-x64\native or \runtimes\win-x86\native (depending on your Access bittnes) and put it into the Ivercy program files directory, usually %LOCALAPPDATA%\Ivercy\Ivercy.
Configuration Options
Open the Ivercy configuration dialog, select the “New Project Template” tab and then change the following properties. – These are the template settings for all projects created from or added to a repository. If you also work with MSSCCI-Provider based projects, you should keep in mind to readjust these before creating a MSSCCI based project.
Internal
SccProxyLibrary: ivercy.git.dll
This switches Ivercy’s source code control connectivity to the new Git connector.
(There will be a warning about changing this setting. If you read this page here, you can confirm with OK.)
Workflow
ExcludeCheckedoutFromGetLatest: No
External Programs
The settings for DiffCommandline, MergeCommandline, and MergeProgram in the External Programs section should be valid for your Diff-/Merge-Tool of choice. See the documentation for these settings in the Ivercy Configuration documentation.
Example values for Sourcegear DiffMerge are:
DiffCommandline: "{accFile}" "{baselineFile}"
MergeCommandline: -m "{accFile}" "{baselineFile}" "{repoFile}" /result="{outputFile}" /t1="{accTitle}" /t2="{outputTitle}" /t3="{repoTitle}"
MergeProgram: "C:\Program Files (x86)\SourceGear\Vault Client\sgdm.exe"
Project Configuration Options
After you created your first Access project from a Git repository you may optionally set the following settings in the “Current Project” tab of the Ivercy configuration dialog.
MSSCC API Settings
Warning: The features and behavior described in this section are still experimental. They may change in the future without warning.
GitFetchUpstreamBeforeManualRefreshStatus: Yes/No (Default: No)
If set to ‘Yes’ the Refresh Status command in the Ivercy UI will not only update the status based on the local Git repository but will also fetch changes from a remote Git repository and will include detected changes in the local branch of that remote repository as ‘Out-of-Date’ status results in Access. (Requires GitRemoteName and GitUpstreamLocalBranch to be also configured!)
Known issue 1: Even though the name and the description of this property indicates this only applies to manual Refresh Status operations, the Ivercy SCC connector layer currently cannot distinguish between a manual and an automatic operation. So, this will be executed on every status refresh and may negatively affect performance. This was fixed in Ivercy v1.4.3.
Known Issue 2: The behavior only works as intended if your current branch is only ahead or behind the Remote. If your branch is ahead and behind the Remote at the same time, all modified objects will be marked as ‘out-of-date’ even if they are ahead in the HEAD and by that current in your Access environment. Should be fixed in the current v1.4.1 release.
GitRemoteName: Name of a Remote, configured in your local Git repository.
If GitFetchUpstreamBeforeManualRefreshStatus is set to ‘Yes’, Ivercy will fetch changes from this Remote when the SCC-Status in Access is updated.
GitUpstreamLocalBranch: Name of the branch containing changes fetched from a Remote upstream repository (usually defined by GitRemoteName). Changes between this local branch and your current branch will be included as ‘Out-of-Date’ status results in Access.
Peculiarities and Limitations
Terminology and Workflow
Ivercy was originally built to support source code control providers built on the Microsoft Source Code Control Interface (MSSCCI) specification and to be mostly compatible with Microsoft’s own SCC-Plug-In for Microsoft Access. This heritage is deeply ingrained in Ivercy’s architecture, and the terminology used in the UI. This will feel odd and requires some mental translation if you are used to Git terminology, but it is not a limitation of capabilities, as I elaborated years ago in the The suitability of MSSCCI for Edit-Merge-Commit.
The hard limitations of Git capabilities and quirks in the workflow with our provider are caused by the special situation with development in Microsoft Access since all source files need to be synchronized with the binary Access files.
git pull vs git fetch
If you work with a remote Git repository setup as Remote and use the git pull command to pull the changes into your local repository this will also update the working folder, which Git and Ivercy share, with all changes pulled from the Remote. By design, Ivercy has no capabilities to compare the Access object inside Access and the file representation of that object in the working folder. Ivercy assumes total sovereignty over its working folder. For any SCC operation, including file comparison, Ivercy may write the text file of any Access object to the working folder, overwriting anything that is already there. – This may result in unexpected status indications by Git and may have other side effects we did not discover yet.
This may also apply to the git checkout command if you use it independently in another git client operating on the same repository!
Whenever you have to use git pull or git checkout on the working folder of your Access project (remember to commit/check-in your pending changes first!) you should use Get Latest Version inside Access to load all updated objects into Access.
If you use git fetch instead of git pull, Git will download remote changes to a dedicated branch in your repository, but it will not update the working folder. If you configured Ivercy’s GitUpstreamLocalBranch option (see above), Ivercy will indicate any objects that were modified on the Remote by applying the out-of-date status indicator to the Access object. This gives you a much clearer idea what to expect and which objects to reload into Access with Get Latest Version, after a subsequent git merge.
No staging
As far as you as a user are concerned, you will not use anything equivalent to git stage / git add ever. Just assume the Git Index does not exist. Every SCC write operation you initiate within Access via Ivercy will be directly committed to repository.
(Internally, Ivercy does use the index for before committing changes to repository. However, each stage operation will be immediately followed by a commit.)
Separate working folder
We strongly recommend you use a working folder separate from your Git repository.
Despite my willingness to embrace new concepts and techniques, I personally still think, the design decision to put the Git repository below its working folder in the folder hierarchy by default is a questionable one.
As elaborated in the pull vs fetch section, Ivercy assumes total sovereignty over its working folder. This puts us at unease when the repository is located inside this folder structure. We are not aware of any situation where Ivercy could overwrite the Git repository inside the working folder. Nonetheless, as measure of precaution, we strongly recommend putting your repository and the working folder in separate locations.
Branching and Merging
One major advantage of Git over many other source code control systems is its lightweight and fast approach to branches and merges.
When working on a Microsoft Access project, there is a major impediment to this. You don’t work directly on the files in the working folder but on objects inside Access, which need to be synced from and to the file system. This makes switching branches and merging of branches much more cumbersome than usual with Git.
Currently the prudent advice to switching or merging branches, it to do this outside of Access with the Git client of your choice and then completely rebuild the Access project when you are done.
An alternative and experimental approach, at least to switching branches without merge, could be to use different working folders for different branches. Ivercy’s Git connectivity should support this without major drawbacks. (Except Git freaking out about missing files not part of your Access project). However, use this with care. Our Git experience is not sufficient to fully grasp all potential implications of this approach.
Ivercy Object Status
Checked-In vs Checked-out
As there is no “Checked-in” status for files managed with Git, you’ll never see the typical blue lock icon for any Access object in a controlled database. All Access objects are “checked out (shared)” by default. If you check-in this will commit changes to the Git repository, but the objects will stay checked-out.
Out-of-Date
We are not aware of any probable scenario in which a file in a Git working folder will get out-of-date in the MSSCCI sense of the term (updated in the repository, old in the working folder). Also, Git appears not have any status reporting on this situation.
With the Ivercy Git Connector the Out-Of-Date status will become visible in Access when there is a new version of a file in the repository and in the working folder but has not been loaded into the Access database.
It also will be displayed in combination with the MSSCC API Settings (described above) for Remotes and/or a git fetch command.
Issues with the History
In some rare situations you may notice unexpected behavior in the History View.
- History view may be incomplete when a file was renamed, "Action" might be missing.
- History view may be incomplete when a file was deleted and later restored, after a time without the item in the tree. The history may be cut-off at that point.
- Very rarely a comparison between revisions might not be possible (Error message: “Object reference not set to an instance of an object. Failed to get file content for revision”)
At the core of these issues are issues/limitations of libGit2Sharp and potentially even Git itself, as documented in Repository.Commits.QueryBy is missing changes #1752 and Return all changes to a file when using Repository.Commits.QueryBy(path) #1753.