Skip to content

Commit af57065

Browse files
Add _diff.ps1 tool for reviewing step template script changes (#1664)
1 parent 74ec81e commit af57065

3 files changed

Lines changed: 112 additions & 0 deletions

File tree

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,6 @@ scriptcs_packages.config
1212
step-templates/*.ps1
1313
step-templates/*.sh
1414
step-templates/*.py
15+
diff-output/
1516
/.vs
1617
!.vscode

README.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,26 @@ Read our [contributing guidelines](https://github.com/OctopusDeploy/Library/blob
1818
Reviewing PRs
1919
-------------
2020

21+
### Reviewing script changes
22+
23+
Step template JSON files embed scripts as single-line escaped strings, making diffs hard to read. Use the `_diff.ps1` tool to extract old and new scripts into separate files you can compare in your diff tool:
24+
25+
```powershell
26+
# Compare ScriptBody against previous commit
27+
.\tools\_diff.ps1 -SearchPattern "template-name"
28+
29+
# Compare against a specific commit or branch
30+
.\tools\_diff.ps1 -SearchPattern "template-name" -CompareWith "master"
31+
```
32+
33+
This outputs readable files to `diff-output/`:
34+
- `template-name.ScriptBody.old.ps1`
35+
- `template-name.ScriptBody.new.ps1`
36+
37+
Also handles `PreDeploy`, `Deploy`, and `PostDeploy` custom scripts if present.
38+
39+
### Checklist
40+
2141
When reviewing a PR, keep the following things in mind:
2242
* `Id` should be a **GUID** that is not `00000000-0000-0000-0000-000000000000`
2343
* `Version` should be incremented, otherwise the integration with Octopus won't update the step template correctly

tools/_diff.ps1

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
param
2+
(
3+
[Parameter(Mandatory=$true)]
4+
[string] $SearchPattern,
5+
6+
[Parameter(Mandatory=$false)]
7+
[string] $CompareWith = "HEAD~1",
8+
9+
[Parameter(Mandatory=$false)]
10+
[string] $OutputFolder = "diff-output"
11+
)
12+
13+
$ErrorActionPreference = "Stop";
14+
Set-StrictMode -Version "Latest";
15+
16+
$thisScript = $MyInvocation.MyCommand.Path;
17+
$thisFolder = [System.IO.Path]::GetDirectoryName($thisScript);
18+
$repoRoot = [System.IO.Path]::GetDirectoryName($thisFolder);
19+
20+
$stepTemplateFolder = [System.IO.Path]::Combine($repoRoot, "step-templates");
21+
$stepTemplates = [System.IO.Directory]::GetFiles($stepTemplateFolder, "$SearchPattern.json");
22+
23+
if ($stepTemplates.Length -eq 0)
24+
{
25+
Write-Error "No step templates found matching '$SearchPattern'";
26+
return;
27+
}
28+
29+
Import-Module -Name ([System.IO.Path]::Combine($thisFolder, "StepTemplatePacker")) -ErrorAction "Stop";
30+
31+
$outputPath = [System.IO.Path]::Combine($repoRoot, $OutputFolder);
32+
if (-not (Test-Path $outputPath))
33+
{
34+
New-Item -ItemType Directory -Path $outputPath | Out-Null;
35+
}
36+
37+
$scriptProperties = @(
38+
@{ Name = "ScriptBody"; Property = "Octopus.Action.Script.ScriptBody" },
39+
@{ Name = "PreDeploy"; Property = "Octopus.Action.CustomScripts.PreDeploy.ps1" },
40+
@{ Name = "Deploy"; Property = "Octopus.Action.CustomScripts.Deploy.ps1" },
41+
@{ Name = "PostDeploy"; Property = "Octopus.Action.CustomScripts.PostDeploy.ps1" }
42+
)
43+
44+
foreach ($stepTemplate in $stepTemplates)
45+
{
46+
$relativePath = "step-templates/$([System.IO.Path]::GetFileName($stepTemplate))";
47+
$templateName = [System.IO.Path]::GetFileNameWithoutExtension($stepTemplate);
48+
49+
$oldJson = $null;
50+
try
51+
{
52+
$oldText = git show "${CompareWith}:${relativePath}" 2>$null;
53+
if ($LASTEXITCODE -eq 0 -and $oldText)
54+
{
55+
$oldJson = ConvertFrom-Json -InputObject ($oldText -join "`n");
56+
}
57+
}
58+
catch
59+
{
60+
Write-Host "No previous version found for '$templateName' at $CompareWith" -ForegroundColor Yellow;
61+
continue;
62+
}
63+
64+
$newText = Get-Content -Path $stepTemplate -Raw;
65+
$newJson = ConvertFrom-Json -InputObject $newText;
66+
67+
# Get file extension from syntax
68+
$syntax = Get-OctopusStepTemplateProperty -StepJson $newJson -PropertyName "Octopus.Action.Script.Syntax" -DefaultValue "PowerShell";
69+
$fileType = Get-OctopusStepTemplateFileType -Syntax $syntax;
70+
71+
foreach ($prop in $scriptProperties)
72+
{
73+
$oldValue = Get-OctopusStepTemplateProperty -StepJson $oldJson -PropertyName $prop.Property;
74+
$newValue = Get-OctopusStepTemplateProperty -StepJson $newJson -PropertyName $prop.Property;
75+
76+
if ([string]::IsNullOrEmpty($oldValue) -and [string]::IsNullOrEmpty($newValue)) { continue; }
77+
78+
$oldFile = [System.IO.Path]::Combine($outputPath, "$templateName.$($prop.Name).old$fileType");
79+
$newFile = [System.IO.Path]::Combine($outputPath, "$templateName.$($prop.Name).new$fileType");
80+
81+
Set-Content -Path $oldFile -Value $oldValue -NoNewline;
82+
Set-Content -Path $newFile -Value $newValue -NoNewline;
83+
84+
Write-Host "Created: $($prop.Name)" -ForegroundColor Cyan;
85+
Write-Host " Old: $oldFile";
86+
Write-Host " New: $newFile";
87+
}
88+
}
89+
90+
Write-Host "";
91+
Write-Host "Files written to: $outputPath" -ForegroundColor Green;

0 commit comments

Comments
 (0)