Debugging GitDeltaDeploy with a Sitecore TDS project

As an open-source project, I wanted to enable developers to easily debug the GitDeltaDeploy extension themselves, in case of any issues or surprise edge cases they come across.

As GitDeltaDeploy is an open-source project, developers are free to download the Github repo and directly debug and edit as they wish.
It is a third party extension that I maintain in my spare time, so it isn’t affiliated with Hedgehog or Sitecore, and their support teams should not be contacted for help with this.
Instead I encourage developers to follow the debugging steps mentioned here, and to discuss their projects on the #tds channel in the Sitecore Community Slack.

Out of the box, the extension will create files that it uses for auditing whether or not items should be added to the deployment.
It does this by creating a ‘ChangedItemFiles.txt‘ file in a ‘DeltaArtifactsFolder‘ location (which is set as {project}/Report/ChangedItemFiles.txt by default), then by saving a ‘LastDeploymentGitCommitId.txt’ file in the same location for future delta deployments.

ChangeItemFiles.txt
This contains a list of the files that have changed in Git for your ‘Delta’ deployment.

This is the output of the Git command
git diff -r –name-only –no-commit-id $(PrevIdentifier)..$(GitCurrentCommitID) “*.item”

The output into this file will be a list of files that have changed in Git between ‘PrevIdentifier‘ (either a commit ID or git tag) and ‘GitCurrentCommitID‘ (the Git HEAD tag, given by the command git rev-parse HEAD).

 

LastDeploymentGitCommitId.txt

At the end of the processing, whatever was stored as $GitCurrentCommitID (which comes from the command git rev-parse HEAD) is stored in this file.
This is so the next time the delta deployment is run, it can check this file as ‘the latest commit at the last time we deployed’, so that the next delta can be taken from that point in time.

It should be noted that this is just a file, that may not persist for your builds, depending on how you build and what you’re using to build.
For example, you may being performing cloud builds, that essentially do a ‘clean’ build every time. In that case, the file won’t exist ‘the next time’ the build is run. Instead, you would need a method of persisting the ‘LastDeploymentGitCommitId’ somewhere, like as a deployment variable or source control tag, and passing that in to the build (like /p:LastDeploymentGitCommitID=commithash0123456789) so that GitDeltaDeploy recognizes that value as the next build’s starting point instead.

 

DeltaDeployCompare.txt

As part of the NuGet package, I also included a DLL build from a Debug configuration. This ‘DEBUG’ DLL contains additional logic to output another text file ‘DeltaDeployCompare.txt‘ in the DeltaArtifactsFolder location. The file will store what it’s found in Git as changed (like the ChangedItemFiles.txt file above), as well as the adjudication that GitDeltaDeploy made on each item as to whether or not to include it in the deployment. This way you can see the full list of what was added, and what was NOT added in the delta deployment.

If you wish to gain this extra information in your delta deployment, simply replace the ‘Hedgehog.TDS.BuildExtensions.GitDeltaDeploy_DEBUG.dll‘ with the ‘Hedgehog.TDS.BuildExtensions.GitDeltaDeploy_DEBUG.dll‘ in the package’s ‘build’ folder.
If you’re using the ‘HedgehogDevelopment.TDS‘ build components NuGet package, you will also need to copy this new debug DLL to the ‘HedgehogDevelopment.TDS.x.x.x.x/build‘ folder (again naming the DLL without the _DEBUG).

Then when you run a build, you will see the DeltaDeployCompare.txt file that you can check to see how the delta decision was made on each item.

MSBuild Structured Log Viewer
One of the difficult things about this project is dealing with MSBuild when only coming back to it once in a while. I found it was difficult to get back the context of what I worked on months ago… and I needed my head to be into the project for a while to fully understand what’s going on….even for the things that I initially wrote.

Therefore, I am now using the MSBuild Structured Log Viewer application to properly see the order in which MSBuild tasks are applied. This has allowed me to see how a project is being built with GitDeltaDeploy, and to determine if any steps were missed, or if there are other problems causing issues.

As part of your debugging, you can add the switch /bl to the call to MSBuild. This will create an msbuild.binlog file that can be loaded into the MSBuild Structured Log Viewer application where you can see the order in which the GitDeltaDeploy tasks were executed.

You can also directly load the solution instead, and run the MSBuild command from there.

With the msbuild.binlog file, developers can seek assistance on their build by passing this over to discuss the order of the MSBuild tasks in their project.

Remember to try out these debugging tips, and to discuss you findings and issues on the #tds channel in the Sitecore Community Slack.